Below are the first 10 and last 10 pages of uncorrected machine-read text (when available) of this chapter, followed by the top 30 algorithmically extracted key phrases from the chapter as a whole.
Intended to provide our own search engines and external engines with highly rich, chapter-representative searchable text on the opening pages of each chapter.
Because it is UNCORRECTED material, please consider the following text as a useful but insufficient proxy for the authoritative book pages.
Do not use for reproduction, copying, pasting, or reading; exclusively for search engines.
OCR for page 92
APPENDIX A
Set of Functionality
for a Standard API
The API proposed under this work is intended to standardize the implementation aspects
associated with contactless smartcards as a fare media for mass transit applications.
A.1 API Functions
This section describes the functions that will be provided by the API and the associated param-
eters, return values, and pre/post conditions for each function.
Table A-1 presents the API-provided CloseReader function used to close an open interface to
a particular contactless smartcard reader.
Table A-2 describes the API-provided GetDriverCap function used to return information
about the driver capabilities for the API-compliant driver. This would include information about
the API version supported and any support for optional API instructions.
Table A-3 describes the API-provided GetPCDProp function used to retrieve a list of proper-
ties associated with the actual hardware reader defined by a particular reader ID. This command
serves as a configuration interrogation utility.
Table A-4 describes the API-provided GetPCDStatus function used to retrieve the current
status of the PCD. This command can be used to verify the current condition of a particular
reader.
Table A-5 describes the API-provided OpenReader function used to initialize and open an
interface to a particular contactless smartcard reader.
Table A-6 describes the API-provided Poll function used to instruct the reader to initiate prob-
ing of the field for contactless card(s). The behavior of the Poll will be defined by the options
defined in the xPICC parameter.
Table A-7 describes the API-provided RetrieveFirmware function used to extract currently
installed firmware from a reader supporting this type of download. It is intended to function as a
standard firmware extraction utility for retrieving an image to be used in a potential restoration.
Table A-8 describes the API-provided SendFirmware function used to send an updated
firmware to a reader supporting this type of upload. It is intended to function as a standard
firmware mounting utility.
Table A-9 describes the API-provided SetPCDProp function used to set attributes associated
with the actual hardware reader defined by a particular interface ID in PCDProp. This command
serves as a configuration-setting utility.
92
OCR for page 93
Set of Functionality for a Standard API 93
Table A-1. TCRPAPI: CloseReader.
Syntax int CloseReader ( PCD* xPCD );
Data Type Field Name Description
PCD* xPCD Pointer to the PCD structure
0 Successful execution
Return Value
2008 Failed execution
Precondition None
The function returns 0 if successful. Otherwise, it
Return Code(s)
returns 2008.
Table A-2. TCRPAPI: GetDriverCap.
Syntax int GetDriverCap (DriverCap* xCap);
Data Type Field Name Description
DriverCap* xCap Pointer to the DriverCap structure
0 Successful execution
Return Value
2008 Failed execution
Precondition None
Return Code(s) Function returns 0 if successful. Otherwise, returns 2008.
Table A-3. TCRPAPI: GetPCDProp.
Syntax int GetPCDProp (PCDProp* xPCDprop);
Data Type Field Name Description
PCDProp* xPCDProp Pointer to the PCDProp structure
0 Successful execution
Return Value
2008 Failed execution
Precondition None
Reader properties and attributes will be set to PCDProp
Return Code(s)
structure if the function execution is successful.
Table A-4. TCRPAPI: GetPCDStatus.
Syntax int GetPCDStatus (PCD* xPCD);
Data Type Field Name Description
PCD* xPCD Pointer to PCD structure
0 Successful execution
Return Value
2008 Failed execution
Precondition None
Outgoing command status is set to nPCDstatus of PCD
structure will be set to current status of a reader. The
Return Code(s) information shall indicate the type of reader, its
communication type, and target reader identification
number.
OCR for page 94
94 Smartcard Interoperability Issues for the Transit Industry
Table A-5. TCRPAPI: OPENREADER.
Syntax int OpenReader (PCD* xPCD);
Data Type Field Name Description
PCD* xPCD Pointer to PCD structure
0 Successful execution
Return Value
2008 Failed execution
Precondition None
The function returns 0 if successful. Otherwise, it returns
2008. Device Identifier will be assigned in PCD structure
Return Code(s) if successful. (It will be assigned to zero if device
identifier is not supported.)
Table A-6. TCRPAPI: Poll.
Syntax int Poll (PICC* xPICC, PCD xPCD);
Data Type Field Name Description
PICC* xPICC Pointer to the PICC structure
PCD xPCD PCD structure
0 Successful execution
2008 Failed execution
Return Value
2002 Timeout
2088 No precise diagnosis
The OpenReader function should be executed successfully
Precondition
prior to Poll function.
If there is no card in the field, nPICCTYPE is set to 0x00
in PICC structure. If a card is found in the field, its serial
number is assigned to the byte array of nPICCUid and the
Return Code(s)
length of the serial number is assigned to nPICCUidLen
in PICC structure. If the card in the field is ISO 14443-4
compliant, bISOPart4 is set to true in PICC structure.
Table A-7. TCRPAPI: RetrieveFirmware.
Syntax int RetrieveFirmware (Firmware* xFirm int nID);
Data Type Field Name Description
Firmware* xFirm Pointer to Firmware structure
int nID Interface ID of the communication
target.
0 Successful execution
Return Value
2008 Failed execution
Precondition None
Return Code(s) Function returns 0 if successful. Otherwise,
it returns 2008.
OCR for page 95
Set of Functionality for a Standard API 95
Table A-8. TCRPAPI: SendFirmware.
Syntax int SendFirmware (Firmware* xFirm int nID);
Data Type Field Name Description
Firmware* xFirm Pointer to Firmware structure
int nID Interface ID of the communication
target.
0 Successful execution
Return Value
2008 Failed execution
Precondition None
Return Code(s) Function returns 0 if successful. Otherwise,
it returns 2008.
Table A-9. TCRPAPI: SetPCDProp.
Syntax int SetPCDProp (PCDProp xPCDprop);
Data Type Field Name Description
PCDProp xPCDProp PCDProp structure
0 Successful execution
Return Value
2008 Failed execution
Precondition None
Return Code(s) Function returns 0 if successful. Otherwise,
it returns 2008.
Table A-10. TCRPAPI: TransmitToCard.
int TransmitToCard (
Command_Frame xCommandFrame,
Syntax Response_Frame* xResponseFrame,
BYTE nPICCType,
PCD xPCD);
Data Type Field Name Description
Command_Frame xCommandFrame Command_Frame structure for
outgoing command frame to
the card.
Response_Frame* xResponseFrame Pointer to the Response_Frame
structure for the incoming
response frame from the card.
BYTE nPICCType Type of card
PCD xPCD PCD structure
0 Successful execution
2008 Failed execution
Return Value
2002 Timeout
2088 No precise diagnosis
OpendReader and Poll functions should be executed
Precondition
successfully prior to TransmitToCard function.
Outgoing command status is set to nPCDstatus of the
Response_Frame structure. Incoming response frame
Return Code(s) from the card is set to the byte array baReceiveFrame
and the length of the response frame is set to
nActualLength in the Response_Frame structure.
Table A-10 describes the API-provided TransmitToCard function used to instruct the reader
to send a block of data to the card and retrieves a response frame if there is a response from the
card before a specified timeout, which is configured in the Response_Frame structure.
OCR for page 96
96 Smartcard Interoperability Issues for the Transit Industry
A.2 API Structures
This section defines the data structures used as parameters by the functions.
Table A-11 defines the Command_Frame structure that contains the outgoing command
frame to the card and its length.
Table A-12 defines the DriverCap structure, which contains the supported API version num-
ber and information about any support for optional API instructions.
Table A-13 defines the Firmware structure that contains the size, revision level, intended check-
sum, and actual binary image to be transferred to the target reader.
Table A-14 defines the PCD structure, which contains interface information about the con-
tactless smartcard reader.
Table A-15 defines the PCDProp structure that contains the particular properties and attrib-
utes of the associated reader with respect to smartcard communication. It includes the number
of SAM slots, the modulation types supported, and options to define the antenna strength, pro-
tocols, and target reader identification number.
Table A-16 defines the PICC Structure that contains the options to define behavior of the
polling.
Table A-17 defines the POLLPICCTYPE structure that contains an options defined type of
card to be polled from the reader.
Table A-18 defines the Response_Frame structure that contains incoming response data from
the card and the options to define timeout delay to retrieve the response frame.
Table A-11. Command_Frame structure.
Parameters List of members
Data Type Field Name Description
short nLength Length of the command frame
BYTE* baSendFrame Outgoing command data frame
Remark: Outgoing command data
(baSendFrame) must be terminated by
0x00. If the raw command length is 2,
a null terminator shall be appended
and the length of the command frame
in this structure will be 3.
For example: the raw command is
{0x5F, 0x02}. The data in baSendFrame
of this structure would be set to {0x5F,
0x02, 0x00}, and the value of nLength
would be set to 3.
Table A-12. DriverCap structure.
Parameters List of members
Data Type Field Name Description
BYTE nVersion Supported TCRP API version
char* cOptional Supported optional API instructions
OCR for page 97
Set of Functionality for a Standard API 97
Table A-13. Firmware structure.
Parameters List of members
Data Type Field Name Description
WORD nRevisionLevel Revision level number of
the firmware
unsigned long int nSize Number of bytes of the firmware
content
unsigned char* cImage Firmware content
WORD nCheckSum CRC of the firmware content
Table A-14. PCD structure.
Parameters List of members
Data Type Field Name Description
BYTE nDevice Target reader to be initialized.
BYTE nID Interface ID for identification of
communication target. This provides
for multi reader operation under a
single host
BYTE nCommType Communication Type, Serial = 0x01,
USB = 0x02
BYTE nComPort COM port number
char* cUsbName USB device name
BYTE nPCDstatus PCD operational status
0: good
1: out of service
Table A-15. PCDProp structure.
Parameters List of members
Data Type Field Name Description
BYTE nDevice Target reader identification number
int nAntennaStrength Options to set the reader's antenna
strength
char* cProtocol Options to set the reader's protocol
mode
BYTE nSAM Number of SAM slots in the reader
char* cModType Reader Modulation Type
OCR for page 98
98 Smartcard Interoperability Issues for the Transit Industry
Table A-16. PICC structure.
Parameters List of members
Data Type Field Name Description
POLLPICCTYPE xPICCTYPE Type of card to poll
BYTE nPICCsToSearch Number of card to search
BYTE nTimeout Timeout delay for polling
short nSessionID Session ID for communication
to the card
BYTE nPICCUid[256] Card Serial Number
int nPICCUidLen Length of serial number
BYTE nPICCTYPE Type of card found,
0x01 = Mifare Ultralight
0x02 = Mifare DESFire
Remark: Future version will
have more card types.
bool bISOPart4 ISO 7816 part-4 compliant
Table A-17. POLLPICCTYPE structure.
Parameters List of members
Data Type Field Name Description
bool ISOA TYPE A card
bool ISOB TYPE B card
bool MifareClassic Phillips Mifare Classic 1K card
bool MifareUltralight Phillips Mifare Ultralight card
bool Jewel Jewel card
bool MV4000 MV 4K card
Table A-18. Response_Frame structure.
Parameters List of members
Data Type Field Name Description
short nExpectedLength Expected length of the response
frame
short nActualLength Actual length of the response frame
BYTE baReceiveFrame[256] Incoming response data frame
int nPCDStatus Outgoing command status
short nNumIterations Number of iteration to check the
response frame from the card
short nIterationTimeout Timeout delay of each iteration
OCR for page 99
Set of Functionality for a Standard API 99
A.3 Example
(OpenReader, CloseReader, Poll, TransmitToCard):
int retValue;
BYTE piccType = 0x02;
PCD reader;
reader.nCommType = 0x01;
reader.nComPort = 0x03;
retValue = OpenReader(&reader);
if(retValue == 0)
{
PICC card;
card.xPICCType.ISOA = true;
card.xPICCType.ISOB = true;
card.xPICCType.MifareClassic = false;
card.xPICCType.MifareUltralight = false;
card.xPICCType.Jewel = false;
card.xPICCType.MV4000 = false;
card.nPICCsToSearch = 0;
card.bISOPart4 = false;
retValue = Poll(&card, reader);
if(retValue == 0 && card.nPICCTYPE != 0x00)
{
BYTE acutalCommand[3] = {0x5F, 0x02, 0x00};
Command_Frame commandStruct;
Response_Frame responseStruct;
commandStruct.baSendFrame = actual Command;
commandStruct.nLength = 3;
responseStruct.nNumIterations = 2;
responseStruct.nIterationTimeout = 100;
response.nExpectedLength = 1;
retValue = TransmitToCard(command Struct, &response Struct, piccType,
reader);
}
}
CloseReader(reader);
