rsidll

(1)

RECOGNITION SYSTEMS, INC.

ID3D Hand Reader Software Development Kit

Version

(2)

I D 3 D H A N D R E A D E R S O F T W A R E D E V E L O P M E N T K I T

Recognition Systems, Inc. Campbell, CA 95008

(3)

Introduction____________________________________5 Overview_______________________________________9 Level 0 API____________________________________11 rsiInstallChannel______________11 rsiOpenDirectChannel_________11 rsiSetModemInitString_________12 rsiOpenModemChannel________13 rsiOpenCustomChannel________13 rsiSetHandReader_____________14 rsiGetHandReader_____________15 rsiCloseChannel_______________15 rsiCOMDtr_____________________16 rsiCOMRts_____________________16 rsiCOMCts_____________________16 rsiCOMDsr_____________________17 rsiCOMRing___________________17 rsiCOMCarrier_________________17 rsiCOMLineBreak______________18 rsiCOMHardwareOverrun______18 rsiCOMBaudRate______________18 rsiCOMDataLength____________19 rsiCOMParity__________________19 rsiCOMStopBits________________20 rsiCOMRXFlush________________20 rsiCOMTXFlush________________21 rsiCOMRXCount_______________21 rsiCOMTXCount_______________21 rsiCOMGetChar________________22 rsiCOMGetBuffer______________22 rsiCOMGetString______________23 rsiCOMPutChar________________23 rsiCOMPutBuffer_______________24 rsiCancelPendingIO____________24 rsiStartupWsock_______________25 rsiCleanupWsock______________26 rsiInitWsock___________________26 rsiCloseWsock_________________27 rsiPing________________________27 rsiSendMessage_______________30 rsiGetResponse_______________31 rsiParseResponse______________32 rsiLookupCommandInfo________33 rsiLookupCommandDataSize___33 rsiLookupResponseInfo________34 Level 2 API________________35 rsiResume____________________35 rsiAbortCommand_____________35 rsiHereIsUserRecord___________35 rsiSendUserRecord____________35 rsiHereIsSetupData____________36 rsiRemoveUserRecord_________36 rsiCalibrate____________________36 rsiClearUserDataBase_________36 rsiSendCalibrationData________36 rsiSendLastUserRecord________36 rsiHereIsTime_________________37 rsiGetTime____________________37 rsiSendResults________________37 rsiSendStatusCRC_____________37 rsiEnterIdleMode______________37 rsiEnterIdleMode2_____________37 rsiBeep_______________________38 rsiHereIsBankNumber_________38 rsiHereIsDataBank_____________38 rsiSendDataBank______________38 rsiEnrollUser__________________38 rsiVerifyOnExternalData_______38 rsiSendTemplate______________39 rsiUpdateNVRam______________39 rsiSendDataLog_______________39 rsiSendPreviousDataLog_______39 rsiSendSetupData_____________39 rsiOutputControl_______________39 rsiHereIsDisplayMessage______40 rsiPrinterPassThrough_________40

(4)

rsiDisplayCodedMessage______41 rsiNextMessageIsBellScheduleTable 41 rsiHereIsBellScheduleTable____41 Level 3 API________________42 rsiGetUserRecord 42 rsiGetLastUserRecord__________42 rsiGetStatus___________________43 rsiSetBellSchedule_____________43 rsiSetTimeZoneTable__________44 rsiGetSetupData_______________44 rsiGetDataLogElement_________44 rsiGetCalibrationData__________45 rsiGetLastTemplate____________45 rsiGetResults__________________46 rsiGetDataBank_______________46 rsiSetDataBank________________47

Data Conversion API_____48

rsiUserRecordToData__________48 rsiDataToUserRecord__________48 rsiSetupDataToData___________49 rsiDataToSetupData___________49 rsiTimeToData________________50 rsiDataToTime________________50 rsiDataToStatus_______________50 rsiTextToID____________________51 rsiIDToText____________________51 rsiTextToMessage_____________52 rsiTimeZoneTableToData______52 rsiBellScheduleToData_________52 rsiDisplayMessageToData______53 rsiDataToDataLog_____________53 rsiTextToTemplate____________54 rsiTemplateToText____________54 Miscellaneous Functions_55 rsiGetDataError_______________55 rsiGetComError________________56 rsiSleep_______________________56 rsiSetICD______________________57 rsiGetICD_____________________57

Data Types & Sizes______58

RSI_RESPONSE________________58 RSI_USER_RECORD____________60 RSI_DISPLAY_MESSAGE________61 RSI_SETUP_DATA______________61 RSI_STATUS___________________63 RSI_CALIBRATION_DATA_______63 RSI_RESULTS__________________64 RSI_LAST_TEMPLATE___________64 RSI_BELL_SCHEDULE_ELEMENT_64 RSI_BELL_SCHEDULE__________65 RSI_TIME_ZONE_INTERVAL_____65 RSI_TIME_ZONE_ELEMENT_____66 RSI_HOLIDAY_ELEMENT________66 RSI_TIME_ZONE_TABLE________66 RSI_DATA_LOG_ELEMENT______67 RSI_DATA_LOG_1______________68 RSI_DATA_LOG_2______________69 RSI_TA_7______________________70 Level 2 API________________82 rsiAddUserMessage____________82 rsiClearUserMessages_________83 rsiHereIsExtSetupData_________83 rsiHereIsExtUserRecord________84 rsiLoadFkeyFromFile___________84 rsiHereIsFkeyData_____________85 rsiRemoveUserMessage_______85 rsiSendExtSetupData__________86 rsiSetExtUserData_____________86 rsiSetUserData________________87 Level 3 API________________88 rsiGetExtSetupData___________88 rsiAllocResponseBuffer________88 rsiDeAllocResponseBuffer______88 rsiReadResponseBuffer________89 rsiGetExtUserRecord__________89 rsiGetOemCode_______________90 rsiGetReaderInfo______________90 rsiMemoryIs___________________91 rsiMemoryIs128K, rsiMemoryIs256K, rsiMemoryIs640K______________91 rsiModelIs_____________________91 rsiModelIsHK, rsiModelIsHKCR, rsiModelIsHKII, rsiModelIsHP, rsiModelIsHP2K, rsiModelIsHP3K, rsiModelIsHP4K, rsiModelIsSpecial 92

Data Conversion API_____93

rsiDataToExtSetupData________93 rsiDataToExtUserRecord_______93 rsiDataToReaderInfo___________94 rsiExtSetupDataToData________94 rsiExtUserDataToData_________94 rsiExtUserRecordToData_______95 rsiPackTI______________________95 rsiUnpackTI___________________96

DLL Functions and Reader Commands Cross Reference ____________________________97

(5)

Introduction

About RSI DLL

RSI DLL is a Windows Dynamic Linking Library which provides an interface for Windows applications to interact with RSI ID3D hand readers. RSI DLL supports communication with hand readers through direct serial links, Hayes compatible modems, Ethernet connection, or any serial port device. RSI DLL contains an API set that simplifies hand reader communication by providing both low and high level routines.

There are actually two versions of RSI DLL, a 16-bit version and a 32-bit version. The physical DLL files are named RSIDLL16.DLL and RSIDLL32.DLL, respectively. The two versions support the exact same API. Thus source code written for one platform can be ported to the other simply by re-linking.

Note that for serial link connections under Windows, the RSI DLL can support RS-232

direct connection, 4-wire RS-422 network configuration, or 2-wire RS-485 network configuration connected to an RSI DC103 Data Converter.

What’s New

2.4.2

Includes miscellaneous functions. See readme.txt for details.

NOTE for modem connection only: It has been observed that failure (when calling rsiLoadFkeyFromFile, rsiHereIsFkeyData or rsiSetDataBank with a big data block of 4K) may occur in some modem models. To resolve this problem, disable data compression. For Hayes compatible modem, the command is %C0. Check your modem manual for proper command to disable data compression and use rsiSetModemInitString() to send the initialization string.

2.4.1

Includes module file RSIDLL32.BAS containing the RSIDLL32 function declarations for

Chapter

(6)

Visual Basic and a VB test program called WHVB.EXE. 2.4

Includes new commands for new readers models HP2K, HP3K, HP4K, HKCR and HKII. 2.3.1

Pending DLL operations can now be canceled (rsiCancelPendingIO).

Block output (rsiCOMPutbuffer()) is now done as single I/O operation rather than

character-at-a-time to improve throughput.

The main handreader message reception function (rsiGetResponse()) now does

reads using block input rather than character-at-a-time input to improve efficiency. 2.2

Add Ethernet connection. 2.0

RSI DLL now supports simultaneous multiple channels: applications can open and use multiple communication ports at the same time.

RSI DLL is now also thread-safe. This means multi-threaded applications can call the API from different threads. Applications can pass channel handles between threads to allow multiple threads to access the same channel. However, it is the application’s responsibility to ensure more than one thread does not use the same channel at the same time. This can be done by using the Win32 synchronization functions to protect the channel handle.

RSI DLL can now be used from any programming language that supports Windows DLLs, including Visual C++, Visual Basic, Visual Basic for Applications, Delphi, and many more. This manual and the header file RSI_CMD.H are written assuming C or C+ + will be the programming language used. To use RSI DLL with another language, you will need to convert RSI_CMD.H to that language.

Because of the new functionality, there have been some changes in the API. The most significant is that most of the functions now take a channel handle as their first parameter. rsiInstallChannel returns this channel handle instead of a RSI_RESULT. The data conversion functions also now return a RSI_DATA_ERROR instead of a RSI_RESULT, eliminating the need for using rsiGetDataError when working with the data conversion routines. A file called RSI_OLD.H is provided to ease the transition from previous versions of the DLL. The include file contains overloaded C++ functions

(7)

that minimize the number of code changes necessary to successfully compile your program with the new RSI DLL. Include RSI_OLD.H after including RSI_CMD.H. See RSI_OLD.H for more details.

(8)

Chapter

(9)

Overview

Getting Started

The first step to using RSI DLL is including it in your project. The procedure for this is different for each compiler. RSI_CMD.H contains the API declarations and must be included for the compiler. You may also need to use the RSI DLL export library with your linker.

Before you can communicate with the hand reader, you must initialize RSI DLL. This is done by calling several Level 0 API functions in the following order:

1. rsiInstallChannel (the returned handle must be saved and used with the rest of the API)

2. rsiOpen…Channel (use one of the three available variations of this function)

3. rsiSetHandReader

Once these three functions have been called, in that order, the DLL API is ready for use. You cannot use the API until these three functions have been called successfully.

Note, however, that after the first call to rsiSetHandReader, it may be called any number of additional times—with different reader addresses—without re-installing or re-opening the channel. This is how you access different readers in a single session.

After you are done using the API, you must de-initialize the DLL. This is usually done in the application’s clean up or exit procedure by calling:

rsiCloseChannel

See the documentation for each of these functions for more information.

(10)

Getting Help

Aside from this reference manual which describes and prototypes each API function, you will probably also need the ID3D Hand

Reader Software Manual and ID3D-R Operating and Installation Manual.

A program called WinHand is provided as an example application. You should thoroughly study this program before starting your own project. It illustrates the usage of nearly all the RSI DLL API and is a good starting point. WinHand comes in 16-bit and 32-bit versions named WinHand16 and WinHand32, respectively.

It is also very beneficial, and sometimes necessary, to look at RSI_CMD.H. This include file contains the declarations for the entire RSI DLL API.

A test program written in Visual Basic called WHVB is also provided to illustrate the calls to the functions declared in module RSIDLL32.BAS. Refer to RSIDLLVB.DOC for a complete description of this program. For developing your real VB application, simply add module RSIDLL32.BAS to your project.

Highlights on Establishing Different

Connections

Following is a summary on how to use Ethernet functions, in comparision to Direct or Modem connection:

Ethernet Direct Modem

1. rsiStartupWsockrsiInstallChannel rsiInstallChannel rsiInitWsock rsiOpenDirectChannel

rsiOpenModemChannel

2. Once a Direct, Modem or Ethernet connection is established, other related communication functions can be called exactly the same way in these three types of connections.

(11)

rsiCleanupWsock

Level 0 API

Initialization and Communication

The following functions are used to initialize and setup the DLL. Some must be called before and after using the DLL. Others provide the application an interface to the underlying communications channel (serial port).

rsiInstallChannel

RSI_CHANNEL rsiInstallChannel (int com); int com

Communications port number to use minus 1. For example, 0 for COM1 and 1 for COM2.

Initializes the DLL for use with the specified COM port. As such, it

must be called before any of the other routines. The handle it

returns must be saved and passed to the other RSI DLL functions. A handle to the opened channel if successful.

NULL if the channel could not be opened.

No logic, except for NULL checking, should be performed on the returned handle as the definition of RSI_CHANNEL may change in future versions of the DLL.

rsiOpenDirectChannel

RSI_RESULT rsiOpenDirectChannel (RSI_CHANNEL chnl,

Chapter

3

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

(12)

long baud);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. long baud

Baud rate between 10 and 115200 to connect at.

Configures the DLL to communicate through a direct serial link to the hand reader at the specified baud rate. This function should be called immediately after rsiInstallChannel. Until this, or one of the other rsiOpen…Channel functions, is called, NONE of the other routines can be used.

RSI_SUCCESS if successful.

RSI_INVALID_CHANNEL if the channel handle is not valid. RSI_ERROR_COM if unsuccessful.

The specified baud rate should be the same as what the hand reader is configured for.

rsiSetModemInitString

RSI_RESULT rsiSetModemInitString (RSI_CHANNEL chnl, LPTSTR init_string);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. LPTSTR init_string

A pointer to the buffer holding the modem init. string to send. Send the init. string to the modem.

RSI_INVALID_CHANNEL if the channel handle is not valid. rsiSetModemInitString is optional.

If you wish to customize the modem init. string, rsiSetModemInitString should be called before

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 R E T U R N S N O T E S

(13)

rsiOpenModemChannel. If rsiSetModemInitString is not called, a default, Hayes-compatible modem init string is used.

rsiOpenModemChannel

RSI_RESULT rsiOpenModemChannel (RSI_CHANNEL chnl, long baud, LPTSTR number, BOOL speaker);

RSI_CHANNEL chnl

Baud rate between 10 and 115200 to connect at. LPTSTR number

The phone number to dial. BOOL speaker

TRUE to turn the speaker on while dialing or FALSE to turn the speaker off while dialing.

Configures the DLL to communicate through a standard Hayes compatible modem. The DLL configures the modem and dials out to establish the connection. This function should be called immediately after rsiInstallChannel. Until this, or one of the other rsiOpen…Channel functions, is called, NONE of the other routines can be used.

The specified baud rate should be the same as what the hand reader modem is configured for.

rsiOpenCustomChannel

RSI_RESULT rsiOpenCustomChannel (RSI_CHANNEL chnl); RSI_CHANNEL chnl 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

(14)

The handle returned by rsiInstallChannel.

Configures the DLL to communicate through a non-standard modem. The DLL does not configure the modem or dial out. Until this, or one of the other rsiOpen…Channel functions, is called, NONE of the other routines can be used.

Call rsiInstallChannel first, then use the rsiCOM… functions listed later in the chapter to configure the modem and dial out. After a connection has been established, call this function to enable the hand reader routines in the DLL. It is the applications responsibility to ensure a valid connection.

rsiSetHandReader

RSI_RESULT rsiSetHandReader (RSI_CHANNEL chnl, BYTE addr, RSI_STATUS FAR* status);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. BYTE addr

A reader address between 0x00 and 0xFE, but not 0xAA. RSI_STATUS FAR* status

A pointer to a buffer to hold the status of the reader; this can be NULL.

Directs all further hand reader messages to be sent to the hand reader at this address. It also sets the hand reader in CRC mode. This function should be called immediately after one of the rsiOpen…Channel routines.

RSI_INVALID_CHANNEL if the channel handle is not valid. RSI_ERROR_DATA if the reader address is invalid.

RSI_ERROR_COM if there is no hand reader at the address.

By default, address 0x01 is used. But if this function is not called,

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 R E T U R N S N O T E S

(15)

the reader at address 0x01 may or may not be in CRC mode and messages between the host and the reader may not work.

rsiGetHandReader

BYTE rsiGetHandReader (RSI_CHANNEL chnl); RSI_CHANNEL chnl

Gets the hand reader address messages are being sent to. The current hand reader address.

By default, the address 0x01 is used until changed by rsiSetHandReader.

rsiCloseChannel

RSI_RESULT rsiCloseChannel (RSI_CHANNEL chnl); RSI_CHANNEL chnl

Closes the currently open channel. This function should be called in the application’s clean-up or exit procedure. It may also be used to close the channel and open a new one. After this function has been called, NONE the other routines will work.

RSI_INVALID_CHANNEL if the channel handle is not valid.

If rsiOpenDirectChannel was used to open the channel, the serial port is closed.

If rsiOpenModemChannel was used, the modem is hung up and the port is closed.

If rsiOpenCustomChannel was used, the serial port is closed. It is the application’s responsibility to hang up and disconnect the modem before calling this function.

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 R E T U R N S N O T E S

(16)

rsiCOMDtr

BOOL rsiCOMDtr (RSI_CHANNEL chnl, BOOL val); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. BOOL val

The new setting (TRUE = on or FALSE = off) or -1 to retrieve the current setting.

Gets or sets the state of the DTR signal.

The current value or the new value (if successful).

This function should only be called when using rsiOpenCustomChannel.

rsiCOMRts

BOOL rsiCOMRts (RSI_CHANNEL chnl, BOOL val); RSI_CHANNEL chnl

Gets or sets the state of the RTS signal.

rsiCOMCts

BOOL rsiCOMCts (RSI_CHANNEL chnl); RSI_CHANNEL chnl

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 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

(17)

Gets the state of the CTS signal. The current value.

rsiCOMDsr

BOOL rsiCOMDsr (RSI_CHANNEL chnl); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. Gets the state of the DSR signal.

The current value.

rsiCOMRing

BOOL rsiCOMRing (RSI_CHANNEL chnl); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. Gets the state of the RI signal.

The current value.

rsiCOMCarrier

BOOL rsiCOMCarrier (RSI_CHANNEL chnl); RSI_CHANNEL chnl

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 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 P R O T O T Y P E A R G U M E N T S

(18)

Gets or sets the state of the CD signal. The current value.

rsiCOMLineBreak

BOOL rsiCOMLineBreak (RSI_CHANNEL chnl, BOOL val); RSI_CHANNEL chnl

Gets or sets the state of the break signal.

rsiCOMHardwareOverrun

BOOL rsiCOMHardwareOverrun (RSI_CHANNEL chnl); RSI_CHANNEL chnl

Gets the state of the receiver overrun flag in the port. The current value.

rsiCOMBaudRate

long rsiCOMBaudRate (RSI_CHANNEL chnl, long baud);

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 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 P R O T O T Y P E

(19)

RSI_CHANNEL chnl

Baud rate between 10 and 115200 or -1 to retrieve the current baud rate.

Gets or sets the baud rate.

The current or new baud rate or a negative value if unsuccessful. This function should only be called when using rsiOpenCustomChannel.

rsiCOMDataLength

int rsiCOMDataLength (RSI_CHANNEL chnl, int dlen); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. int dlen

Data length between 5 and 8 or -1 to retrieve the current data length.

Gets or sets the data length.

The current or new data length or a negative value if unsuccessful. This function should only be called when using rsiOpenCustomChannel.

rsiCOMParity

char rsiCOMParity (RSI_CHANNEL chnl, char parity); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. char parity

Parity setting: ‘N’ (no parity), ‘O’ (odd parity), ‘E’ (even parity), ‘S’ (space parity), ‘M’ (mark parity).

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 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

(20)

Gets or sets the parity settings.

The current or new parity setting or a negative value if unsuccessful.

rsiCOMStopBits

int rsiCOMStopBits (RSI_CHANNEL chnl, int sbits); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. int sbits

Number of stop bits: 1 or 2.

Gets or sets the number of stop bits.

The current or new number of stop bits or a negative value if unsuccessful.

rsiCOMRXFlush

int rsiCOMRXFlush (RSI_CHANNEL chnl, unsigned count); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. unsigned count

Number of bytes to flush or 0 to flush the entire buffer. Flushes all or some of the receive buffer

0 if successful.

A negative value if unsuccessful.

This function should only be called when using rsiOpenCustomChannel. 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 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

(21)

rsiCOMTXFlush

void rsiCOMTXFlush (RSI_CHANNEL chnl); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. Flushes output buffer

NONE

rsiPing, 22 rsiSetPings, 23

rsiCOMRXCount

unsigned rsiCOMRXCount (RSI_CHANNEL chnl); RSI_CHANNEL chnl

Gets the number of characters in the receive buffer. The number of bytes in the receive buffer.

rsiCOMTXCount

unsigned rsiCOMTXCount (RSI_CHANNEL chnl); NONE

Gets the number of characters in the transmit buffer. The number of bytes in the transmit buffer.

This function should only be called when using rsiOpenCustomChannel. 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 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

(22)

rsiCOMGetChar

int rsiCOMGetChar (RSI_CHANNEL chnl, unsigned msecs); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. unsigned msecs

Number of milliseconds to wait for a character.

Attempts to retrieve a character from the receive queue. The character or a negative value if unsuccessful.

rsiCOMGetBuffer

long rsiCOMGetBuffer (RSI_CHANNEL chnl, LPBYTE buffer, unsigned count, unsigned msecs);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. LPBYTE buffer

Pointer to the buffer to receive the characters. unsigned count

Maximum number of characters to read. unsigned msecs

Attempts to read characters from the input queue. The buffer will be null terminated.

The number of characters read.

This function should only be called when using rsiOpenCustomChannel. N O T E S R E T U R N S D E S C R I P T I O N A R G U M E N T S P R O T O T Y P E N O T E S R E T U R N S D E S C R I P T I O N A R G U M E N T S P R O T O T Y P E

(23)

rsiCOMGetString

long rsiCOMGetString (RSI_CHANNEL chnl, LPBYTE buffer, unsigned count, int delim, long msecs);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. LPBYTE buffer

Pointer to the buffer to receive the string. unsigned count

Maximum number of characters to read. int delim

Delimiting character or -1 to function like rsiCOMGetBuffer. unsigned msecs

Attempts to read characters from the input queue until the delimiting character is read. The buffer will be null terminated. The number of characters read.

rsiCOMPutChar

int rsiCOMPutChar (RSI_CHANNEL chnl, BYTE outc); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. BYTE outc

Character to output.

Writes a single character to the serial port. 0 if successful.

A negative value if unsuccessful.

This function should only be called when using

(24)

rsiOpenCustomChannel.

rsiCOMPutBuffer

unsigned rsiCOMPutBuffer (RSI_CHANNEL chnl, LPBYTE buf, unsigned count);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. LPBYTE buf

Pointer to the buffer that contains the data to be sent. unsigned count

Number of bytes to send. Writes bytes to the serial port. Value of count if successful. Some other number if unsuccessful.

rsiCancelPendingIO

void rsiCancelPendingIO(RSI_CHANNEL chnl, BOOL State );

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. BOOL State

Flag indicating the state of cancellation. To cancel all current and future operations, pass TRUE. To stop canceling operations, pass FALSE..

Cancels and pending I/O operations or cancels a pending cancel. None 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 R E T U R N S

(25)

Call this function at anytime after rsiInstallChannel has

successfully returned with a TRUE value to cancel pending I/O operations and FALSE to cancel the cancel. Typically, this function is called by a separate thread from the one controlling the I/O channel (since the channel’s thread is usually in the DLL if a cancel operation needs to be done). A typical use of this function might be:

Main thread:

CancelNeeded = TRUE;

rsiCancelPendingIO( chnl, TRUE ); // wait until worker sees cancel While(CancelNeeded == TRUE ) ;

Worker Thread:

if( CancelNeeded == TRUE ) {

// cancel pending cancel

rsiCancelPendingIO( chnl, FALSE );

CancelNeeded = TRUE; // signal main thread }

rsiStartupWsock

RSI_RESULT rsiStartupWsock (void); None

Calls the WSAStartup function which initiates the use of the Windows Sockets WS2_32.DLL

RSI_SOCKET_ERROR if unsuccessful. RSI_SUCCESS if successful.

This function should be called at the start-up procedure and once per process. RSIDLL32 supports up to Winsock version 2.2

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

(26)

rsiCleanupWsock

RSI_RESULT rsiCleanupWsock (void); None

Calls the WSACleanup function which terminates the use of the Windows Sockets WS2_32.DLL

RSI_SOCKET_ERROR if unsuccessful. RSI_SUCCESS if successful.

This function should be called once for each successful rsiStartupWsock.

rsiInitWsock

RSI_CHANNEL rsiInitWsock (char* hostname, WORD port); Char* hostname: a null-terminated character string representing a number expressed in the Internet standard “.” (dotted) notation. Ie. 111.112.113.114. WOR port: IP port, should be 3001.

Initializes the DLL for use with the specified socket. As such, it

must be called before any of the other routines. The handle it

returns must be saved and passed to the other RSI DLL functions. A handle to the opened channel if successful.

NULL if the channel could not be opened.

This function must be called before using the API.

The returned channel handle must be saved and passed to the other RSIDLL32 functions.

(27)

rsiCloseWsock

RSI_RESULT rsiCloseWsock (RSI_CHANNEL chnl); RSI_CHANNEL chnl

The handle of the channel returned by rsiInitWsock.

Calls Winsock shutdown and closesocket functions. RSI_SUCCESS if successful.

RSI_INVALID_CHANNEL if channel handle is invalid. RSI_NO_CONNECTION if there was no connection.

This function must be called in the applications’s clean-up procedure. After calling this function, none of the commands to the hand reader will work.

rsiPing

RSI_RESULT rsiPing (char * pingaddr, int pings); char * pingaddr

Pointer to a null-terminated string in the form of an IP address. int pings

Number of times to ping before giving up.

Issues one or more pings to see if entity at given IP address is ready.

RSI_SUCCESS if the value of pings is zero or if the function is successful in pinging the given address within a number of attempts given by the argument pings.

RSI_SOCKET_ERROR otherwise.

rsiStartupWsock() needs to have been called first. This function

(28)

is independent of any channels which may or may not have been opened.

This function should not be called if your version of Windows is earlier than Windows 98.

rsiSetPings

void rsiSetPings (int pings); int pings

Number of times rsiInitWsock() is to ping before giving up.

The function rsiInitWsock() calls rsiPing() before attempting to establish communications with the given IP address given by its hostname argument. There is a global variable which gives the value to be passed as the second argument to rsiPing(). This global variable has a default value of zero. rsiSetPing() sets this global variable to the value given in its argument.

This function does not return a value. It cannot fail.

This function should not be called if your version of Windows is earlier than Windows 98. If rsiSetPings() has been called with a nonzero value, then rsiInitWsock() will, to all intents and purposes, attempt to ping the IP address given by its hostname argument prior to attempting to establish communications with it, and if it is unsuccessful in pinging it within the number of attempts previously set via a nonzero argument to rsiSetPings(), then it will not attempt to extablish communications with it, but will return an error code. This can sometimes prevent rsiInitWsock() from waiting an excessively long time before returning an error value, should it be the case that the given host is not in fact available. As a general rule, a value of 2 is recommended as the argument to

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

(29)

rsiSetPings(), but experimentation may be required.

The term “ping” means to send a message to a possible remote IP address in the hope that the target entity will echo it back if the target entity exists.

(30)

Level 1 API

Hand Reader Messaging

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

(31)

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

(32)

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_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 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 R E T U R N S

(33)

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

(34)

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

(35)

Level 2 API

Hand Reader Commands

These functions provide a wrapper around the hand reader commands listed in the Software Manual. As such they will simply be listed here unless there is something that needs to be explained.

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. If successful, RSI_SUCCESS is returned.

RSI_INVALID_CHANNEL is returned if the channel handle is not valid. Validation is performed on all data and RSI_ERROR_DATA may be returned.

rsiResume

RSI_RESULT rsiResume (RSI_CHANNEL chnl);

rsiAbortCommand

RSI_RESULT rsiAbortCommand (RSI_CHANNEL chnl);

rsiHereIsUserRecord

RSI_RESULT rsiHereIsUserRecord (RSI_CHANNEL chnl, RSI_USER_RECORD FAR* ur);

The user record structure this function uses is not the format the hand reader uses.

rsiSendUserRecord

RSI_RESULT rsiSendUserRecord (RSI_CHANNEL chnl, RSI_ID id);

Chapter

5

A R G U M E N T S R E T U R N S P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E N O T E S P R O T O T Y P E

(36)

rsiHereIsSetupData

RSI_RESULT rsiHereIsSetupData (RSI_CHANNEL chnl, RSI_SETUP_DATA FAR* setup);

The setup data structure this function uses is not the format the hand reader uses.

This function retrieves the existing setup data from the reader, updates it with the new setup data, and then sends it back to the reader. This is the correct procedure for updating reader setup data, as described in the Software Manual.

The function rsiUpdateNVRam must be called after this command to transfer the reader’s current setup information to non-volatile RAM.

rsiRemoveUserRecord

RSI_RESULT rsiRemoveUserRecord (RSI_CHANNEL chnl, RSI_ID id);

rsiCalibrate

RSI_RESULT rsiCalibrate (RSI_CHANNEL chnl);

rsiClearUserDataBase

RSI_RESULT rsiClearUserDataBase (RSI_CHANNEL chnl);

rsiSendCalibrationData

RSI_RESULT rsiSendCalibrationData (RSI_CHANNEL chnl);

rsiSendLastUserRecord

RSI_RESULT rsiSendLastUserRecord (RSI_CHANNEL chnl);

P R O T O T Y P E N O T E S P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E

(37)

rsiHereIsTime

RSI_RESULT rsiHereIsTime (RSI_CHANNEL chnl, RSI_TIME_DATE FAR* time);

The wDayOfWeek and wMilliseconds members are not used. The wYear member must be number between 0 and 99 and not a number like 1996.

The time structure this function uses is not the format the hand reader uses.

rsiGetTime

RSI_RESULT rsiGetTime (RSI_CHANNEL chnl, RSI_TIME_DATE FAR* time);

Read the time and date from the hand reader.

rsiSendResults

RSI_RESULT rsiSendResults (RSI_CHANNEL chnl);

rsiSendStatusCRC

RSI_RESULT rsiSendStatusCRC (RSI_CHANNEL chnl);

rsiEnterIdleMode

RSI_RESULT rsiEnterIdleMode (RSI_CHANNEL chnl);

rsiEnterIdleMode2

RSI_RESULT rsiEnterIdleMode2 (RSI_CHANNEL chnl);

P R O T O T Y P E N O T E S P R O T O T Y P E N O T E S P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E

(38)

rsiBeep

RSI_DLL RSI_RESULT RSI_API rsiBeep(RSI_CHANNEL chnl, BYTE duration, BYTE count);

Causes reader to beep a given number of times for a given duration.

rsiHereIsBankNumber

RSI_RESULT rsiHereIsBankNumber (RSI_CHANNEL chnl, RSI_BANK_NUMBER bnk);

rsiHereIsDataBank

RSI_RESULT rsiHereIsDataBank (RSI_CHANNEL chnl, RSI_DATA_BANK FAR* dbnk);

rsiSendDataBank

RSI_RESULT rsiSendDataBank (RSI_CHANNEL chnl, RSI_BANK_NUMBER bnk);

rsiEnrollUser

RSI_RESULT rsiEnrollUser (RSI_CHANNEL chnl, RSI_PROMPT prm);

Valid values for prm are: RSI_RIGHT

RSI_LEFT RSI_BLANK

rsiVerifyOnExternalData

RSI_RESULT rsiVerifyOnExternalData (RSI_CHANNEL chnl, RSI_PROMPT prm, RSI_TEMPLATE tmpl); P R O T O T Y P E N O T E S P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E N O T E S P R O T O T Y P E

(39)

Valid values for prm are: RSI_RIGHT

RSI_LEFT RSI_BLANK

rsiSendTemplate

RSI_RESULT rsiSendTemplate (RSI_CHANNEL chnl);

rsiUpdateNVRam

RSI_RESULT rsiUpdateNVRam (RSI_CHANNEL chnl);

Use this function after sending setup information with the function rsiHereIsSetupData.

rsiSendDataLog

RSI_RESULT rsiSendDataLog (RSI_CHANNEL chnl);

rsiSendPreviousDataLog

RSI_RESULT rsiSendPreviousDataLog (RSI_CHANNEL chnl);

rsiSendSetupData

RSI_RESULT rsiSendSetupData (RSI_CHANNEL chnl);

rsiOutputControl

RSI_RESULT rsiOutputControl (RSI_CHANNEL chnl, RSI_OUTPUT_STATE out);

Valid values for out are:

N O T E S P R O T O T Y P E P R O T O T Y P E N O T E S P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E N O T E S

(40)

RSI_TIMED_UNLOCK RSI_INDEFINATE_UNLOCK RSI_RELOCK_NOW RSI_AUX_ON RSI_AUX_OFF RSI_DISABLE_LOCK RSI_AUX1_ON RSI_AUX1_OFF RSI_AUX2_ON RSI_AUX2_OFF

rsiHereIsDisplayMessage

RSI_RESULT rsiHereIsDisplayMessage (RSI_CHANNEL chnl, RSI_DISPLAY_MESSAGE FAR* msg);

The display message structure this function uses is not the format the hand reader uses.

rsiPrinterPassThrough

RSI_RESULT rsiPrinterPassThrough (RSI_CHANNEL chnl, LPBYTE out, BYTE len);

rsiVerifyOnInternalData

RSI_RESULT rsiVerifyOnInternalData (RSI_CHANNEL chnl, RSI_ID id);

rsiNextMessageIsTimeZone

RSI_RESULT rsiNextMessageIsTimeZone (RSI_CHANNEL chnl);

rsiHereAreTimeZones

RSI_RESULT rsiHereAreTimeZones (RSI_CHANNEL chnl, RSI_TIME_ZONE_TABLE FAR* tz);

The time zone structure this function uses is not the format the hand

P R O T O T Y P E N O T E S P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E P R O T O T Y P E N O T E S

(41)

reader uses.

rsiDisplayCodedMessage

RSI_RESULT rsiDisplayCodedMessage (RSI_CHANNEL chnl, RSI_MESSAGE_CODE msg, BYTE halfsecs);

Valid values for msg are: RSI_ACCESS_GRANTED

RSI_WRONG_TIME_PLACE RSI_HAND_NOT_CLEARED

rsiNextMessageIsBellScheduleTable

RSI_RESULT rsiNextMessageIsBellScheduleTable (RSI_CHANNEL chnl);

rsiHereIsBellScheduleTable

RSI_RESULT rsiHereIsBellScheduleTable (RSI_CHANNEL chnl, RSI_BELL_SCHEDULE FAR* schedule);

The bell schedule structure this function uses is not the format the hand reader uses.

P R O T O T Y P E

N O T E S

P R O T O T Y P E

(42)

Level 3 API

High Level Functions

These are the functions most applications will use. They perform useful tasks such as retrieving and updating user records through one function call. They also handle memory management for RSI_RESPONSE members.

rsiGetUserRecord

RSI_RESULT rsiGetUserRecord (RSI_CHANNEL chnl, RSI_ID id, RSI_USER_RECORD FAR* ur);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_ID id

The ID of the user to retrieve. RSI_USER_RECORD FAR* ur

A pointer to the structure for the user record.

Retrieves a user record from the hand reader. RSI_SUCCESS if successful.

Any error value returned by rsiSendUserRecord, rsiGetResponse, and/or rsiParseResponse if unsuccessful.

Returns value other than RSI_SUCCESS only if there is a communication problem. If the record given by "id" does

not exist, then the reader sends a record with all-zero User ID field.

rsiGetLastUserRecord

RSI_RESULT rsiGetLastUserRecord (RSI_CHANNEL chnl, RSI_USER_RECORD FAR* ur);

Chapter

6

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 P R O T O T Y P E

(43)

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_USER_RECORD FAR* ur

A pointer to the structure for the user record.

Retrieves the user record for the most recent hand reading. RSI_SUCCESS if successful.

Any error value returned by rsiSendLastUserRecord, rsiGetResponse, and/or rsiParseResponse if unsuccessful.

rsiGetStatus

RSI_RESULT rsiGetStatus (RSI_CHANNEL chnl, RSI_STATUS FAR* status);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_STATUS FAR* status

A pointer to the structure for the status.

Retrieves the status of the hand reader. RSI_SUCCESS if successful.

Any error value returned by rsiSendStatusCRC, rsiGetResponse, and/or rsiParseResponse if unsuccessful.

rsiSetBellSchedule

RSI_RESULT rsiSetBellSchedule (RSI_CHANNEL chnl, RSI_BELL_SCHEDULE FAR* schedule);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_BELL SCHEDULE FAR* schedule

A pointer to the structure with the bell schedule for the hand reader. Sets the bell schedule for the hand reader.

RSI_SUCCESS if successful. 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 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 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

(44)

Any error value returned by rsiNextMessageIsBellScheduleTable, and/or rsiHereIsBellScheduleTable if unsuccessful.

rsiSetTimeZoneTable

RSI_RESULT rsiSetTimeZoneTable (RSI_CHANNEL chnl, RSI_TIME_ZONE_TABLE FAR* tz);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_TIME_ZONE_TABLE FAR* tz

A pointer to the structure with the time zone table for the reader. Sets the time zone table for the hand reader. RSI_SUCCESS if successful.

Any error value returned by rsiNextMessageIsTimeZone, and/or rsiHereAreTimeZones if unsuccessful.

rsiGetSetupData

RSI_RESULT rsiGetSetupData (RSI_CHANNEL chnl, RSI_SETUP_DATA FAR* setup);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_SETUP_DATA FAR* setup

A pointer to the structure for the setup data.

Retrieves the current setup data for the hand reader. RSI_SUCCESS if successful.

Any error value returned by rsiSendSetupData, rsiGetResponse, and/or rsiParseResponse if unsuccessful.

rsiGetDataLogElement

RSI_RESULT rsiGetDataLogElement (RSI_CHANNEL chnl, RSI_DATA_LOG_ELEMENT FAR* dl, BOOL bPrev);

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 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 P R O T O T Y P E

(45)

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_DATA_LOG_ELEMENT FAR* dl

A pointer to the structure for the data log. BOOL bPrev

TRUE to retrieve the previous data log or FALSE to retrieve the next data log. Retrieves a data log element from the hand reader.

Any error value returned by rsiSendDataLog, rsiSendPreviousDataLog, rsiGetResponse, and/or rsiParseResponse if unsuccessful.

rsiGetCalibrationData

RSI_RESULT rsiGetCalibrationData (RSI_CHANNEL chnl, RSI_CALIBRATION_DATA FAR* calib);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_CALIBRATION_DATA FAR* calib

A pointer to the structure for the calibration data.

Retrieves the calibration data for the hand reader. RSI_SUCCESS if successful.

Any error value returned by rsiSendCalibrationData, rsiGetResponse, and/or rsiParseResponse if unsuccessful.

rsiGetLastTemplate

RSI_RESULT rsiGetLastTemplate (RSI_CHANNEL chnl, RSI_LAST_TEMPLATE FAR* tmpl);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_LAST_TEMPLATE FAR* tmpl 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 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 P R O T O T Y P E A R G U M E N T S

(46)

A pointer to the structure for the last template and score.

Retrieves the template vector and score for the most recent hand reading.

(But ignore score immediately after an enrollment.) RSI_SUCCESS if successful.

Any error value returned by rsiSendTemplate, rsiGetResponse, and/or rsiParseResponse if unsuccessful.

rsiGetResults

RSI_RESULT rsiGetResults (RSI_CHANNEL chnl, RSI_RESULTS FAR* results);

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_RESULTS FAR* results

A pointer to the structure for the results.

Retrieves the results for the most recent hand reading. RSI_SUCCESS if successful.

Any error value returned by rsiSendResults, rsiGetResponse, and/or rsiParseResponse if unsuccessful.

rsiGetDataBank

RSI_RESULT rsiGetDataBank (RSI_CHANNEL chnl, RSI_BANK_NUMBER bnk, RSI_DATA_BANK FAR* dbnk); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_BANK_NUMBER bnk

Number of the data bank to retrieve. RSI_DATA_BANK_FAR* dbnk

A pointer to the structure for the data bank.

Retrieves a data bank from the hand reader

D E S C R I P T I O N R E T U R N 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 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

(47)

Any error value returned by rsiEnterIdleMode, rsiSendDataBank, rsiGetResponse, and/or rsiParseResponse if unsuccessful.

rsiSetDataBank

RSI_RESULT rsiSetDataBank (RSI_CHANNEL chnl, RSI_BANK_NUMBER bnk, RSI_DATA_BANK FAR* dbnk); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. RSI_BANK_NUMBER bnk

Number of the data bank to set. RSI_DATA_BANK_FAR* dbnk

A pointer to the structure with the data bank to set. Sets a data bank in the hand reader. RSI_SUCCESS if successful.

Any error value returned by rsiEnterIdleMode, rsiHereIsBankNumber, and/or rsiHereIsDataBank if unsuccessful.

R E T U R N 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

(48)

Data Conversion API

Raw, Packed Hand Reader Data

⇔

Programmer Friendly

Structures

Although data conversion is performed by the Level 2 API, applications may need to use these functions to manage data efficiently by storing it in raw, packed format and using it in “programmer friendly” structures.

Functions that convert structures to hand reader data perform validation on structure members. But it is the application’s responsibility to ensure buffers that are passed to these functions are of sufficient size.

These functions will work whether or not the Level 0 API has been called to initialize the DLL/hand reader communication.

rsiUserRecordToData

RSI_DATA_ERROR rsiUserRecordToData (RSI_USER_RECORD FAR* ur, LPBYTE data);

RSI_USER_RECORD FAR* ur

A pointer to the structure with the user record. LPBYTE data

A pointer to the buffer that will receive the user record in raw, packed hand reader format.

Converts a user record structure into the format used by the hand reader.

RSI_DATA_OK if successful.

One of the values returned by rsiGetDataError if unsuccessful.

rsiDataToUserRecord

RSI_DATA_ERROR rsiDataToUserRecord (LPBYTE data, RSI_USER_RECORD FAR* ur);

Chapter

7

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 P R O T O T Y P E

(49)

LPBYTE data

A pointer to the buffer with the raw, packed hand reader user record. RSI_USER_RECORD FAR* ur

A pointer to the structure that will receive the converted user record.

Converts raw, packed hand reader data into a user record structure. RSI_DATA_OK if successful.

rsiSetupDataToData

RSI_DATA_ERROR rsiSetupDataToData (RSI_SETUP_DATA FAR* setup, LPBYTE data);

RSI_SETUP_DATA FAR* setup

A pointer to the structure with the setup data. LPBYTE data

A pointer to the buffer that will receive the setup data in raw, packed hand reader format.

Convert a setup data structure to the format used by the hand reader.

rsiDataToSetupData

RSI_DATA_ERROR rsiDataToSetupData (LPBYTE data, RSI_SETUP_DATA FAR* setup);

LPBYTE data

A pointer to the buffer with the setup data in raw, packed hand reader format.

RSI_SETUP_DATA FAR* setup

A pointer to the structure that will receive the converted setup data.

Converts setup data from raw, packed hand reader format to a setup data structure. 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 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 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

(50)

rsiTimeToData

RSI_DATA_ERROR rsiTimeToData (RSI_TIME_DATE FAR* time, LPBYTE data);

RSI_TIME_DATE FAR* time

A pointer to the structure with the time. The wDayOfWeek and wMilliseconds members are not used. The wYear member must be number between 0 and 99 and not a number like 1996.

LPBYTE data

A pointer to the buffer that will receive the time in raw, packed hand reader format. Converts a time structure to the hand reader format.

rsiDataToTime

RSI_DATA_ERROR rsiDataToTime (LPBYTE data, RSI_TIME_DATE FAR* time);

Converts the hand reader time/date format to a time structure.

rsiDataToStatus

RSI_DATA_ERROR rsiDataToStatus (LPBYTE data, RSI_STATUS FAR* status); R E T U R N 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 P R O T O T Y P E D E S C R I P T I O N R E T U R N S P R O T O T Y P E

(51)

LPBYTE data

A pointer to the buffer with the status information in raw, packed hand reader format.

RSI_STATUS FAR* status

A pointer to the structure that will receive the converted time. Converts hand reader data into a time structure. RSI_DATA_OK if successful.

rsiTextToID

RSI_DATA_ERROR rsiTextToID (LPCTSTR text, RSI_ID id); LPCTSTR text

A pointer to the string that contains the ID number. RSI_ID id

The structure that will receive the ID in BCD format.

Converts a user ID from text to hand reader BCD format. RSI_DATA_OK if successful.

rsiIDToText

RSI_DATA_ERROR rsiIDToText (RSI_ID id, LPTSTR text); RSI_ID id

The structure with the user ID in BCD format. LPTSTR text

A pointer to the string that will receive the ID number in text format. Converts a user ID in BCD format to text.

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 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 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

(52)

rsiTextToMessage

RSI_DATA_ERROR rsiTextToMessage (LPCTSTR text, RSI_MESSAGE_TEXT FAR* msg);

LPCTSTR text

A pointer to the string with the message of up to 32 characters. RSI_MESSAGE_TEXT FAR* msg

A pointer to the structure that will receive the message in hand reader format.

Converts a string to a hand reader string (fixed-length, no null termination).

rsiTimeZoneTableToData

RSI_DATA_ERROR rsiTimeZoneTableToData

(RSI_TIME_ZONE_TABLE FAR* tz, LPBYTE data); RSI_TIME_ZONE_TABLE FAR* tz

A pointer to the structure with the time zone table (including holiday table).

LPBYTE data

A pointer to the buffer that will receive the time zone table in hand reader format. Converts a time zone table structure to the hand reader data format. RSI_DATA_OK if successful.

rsiBellScheduleToData

RSI_DATA_ERROR rsiBellScheduleToData (RSI_BELL_SCHEDULE FAR* schedule, LPBYTE data);

RSI_BELL_SCHEDULE FAR* schedule

A pointer to the structure with the bell schedule.

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 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 P R O T O T Y P E A R G U M E N T S

(53)

LPBYTE data

A pointer to the buffer that will receive the bell schedule in hand reader format. Converts a bell schedule structure to the hand reader data format. RSI_DATA_OK if successful.

rsiDisplayMessageToData

RSI_DATA_ERROR rsiDisplayMessageToData

(RSI_DISPLAY_MESSAGE FAR* msg, LPBYTE data); RSI_DISPLAY_MESSAGE FAR* msg

A pointer to the structure with the display message information. LPBYTE data

A pointer to the buffer that will receive the display message information in hand reader format.

Coverts a display message information structure to the hand reader data format.

rsiDataToDataLog

RSI_DATA_ERROR rsiDataToDataLog (LPBYTE data, RSI_DATA_LOG_ELEMENT FAR* datalog);

LPBYTE data

A pointer to the buffer with the data log element in raw, packed hand reader data.

RSI_DATA_LOG_ELEMENT FAR* datalog

A pointer to the structure that will receive the converted data log element. Converts hand reader data into a data log element.

D E S C R I P T I O N R E T U R N 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 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

(54)

rsiTextToTemplate

void rsiTextToTemplate (LPCTSTR text, int length, RSI_TEMPLATE tmpl);

LPCTSTR text

A pointer to the string that contains the template. RSI_TEMPLATE tmpl

The structure that will receive the template in hex format. Converts a template from text to hex format. None

rsiTemplateToText

void rsiTemplateToText (RSI_TEMPLATE tmpl, LPTSTR text); RSI_TEMPLATE tmpl

The structure with the template in hex format. LPTSTR text

A pointer to the string that will receive the template in text format. Converts a template in hex format to text.

none 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 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

(55)

Miscellaneous Functions

Other Routines

These functions are useful when used with the rest of the API.

rsiGetDataError

RSI_DATA_ERROR rsiGetDataError (RSI_CHANNEL chnl); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. Gets the last data related error that occurred. Possible return values are:

RSI_DATA_OK No data error

RSI_ERROR_ID_CHAR ID character was not a number RSI_ERROR_AUTHORITY_LEVEL Authority level was invalid

RSI_ERROR_REJECT_THRESHOLD Rejection threshold out of range (40-200)

RSI_ERROR_TIME_ZONE Time zone out of range (0-61) RSI_ERROR_YEAR Year out of range (0-99) RSI_ERROR_MONTH Month out of range (1-12) RSI_ERROR_DAY Day out of range (1-31) RSI_ERROR_HOUR Hour out of range (0-23) RSI_ERROR_MINUTE Minute out of range (0-59) RSI_ERROR_SECOND Second out of range (0-59) RSI_ERROR_TIME_20K Time out of range (0-20,000) RSI_ERROR_READER_ADDR Reader address is invalid

Chapter

8

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

(56)

RSI_ERROR_FACILITY_CODE Facility code out of range (0x00-0xFFF)

RSI_ERROR_ID_LENGTH ID length out of range (1-11) RSI_ERROR_NUM_TRIES Number of tries out of range

(1-250)

RSI_ERROR_DURESS_CHAR Duress character invalid

RSI_ERROR_MSG_TEXT Message text is not all alphanumeric

RSI_ERROR_INTERVAL_TIME Interval time out of range (0-239)

RSI_ERROR_BELL_DURATION Bell duration out of range (0-32) RSI_ERROR_BUFFER_INVALID One of the passed buffers was

NULL

Functions that might return RSI_ERROR_DATA clear the current data error, if any, before proceeding. This means applications need to check for data errors immediately after a function returns RSI_ERROR_DATA.

rsiGetComError

int rsiGetComError (RSI_CHANNEL chnl, WORD& error); RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. WORD& error

The error that occured.

Gets the last communications related error that occurred.

rsiSleep

RSI_RESULT rsiSleep (RSI_CHANNEL chnl, long msecs);

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

(57)

RSI_CHANNEL chnl

The handle returned by rsiInstallChannel. long msecs

Length of time to wait in milliseconds.

Waits for the specified amount of time before returning. RSI_SUCCESS if successful.

RSI_ERROR_COM if unsuccessful.

Idle processing is handled automatically.

rsiSetICD

RSI_RESULT rsiSetICD (RSI_CHANNEL chnl, long delay);

Set the ICD to a value possibly different from the default ICD of 4000 ms. ICD is a timeout value that applies when mode is ethernet.

rsiGetICD

RSI_RESULT rsiGetICD (RSI_CHANNEL chnl, long *delay); Get ICD. 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 N O T E S P R O T O T Y P E N O T E S

(58)

Data Types & Sizes

“Programmer Friendly” Hand Reader Data

These structures are not the format used by the hand reader. They exist to simplify programming with RSI DLL. For the actual formats the hand reader uses, see the Software Manual. For the most updated structures, see the rsi_cmd.h file.

RSI_RESPONSE

typedef struct { RSI_RESPONSE_TYPE type; union {

RSI_STATUS FAR* status; RSI_USER_RECORD FAR* userRecord; RSI_CALIBRATION_DATA FAR* calibrationData;

RSI_RESULTS FAR* results; RSI_DATA_BANK FAR* dataBank; RSI_LAST_TEMPLATE FAR* lastTemplate; RSI_DATA_LOG_ELEMENT FAR* dataLog;

RSI_SETUP_DATA FAR* setupData; } data; WORD dataSize; LPBYTE buffer; WORD buflen; } RSI_RESPONSE; RSI_RESPONSE_TYPE type

The response message received. This is set by rsiGetResponse. Valid responses are:

RSI_RESP_NONE RSI_RESP_HERE_IS_STATUS RSI_RESP_HERE_IS_USER_RECORD RSI_RESP_HERE_IS_CALIBRATION_DATA RSI_RESP_HERE_ARE_RESULTS RSI_RESP_HERE_IS_DATA_BANK RSI_RESP_HERE_IS_TEMPLATE_VECTOR

Chapter

9

P R O T O T Y P E M E M B E R S

rsidll

RECOGNITION SYSTEMS, INC.

ID3D Hand Reader Software Development Kit

Version

Table of Contents

Introduction

About RSI DLL

What’s New

Chapter

Chapter

Overview

Getting Started

Getting Help

Highlights on Establishing Different

Connections

Level 0 API

Initialization and Communication

rsiInstallChannel

rsiOpenDirectChannel

Chapter

3

rsiSetModemInitString

rsiOpenModemChannel

rsiOpenCustomChannel

rsiSetHandReader

rsiGetHandReader

rsiCloseChannel

rsiCOMDtr

rsiCOMRts

rsiCOMCts

rsiCOMDsr

rsiCOMRing

rsiCOMCarrier

rsiCOMLineBreak

rsiCOMHardwareOverrun

rsiCOMBaudRate

rsiCOMDataLength

rsiCOMParity

rsiCOMStopBits

rsiCOMRXFlush

rsiCOMTXFlush

rsiCOMRXCount

rsiCOMTXCount

rsiCOMGetChar

rsiCOMGetBuffer

rsiCOMGetString

rsiCOMPutChar

rsiCOMPutBuffer

rsiCancelPendingIO

rsiStartupWsock

rsiCleanupWsock

rsiInitWsock

rsiCloseWsock

rsiPing

rsiSetPings

Level 1 API

Hand Reader Messaging

rsiSendMessage

Chapter

4

rsiGetResponse

rsiParseResponse

rsiLookupCommandInfo

rsiLookupCommandDataSize

rsiLookupResponseInfo

Level 2 API

Hand Reader Commands

rsiResume

rsiAbortCommand

rsiHereIsUserRecord

rsiSendUserRecord

Chapter

5

rsiHereIsSetupData

rsiRemoveUserRecord

rsiCalibrate

rsiClearUserDataBase

rsiSendCalibrationData

rsiSendLastUserRecord

rsiHereIsTime