API

API Overview​

Define the following APIs using the __stdcall (WINAPI) calling convention.

API Name	Purpose
UserCallOut_GetUserCfg	Retrieve callout custom parameters
UserCallOut_SetUserCfg	Set callout custom parameters
UserCallOut_ChInit	Initialize channel information
UserCallOut_ChDeInit	Finalize channel information
UserCallOut_MonStart	Notification that monitoring has started
UserCallOut_CreMacDaPreFixReq	Request prefix data for MAC generation (transmit)
UserCallOut_CreMacDaPostFixReq	Request postfix data for MAC generation (transmit)
UserCallOut_TruncatedFvReq	Request truncated FV data
UserCallOut_MacDaPreFixReq	Request prefix data for MAC verification
UserCallOut_MacDaPostFixReq	Request postfix data for MAC verification
UserCallOut_AfterMacVerify	Notify MAC verification result
UserCallOut_AfterTransMsg	Notify completion of MAC transmit request
UserCallOut_MonStop	Notification that monitoring has stopped

Details for each API follow the format below. Return MPX_COUT_OK (DWORD) from every API (see the constant definitions for error codes).

Field	Description
Signature	<Return type> <API name> (<arguments>, ...)
Arguments	<Type> (*1)	(Name)	<in/out> (*2)	Argument description
Function	API behavior
Call timing	When the API is called
Notes	Additional information

*1: For values set in or retrieved from structures, see Structure Definitions.
*2: Use “in” if the value is supplied when the function is called; “out” if the function populates the value.

UserCallOut_GetUserCfg​

Notifies the security plug-in of the callout custom parameters.

Field	Description
Signature	DWORD UserCallOut_GetUserCfg ( StCustomParamCfg CalloutCfgs[] , LPDWORD CfgNum )
Arguments	StCustomParamCfg []	CalloutCfgs	out	Array of parameter information
	LPDWORD	CfgNum	out	Number of parameter entries
Function	Notifies the security plug-in of the callout custom parameters.
Call timing	Called when the Callout Custom Param Setting dialog is displayed.

UserCallOut_SetUserCfg​

Receives callout custom parameters from the security plug-in.

Field	Description
Signature	DWORD UserCallOut_SetUserCfg ( StCustomParamCfg CalloutCfgs[] , DWORD CfgNum )
Arguments	StCustomParamCfg []	CalloutCfgs	in	Array of parameter information
	DWORD	CfgNum	in	Number of parameter entries
Function	Receives callout custom parameters from the security plug-in.
Call timing	Called when the OK button is clicked in the Callout Custom Param Setting dialog.

UserCallOut_ChInit​

Performs the required initialization for each channel.

Field	Description
Signature	DWORD UserCallOut_ChInit ( DWORD Ch , DWORD InnerCh )
Arguments	DWORD	Ch	in	Channel
	DWORD	InnerCh	in	Internal channel
Function	Performs the required initialization for each channel.
Call timing	Called once per channel immediately before the transmit and receive threads start when monitoring begins.

UserCallOut_ChDeInit​

Performs the required cleanup for each channel.

Field	Description
Signature	DWORD UserCallOut_ChDeInit ( DWORD Ch , DWORD InnerCh )
Arguments	DWORD	Ch	in	Channel
	DWORD	InnerCh	in	Internal channel
Function	Performs the required cleanup for each channel.
Call timing	Called once per channel immediately before the transmit and receive threads stop when monitoring ends.

UserCallOut_MonStart​

Notifies that monitoring has started.

Field	Description
Signature	DWORD UserCallOut_MonStart ( DWORD Ch , DWORD InnerCh , DWORD ThreadType , StMsgConfig PrefixCfg , StMsgConfig PostfixCfg )
Arguments	DWORD	Ch	in	Channel
	DWORD	InnerCh	in	Internal channel
	DWORD	ThreadType	in	Calling thread
	StMsgConfig	PrefixCfg	in	Security settings for the prefix
	StMsgConfig	PostfixCfg	in	Security settings for the postfix
Function	Notifies that monitoring has started.
Call timing	Called by both the transmit and receive threads of each channel with message authentication enabled when monitoring starts.
Notes	For ThreadType values, see Thread Types.

UserCallOut_CreMacDaPreFixReq​

Requests prefix data used to generate the MAC for transmission.

Field	Description
Signature	DWORD UserCallOut_CreMacDaPreFixReq ( StFrameCfg FrameCfg , StFrameInfo FrameInfo , LPBYTE Prefix , LPDWORD PrefixLen )
Arguments	StFrameCfg	FrameCfg	in	Transmit frame configuration
	StFrameInfo	FrameInfo	in	Transmit frame information
	LPBYTE	Prefix	out	Pointer to the prefix output buffer
	LPDWORD	PrefixLen	out	Pointer to the prefix length (bytes)
Function	Requests prefix data used to generate the MAC for transmission.
Call timing	Called by the transmit thread while generating a transmit message, before MAC generation.

UserCallOut_CreMacDaPostFixReq​

Requests postfix data used to generate the MAC for transmission.

Field	Description
Signature	DWORD UserCallOut_CreMacDaPostFixReq ( StFrameCfg FrameCfg , StFrameInfo FrameInfo , LPBYTE Postfix , LPDWORD PostfixLen )
Arguments	StFrameCfg	FrameCfg	in	Transmit frame configuration
	StFrameInfo	FrameInfo	in	Transmit frame information
	LPBYTE	Postfix	out	Pointer to the postfix output buffer
	LPDWORD	PostfixLen	out	Pointer to the postfix length (bytes)
Function	Requests postfix data used to generate the MAC for transmission.
Call timing	Called by the transmit thread while generating a transmit message, before MAC generation.

UserCallOut_TruncatedFvReq​

Requests the truncated FV to include in the message.

Field	Description
Signature	DWORD UserCallOut_TruncatedFvReq ( StFrameCfg FrameCfg , StFrameInfo FrameInfo , StPrePostData Prefix , StPrePostData Postfix , LPBYTE TruncatedFv , LPDWORD TruncatedFvLen )
Arguments	StFrameCfg	FrameCfg	in	Transmit frame configuration
	StFrameInfo	FrameInfo	in	Transmit frame information
	StPrePostData	Prefix	in	Prefix used for MAC generation
	StPrePostData	Postfix	in	Postfix used for MAC generation
	LPBYTE	TruncatedFv	out	Pointer to the truncated FV output buffer
	LPDWORD	TruncatedFvLen	out	Pointer to the truncated FV length (bytes)
Function	Requests the truncated FV to include in the message.
Call timing	Called by the transmit thread immediately before sending the request to the MicroPeckerX unit.

UserCallOut_MacDaPreFixReq​

Requests prefix data used to generate the MAC for verification.

Field	Description
Signature	DWORD UserCallOut_MacDaPreFixReq ( DWORD VeryAttemptCnt , StFrameCfg FrameCfg , StFrameInfo FrameInfo , LPBYTE Prefix , LPDWORD PrefixLen )
Arguments	DWORD	VeryAttemptCnt	in	Verification attempt count
	StFrameCfg	FrameCfg	in	Transmit frame configuration
	StFrameInfo	FrameInfo	in	Transmit frame information
	LPBYTE	Prefix	out	Pointer to the prefix output buffer
	LPDWORD	PrefixLen	out	Pointer to the prefix length (bytes)
Function	Requests prefix data used to generate the MAC for verification.
Call timing	Called by the monitor thread before MAC verification.

UserCallOut_MacDaPostFixReq​

Requests postfix data used to generate the MAC for verification.

Field	Description
Signature	DWORD UserCallOut_MacDaPostFixReq ( DWORD VeryAttemptCnt , StFrameCfg FrameCfg , StFrameInfo FrameInfo , LPBYTE Postfix , LPDWORD PostfixLen )
Arguments	DWORD	VeryAttemptCnt	in	Verification attempt count
	StFrameCfg	FrameCfg	in	Transmit frame configuration
	StFrameInfo	FrameInfo	in	Transmit frame information
	LPBYTE	Postfix	out	Pointer to the postfix output buffer
	LPDWORD	PostfixLen	out	Pointer to the postfix length (bytes)
Function	Requests postfix data used to generate the MAC for verification.
Call timing	Called by the monitor thread before MAC verification.

UserCallOut_AfterMacVerify​

Notifies the result of MAC verification.

Field	Description
Signature	DWORD UserCallOut_AfterMacVerify ( StFrameCfg FrameCfg , StFrameInfo FrameInfo , StPrePostData Prefix , StPrePostData Postfix , DWORD VerifyResult )
Arguments	StFrameCfg	FrameCfg	in	Transmit frame configuration
	StFrameInfo	FrameInfo	in	Transmit frame information
	StPrePostData	Prefix	in	Prefix used for MAC generation
	StPrePostData	Postfix	in	Postfix used for MAC generation
	DWORD	VerifyResult	in	MAC verification result
Function	Notifies the result of MAC verification.
Call timing	Called by the monitor thread after MAC verification.

UserCallOut_AfterTransMsg​

Notifies that the MAC transmit request has completed.

Field	Description
Signature	DWORD UserCallOut_AfterTransMsg ( StFrameCfg FrameCfg , StFrameInfo FrameInfo )
Arguments	StFrameCfg	FrameCfg	in	Transmit frame configuration
	StFrameInfo	FrameInfo	in	Transmit frame information
Function	Notifies that the MAC transmit request has completed.
Call timing	Called immediately after submitting the transmit request to the MicroPeckerX unit.

UserCallOut_MonStop​

Notifies that monitoring has stopped.

Field	Description
Signature	DWORD UserCallOut_MonStop ( DWORD Ch , DWORD InnerCh , DWORD ThreadType , StMsgConfig PrefixCfg , StMsgConfig PostfixCfg )
Arguments	DWORD	Ch	in	Channel
	DWORD	InnerCh	in	Internal channel
	DWORD	ThreadType	in	Calling thread
	StMsgConfig	PrefixCfg	in	Security settings for the prefix
	StMsgConfig	PostfixCfg	in	Security settings for the postfix
Function	Notifies that monitoring has stopped.
Call timing	Called by both the transmit and receive threads of each channel with message authentication enabled when monitoring stops.
Notes	For ThreadType values, see Thread Types.