// The following ifdef block is the standard way of creating macros 
// which make exporting from a DLL simpler. All files within this DLL 
// are compiled with the MCASAPI_EXPORTS symbol defined on the command 
// line. this symbol should not be defined on any project that uses this 
// DLL. This way any other project whose source files include this file 
// see MCASAPI_API functions as being imported from a DLL, whereas this 
// DLL sees symbols defined with this macro as being exported.

#ifdef MCASCOMMAPI_EXPORTS
#define MCASCOMMAPI_API __declspec(dllexport)
#else
#define MCASCOMMAPI_API __declspec(dllimport)
#endif
 

/////////////////////////////////////////////////////////////////////////
// COMMAND SET:
// -----------
//
// The following is the list of commands which are accepted by the reader 
// controller.  All commands are sent in ASCII format and are case insensitive.
// Each command string must be terminated with a carriage-return "\r".  Most 
// commands accept an optional address specifier [ADDRESS=nnnnnnnn] which 
// designates a specific controller on the RS-485 network.  If no address is 
// given, the command is assumed to be a broadcast to all reader controller. 
// (Note that a controller will not issue a response message to a broadcast 
// command as this could result in collision(s).
//
// IMPORTANT:  The address of a reader controller will be identical to its 
//             board serial number.  This 8-digit number is printed on the 
//             barcode label attached to the underside of the board. 
//
// When a command is completed successfully, the controller typically echos the 
// command identifier back to the host PC.  If the controller is unable to perform 
// the command, an error string will be returned such as "ERROR: ENTRY NOT FOUND!".
//
//
//
//   ACTIVATE_ACCESS:
//   ---------------
//   Description:  This command opens the door/gate at the specified controller(s)
//                 as if a successful card-swipe had occurred.
//   Command    :  ACTIVATE_ACCESS  [ADDRESS=nnnnnnnn]\r
//   Response   :  ACTIVATE_ACCESS
//   Example    :  ACTIVATE_ACCESS  ADDRESS=00721205
//                 This example opens the door at the specified reader controller.
//
//
//   ADD_USER:
//   --------
//   Description:  This command adds one or more users to the controller's database.
//   Command    :  ADD_USER  xxxxxxxx yyyyyyyy ... zzzzzzzz  [ADDRESS=nnnnnnnn]\r
//                 where xxxxxxxx, yyyyyyyy, .... zzzzzzzz is a space-separated list 
//                 of numeric user IDs
//   Response   :  ADD_USER: X ENTRIES ADDED
//   Example    :  ADD_USER  08195105 04678340 ADDRESS=00721205
//                 This example adds two user IDs to the specified controller.
//
//
//   ASSIGN_ACCESS:
//   -------------
//   Description:  This command restores normal card-access to a specified user in
//                 the controller(s)' database.
//                 (Useful after performing a DENY_USER command.)
//   Command    :  ASSIGN_ACCESS  ID=xxxxxxxx  [ADDRESS=nnnnnnnn]\r
//   Response   :  ASSIGN_ACCESS:  ENTRIES_ALLOWED=xx  CHECKSUM=yyyy
//   Example    :  ASSIGN_ACCESS  ID=08195105 
//                 This example broadcasts a command to grant access to the specified 
//                 user ID in all readers. Note that since the command is broadcast, 
//                 no response is returned.
//
//
//   CLEAR_ALL:
//   ---------
//   Description:  This command erases the entire database contents of the specified
//                 controller(s).
//   Command    :  CLEAR_ALL  [ADDRESS=nnnnnnnn]\r
//   Response   :  CLEAR_ALL
//   Example    :  CLEAR_ALL  ADDRESS=00721205
//                 This example clears the database contents of the specified 
//                 controller.
//
//
//   DELETE_USER:
//   -----------
//   Description:  This command removed a user from the controller's database.
//   Command    :  DELETE_USER  ID=xxxxxxxx  [ADDRESS=nnnnnnnn]\r
//   Response   :  DELETE_USER:  ENTRIES_DELETED=xx  CHECKSUM=yyyy
//   Example    :  DELETE_USER  ID=08195105
//                 This example broadcasts a command to delete the specified 
//                 user from all readers.  Note that since the command is 
//                 broadcast, no response is returned.
//
//
//   DENY_USER:
//   ---------
//   Description:  This command temporarily denies card-access to a specified 
//                 user in the controller(s)' database.
//   Command    :  DENY_USER  ID=xxxxxxxx  [ADDRESS=nnnnnnnn]\r
//   Response   :  DENY_USER:  ENTRIES_DENIED=xx  CHECKSUM=yyyy
//   Example    :  DENY_USER  ID=08195105 
//                 This example broadcasts a command to lockout the specified 
//                 user ID in all readers.  Note that since the command is 
//                 broadcast, no response is returned.
//
//
//   GET_DB_ALL:
//   ----------
//   Description:  This command dumps the entire database of the specified device.
//                 Starting and ending database indexes must be given.
//   Command    :  GET_DB_ALL  [ADDRESS=nnnnnnnn]\r
//   Response   :  All user IDs contained in the database!
//   Example    :  GET_DB_ALL  ADDRESS=00721205
//                 This example dumps all entries of the database of the 
//                 specified reader controller.
//
//
//   GET_DB_CHECKSUM:
//   ---------------
//   Description:  This command gets the database checksum from the specified 
//                 reader controller.  The checksum is useful for verifying the 
//                 integrity of the database contents.
//   Command    :  GET_DB_CHECKSUM  [ADDRESS=nnnnnnnn]\r
//   Response   :  GET_DB_CHECKSUM :yyyy
//   Example    :  GET_DB_CHECKSUM  ADDRESS=00721205
//                 This example retrieves the checksum from the specified reader 
//                 controller.
//
//
//   GET_DB_ENTRY:
//   ------------
//   Description:  This command retrieves database entry(s) from specified.
//                 controller.  Starting and ending database indexes must be given.
//   Command    :  GET_DB_ENTRY  START=xxxx END=yyyy  [ADDRESS=nnnnnnnn]\r
//   Response   :  GET_DB_ENTRY: xxxx ENTRIES RETRIEVED!
//   Example    :  GET_DB_ENTRY  START=0  END=99  ADDRESS=00721205
//                 This example retrieves the first 100 entries of the database at 
//                 the specified reader controller.
//
//
//   GET_DB_SIZE:
//   -----------
//   Description:  This command retrieves the number of users in the 
//                 controller(s)' database.
//   Command    :  GET_DB_SIZE  [ADDRESS=nnnnnnnn]\r
//   Response   :  GET_DB_SIZE:  x ENTRIES  CHECKSUM=yyyy
//   Example    :  GET_DB_SIZE  ADDRESS=00721205 
//                 This example requests the database size of the specified reader
//                 controller. 
//
//
//   GET_FW_VERSION:
//   --------------
//   Description:  This command gets the firmware version from the specified reader 
//                 controller. 
//   Command    :  GET_FW_VERSION  [ADDRESS=nnnnnnnn]\r
//   Response   :  Firmware version (e.g., 01.00)
//   Example    :  GET_FW_VERSION  ADDRESS=00721205
//                 This example retrieves the firmware version from the specified 
//                 reader controller.
//
//
//   GET_TIME:
//   --------
//   Description:  This command gets the current time/date of the specified 
//                 reader controller. 
//   Command    :  GET_TIME  [ADDRESS=nnnnnnnn]\r
//   Response   :  System time
//   Example    :  GET_TIME  ADDRESS=00721205
//                 This example retrieves the system time and date from the 
//                 specified reader 
//                 controller.
//
//
//   LOCKOUT_MODE:
//   ------------
//   Description:  This command puts the specified controller(s) into user lockout 
//                 mode.  In this mode, all user card swipe requests are denied.
//   Command    :  LOCKOUT_MODE  [ADDRESS=nnnnnnnn]\r
//   Response   :  LOCKOUT_MODE
//   Example    :  LOCKOUT_MODE  ADDRESS=00721205
//                 This example denies access to all users at the specified reader 
//                 controller.
//
//
//   MODIFY_USER:
//   -----------
//   Description:  This command changes a user's ID in the controller's database.
//   Command    :  MODIFY_USER  ID=xxxxxxxx  NEW=yyyyyyyy  [ADDRESS=nnnnnnnn]\r
//   Response   :  MODIFY_USER:  ENTRIES_MODIFIED=xx  CHECKSUM=yyyy
//   Example    :  MODIFY_USER  ID=08195105  NEW=12345678
//                 This example broadcasts a command to modify the specified 
//                 user ID in all readers.  Note that since the command is 
//                 broadcast, no response is returned.
//
//
//   NORMAL_MODE:
//   -----------
//   Description:  This command puts the specified controller(s) into normal mode. 
//                 This is the default operational mode on power-up.
//   Command    :  NORMAL_MODE  [ADDRESS=nnnnnnnn]\r
//   Response   :  NORMAL_MODE
//   Example    :  NORMAL_MODE  ADDRESS=00721205
//                 This example re-establishes normal mode operation at the 
//                 specified reader controller.
//
//
//   REPORT_STATUS:
//   -------------
//   Description:  This command reports miscellaneous information about a 
//                 specified reader controller(s).
//                 This information includes number of valid users, database 
//                 checksum, and date/time.
//   Command    :  REPORT_STATUS  [ADDRESS=nnnnnnnn]\r
//   Response   :  REPORT_STATUS: Users=x  Chksm=yyyy  Date=mm/dd/yyyy 
//   Example    :  REPORT_STATUS  ID=08195105 
//                 This example issues a command to get status from the specified 
//                 reader.
//
//
//
//   SET_ACCESS_TYPE:
//   ---------------
//   Description:  This command determines the method of door/gate access 
//                 activation for the specified reader controller(s).  There 
//                 are two possible methods activation supported by the 
//                 controller:  RS-232 and high-output TTL digital.
//                 There are 4 available high-output digital channels, 
//                 designated 0,1,2, and 3.
//   Command    :  SET_ACCESS_TYPE [ON_DELAY=xxxx] D_CHANNEL=y [ADDRESS=nnnnnnnn]\r
//                 SET_ACCESS_TYPE  [ON_DELAY=xxxx]  R_BAUD=xxxx  R_ON="string1" 
//                                 R_OFF="string2" 
//   Response   :  SET_ACCESS_TYPE
//   Example #1 :  SET_ACCESS_TYPE  ON_DELAY=8000  DIGITAL  CHANNEL=0 
//                                   ADDRESS=00721205
//                 This example sets digital access using the first high-output 
//                 TTL channel and specifies a "door open" delay of 8 seconds.
//   Example #2  : SET_ACCESS_TYPE  R_BAUD=9600  R_ON="My on-string" 
//                                  R_OFF="My off-string"
//                 This example broadcasts a command to set RS-232 activation in 
//                 all readers.
//
//
//
//   SET_TIME:
//   --------
//   Description:  This command sets the current time/date of the specified reader 
//                 controller. 
//   Command    :  SET_TIME  mm/dd/yy  hh:mm:ss [ADDRESS=nnnnnnnn]\r
//   Response   :  System time
//   Example    :  SET_TIME  05/06/03  08:23:56  ADDRESS=00721205
//                 This example sets the system time and date at the specified 
//                 reader controller.
//
//
//   VALIDATE_USER:
//   -------------
//   Description:  Determine if a specified user exists in the controller's 
//                 database.
//   Command    :  VALIDATE_USER  xxxxxxxx  [ADDRESS=nnnnnnnn]\r
//   Response   :  VALIDATE_USER:  MATCHING_ENTRIES=xx  DB_INDEX=z  CHECKSUM=yyyy
//   Example    :  VALIDATE_USER  08195105  ADDRESS=00722053
//                 This example determines whether specified user exists in the 
//                 controller.
//
/////////////////////////////////////////////////////////////////////////////

// This class is exported from the McasCommApi.dll
class MCASCOMMAPI_API CMcasCommApi {

public:
 

 // Constructor
 CMcasCommApi(void);
 

 // Destructor
 ~CMcasCommApi(void);
 

 // Opens a serial RS-232 comm link for communicating with card-reader 
 // controller(s).  (A serial converter device is required for RS-485
 // communication.)  Returns 0 on success or non-zero on failure. 
 // The serial link handle is maintained internally.) 
 int OpenLink (int CommPort,   // Comm port:  0=>COM1, 1=>COM2, 2=>COM3, etc.
  char *errStr);               // Optional error string; NULL if unused
 

 // Close the serial comm link
 void CloseLink(void);
 

 // Flush the serial comm link: tx and/or rx buffers
 void ClearLink(bool bTx, bool bRx);
 

 // Send the specified command string.  Returns non-zero on success;  0 on error.
 int SendCommand(BYTE  *str,        // String to send
    DWORD dwLen,                   // String length in bytes
    DWORD *dwWritten);             // Number of bytes actually sent
 

 // Await a command response.  Wait a maximum of maxwait milliseconds
 // Returns non-zero on success;  0 on error.
 int GetResponse(BYTE *str,  // String buffer to hold the response
  DWORD *dwLen,              // Number of bytes received
  int   strsize,             // Size of the string buffer (bytes)
  int   maxwait);            // Maximum wait (milliseconds)
 

 // Return the serial comm handle
 HANDLE GetLinkHandle(void);
 

 // Scramble the command string.  (Required for all commands sent to the controller.)
 // ASCII commands are scrambled for security purposes to protect sensitive 
 // information.
 void Scramble(char *str);
 

 // De-scramble the response string.  (Required for all responses received from 
 // the controller.)
 void Descramble(char *str);
};