These functions send messages to and receive messages from hand readers. These functions are not usually used by applications. The routines deal with raw, packed hand reader data (as described in the ID3D Software Manual) and unless you are thoroughly familiar with the hand reader data formats, these functions should not be used unless there is a specific reason to do so. Instead use the higher level functions that deal with more “programmer friendly” data formats.
rsiSendMessage
RSI_RESULT rsiSendMessage (RSI_CHANNEL chnl, RSI_COMMAND_TYPE type, LPBYTE data, WORD length);
RSI_CHANNEL chnl
The handle returned by rsiInstallChannel.
RSI_COMMAND_TYPE type
The hand reader message to send. Valid messages are:
RSI_CMD_RESUME RSI_CMD_ABORT
RSI_CMD_HERE_IS_USER_RECORD RSI_CMD_SEND_USER_RECORD RSI_CMD_HERE_IS_SETUP_DATA RSI_CMD_REMOVE_USER_RECORD RSI_CMD_CALIBRATE
RSI_CMD_CLEAR_USER_DATABASE RSI_CMD_SEND_CALIBRATION_DATA RSI_CMD_SEND_LAST_USER_RECORD RSI_CMD_HERE_IS_TIME
RSI_CMD_SEND_RESULTS RSI_CMD_SEND_STATUS_CRC RSI_CMD_ENTER_IDLE_MODE RSI_CMD_HERE_IS_BANK_NUMBER RSI_CMD_HERE_IS_DATA_BANK RSI_CMD_SEND_DATA_BANK RSI_CMD_ENROLL_USER
Chapter
4
P R O T O T Y P E
A R G U M E N T S
RSI_CMD_VERIFY_USER_EXTERNAL RSI_CMD_SEND_TEMPLATE
RSI_CMD_UPDATE_NV_RAM RSI_CMD_SEND_DATA_LOG
RSI_CMD_SEND_PREV_DATA_LOG RSI_CMD_SEND_SETUP_DATA RSI_CMD_OUTPUT_CONTROL
RSI_CMD_HERE_IS_DISPLAY_MESSAGE RSI_CMD_VERIFY_USER_INTERNAL RSI_CMD_NEXT_MESSAGE_TIME_ZONE RSI_CMD_HERE_ARE_TIME_ZONES RSI_CMD_DISPLAY_CODED_MESSAGE
RSI_CMD_NEXT_MESSAGE_BELL_SCHEDULE RSI_CMD_HERE_IS_BELL_SCHEDULE
LPBYTE data
Raw, packed hand reader data.
WORD length Length of the data.
Sends a command to the hand reader.
RSI_SUCCESS if successful.
RSI_INVALID_CHANNEL if the channel handle is not valid.
RSI_NO_CONNECTION if the Level 0 API was not used correctly.
RSI_COM_TIMEOUT if a time-out occurred before the entire message was sent.
The receive buffer is flushed before the message is sent.
No data checking or translation is performed. The data sent must be raw, packed hand reader data. Therefore the data format (as specified in the ID3D Software Manual) must be adhered to exactly.
The rsiLookupCommandInfo and/or rsiLookupCommandDataSize functions should be used to ensure data and length are valid for type.
See rsi_cmd.h for a complete commands list.
rsiGetResponse
RSI_RESULT rsiGetResponse (RSI_CHANNEL chnl, RSI_RESPONSE FAR* resp);
D E S C R I P T I O N R E T U R N S
N O T E S
P R O T O T Y P E
RSI_CHANNEL chnl
The handle returned by rsiInstallChannel.
RSI_RESPONSE FAR* resp
A pointer to a RSI_RESPONSE structure that will receive the hand reader’s response.
Attempts to read a response from the hand reader.
RSI_SUCCESS if successful.
RSI_INVALID_CHANNEL if the channel handle is not valid.
RSI_NO_CONNECTION if the Level 0 API was not used correctly.
RSI_COM_TIMEOUT if a time-out occurred before the entire response was received.
RSI_BAD_CRC if the message was received with a bad CRC.
RSI_ERROR_COM if an unknown error occurred.
It is the applications responsibility to set the buffer member of resp to point to valid buffer of sufficient size. The buflen member must be set to the length of the buffer. Use the rsiLookupResponseInfo function to determine the size of the buffer needed for the expected response. The function will not accept responses with a data size other than buflen.
The buffer member will contain raw, packed hand reader data if successful. This allows application can copy buffer to a data file in a compact form.
rsiParseResponse
RSI_RESULT rsiParseResponse (RSI_CHANNEL chnl, RSI_RESPONSE FAR* resp);
RSI_CHANNEL chnl
The handle returned by rsiInstallChannel.
RSI_RESPONSE FAR* resp
A pointer to a RSI_RESPONSE structure that was filled by rsiGetResponse.
Converts the raw, packed hand reader data in the response structure into “programmer friendly” structures according to the response type.
RSI_SUCCESS if successful.
RSI_INVALID_CHANNEL if the channel handle is not valid.
RSI_PARSE_OVERFLOW if the buflen member is larger than the data size for the type member.
RSI_PARSE_UNDERFLOW if the buflen member is smaller than the data size for the
A R G U M E N T S
type member.
RSI_DATA_ERROR if the buffer or data members are not valid pointers.
It is the application’s responsibility to ensure the buffer member of resp is a valid buffer. It is also the application’s responsibility to set one of the data union members to point to a valid structure. The dataSize member must also be set by the applications.
While buflen is the size of the raw, packed hand reader data, dataSize is the size of the “programmer friendly” structure.
rsiLookupCommandInfo
WORD rsiLookupCommandInfo (RSI_COMMAND_TYPE type, RSI_RESPONSE_TYPE& resp);
RSI_COMMAND_TYPE type
The hand reader command message to retrieve information for.
RSI_RESPONSE_TYPE& resp
Variable to store the expected hand reader response message to the command message.
Retrieves information about the various hand reader command messages.
The size of the expected data for the command message is returned.
The data size is for the raw, packed hand reader data and not the
“programmer friendly” structures.
Use this function to determine which hand reader response to expect and allocate the appropriate buffers for rsiSendMessage.
rsiLookupCommandDataSize
WORD rsiLookupCommandDataSize (RSI_COMMAND_TYPE type);
RSI_COMMAND_TYPE type
The hand reader command message to retrieve information for.
Retrieves the length of the expected data for the various hand reader command messages.
N O T E S
P R O T O T Y P E
A R G U M E N T S
D E S C R I P T I O N
R E T U R N S
N O T E S
P R O T O T Y P E A R G U M E N T S
D E S C R I P T I O N
The size of the expected data for the command message is returned.
The data size is for the raw, packed hand reader data and not the
“programmer friendly” structures.
This function is basically rsiLookupCommandInfo, but it doesn’t provide the response message to expect.
Use this function or rsiLookupCommandInfo to allocate the appropriate buffers and structures for rsiSendMessage.
rsiLookupResponseInfo
WORD rsiLookupResponseInfo (RSI_RESPONSE_TYPE resp);
RSI_RESPONSE_TYPE resp
The hand reader response message to retrieve information for.
Retrieves information about the various hand reader response messages.
The size of the expected data for the response message is returned.
The data size is for the raw, packed hand reader data and not the
“programmer friendly” structures.
Use this function to set the buflen member and allocate the buffer member of the RSI_RESPONSE structure passed to rsiGetResponse.
R E T U R N S
N O T E S
P R O T O T Y P E A R G U M E N T S
D E S C R I P T I O N
R E T U R N S
N O T E S