Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members | Related Pages

C API


Files

file  libchipcard.h
 Contains the C API of LibChipCard.

Organisational Stuff

Well, I don't know in which group to put these functions otherwise ;-)

*CHIPCARD_API int ChipCard_Work ()
CHIPCARD_API int ChipCard_AddServer (const char *addr, int port)
CHIPCARD_API void ChipCard_ReaderDescr_free (CHIPCARD_READERDESCR *rd)

Initialisation and Deinitialisation

The functions in this group only need to be called hen you are using the C interface only. The C++ classes automatically call them.

*CHIPCARD_API int ChipCard_Init (const char *configfile, const char *section)
CHIPCARD_API void ChipCard_Fini ()

Configuration File Based APDU Engine

The functions of this group are allow looking up APDU commands. This engine allows adjusting LibChipCard to special cards and readers without recompiling LibChipCard.

*CHIPCARD_API int ChipCard_LocateCommand (const char *command, const char *readertype, const char *cardtype, char *buffer, int bufferlen)
CHIPCARD_API int ChipCard_ExistsCommand (const char *command)
int ChipCard_MakeAPDU (char *buffer, int *bufferlen, const char *command, int argc,...)

General Request and Response Handling

This group contains functions which can be applied to any pending request.

*CHIPCARD_API int ChipCard_CheckResponse (int requestid)
CHIPCARD_API void ChipCard_WithdrawRequest (int requestid)
CHIPCARD_API void ChipCard_AbandonRequest (int requestid)

Requests

LibChipCard works asynchronously. Nearly all actions you want LibChipCard to take are in form of a request. Generally you call a request function (ChipCard_RequestXYZ()), then ChipCard_Work() (repeatedly until a response arrives) and the appropriate check function (ChipCard_CheckXYZ()). The check function is the one that returns the results of a request (if it successfully returns)

*CHIPCARD_API int ChipCard_RequestAllocReader (int *requestid, unsigned int tid)
CHIPCARD_API int ChipCard_CheckAllocReader (int requestid, int *thdl, CHIPCARD_READERDESCR **rd)
CHIPCARD_API int ChipCard_RequestReleaseReader (int *requestid, unsigned int tid)
CHIPCARD_API int ChipCard_CheckReleaseReader (int requestid)
CHIPCARD_API int ChipCard_RequestConnect (int *requestid, unsigned int thdl, int cardId, int waitForIt)
CHIPCARD_API int ChipCard_RequestStopConnect (int *requestid, unsigned int thdl, int prevRequest)
CHIPCARD_API int ChipCard_CheckConnect (int requestid, int *result, char *atrbuffer, int *atrbufferlength)
CHIPCARD_API int ChipCard_RequestDisconnect (int *requestid, unsigned int thdl)
CHIPCARD_API int ChipCard_CheckDisconnect (int requestid, int *result)
CHIPCARD_API int ChipCard_RequestCommand (int *requestid, unsigned int thdl, const char *sendBuffer, int sendBufferLength)
CHIPCARD_API int ChipCard_CheckCommand (int requestid, int *result, char *recvBuffer, int *recvBufferLength)
CHIPCARD_API int ChipCard_RequestFindReader (int *requestid, const char *readerType, unsigned int readerFlags, unsigned int readerFlagsMask)
CHIPCARD_API int ChipCard_CheckFindReader (int requestid, unsigned int *readerbuffer, int *readerBufferLength)
CHIPCARD_API int ChipCard_RequestStatReader (int *requestid, int thdl)
CHIPCARD_API int ChipCard_CheckStatReader (int requestid, int *result, unsigned int *status, char *atrbuffer, int *atrlen)
CHIPCARD_API int ChipCard_RequestWaitReader (int *requestid, int mustChange, const char *readerType, unsigned int readerFlags, unsigned int readerFlagsMask, unsigned int status, unsigned int statusMask, unsigned int statusDelta)
CHIPCARD_API int ChipCard_CheckWaitReader (int requestid, int *tid, unsigned int *status, unsigned int *readerflags, unsigned int *cardId)
CHIPCARD_API int ChipCard_StopWaitReader (int prevRequest)
CHIPCARD_API int ChipCard_CheckStopConnect (int requestid, int *result)

Detailed Description

This group contains the functions of the C core API of LibChipCard. This is internally used by the CTCard and derived classes.

Function Documentation

CHIPCARD_API void ChipCard_AbandonRequest int  requestid  ) 
 

This only marks the request as abandoned. When the response for this request arrives, it will be discarded and the request itself will be deleted. However, if there already is a response to this request this request will immediately be deleted.

Author:
Martin Preuss<martin@libchipcard.de>
Parameters:
request id unique request id

CHIPCARD_API int ChipCard_AddServer const char *  addr,
int  port
 

This function allows adding a card server to the internal list thus bypassing the configuration files. This function is depracated and may seize to exist in future versions, so please don't rely on it.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
addr address of the card server (either 3-dot notation or host name) if port is "-1" then this must be the path to the unix domain socket
port port the server is listening on. If this is "-1" then unix domain sockets will be used, in this case the address should be the path to the socket file.

CHIPCARD_API int ChipCard_CheckAllocReader int  requestid,
int *  thdl,
CHIPCARD_READERDESCR **  rd
 

This function checks whether there is a response for the request.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid unique request id assigned by the matching request function
thdl pointer to an integer variable to receive the terminal handle This one is not to be confused with the tid param given to ChipCard_RequestAllocReader()
rd pointer to a pointer to receive the description of the allocated reader. You are expected to call ChipCard_ReaderDescr_free() when you don't need this description anymore (you take over ownership for this item)

CHIPCARD_API int ChipCard_CheckCommand int  requestid,
int *  result,
char *  recvBuffer,
int *  recvBufferLength
 

This function checks for the result of ChipCard_RequestCommand() and ChipCard_RequestCommand2().

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid unique request id assigned by the matching request function
result pointer to an integer variable to receive the result of the command request. Please note that the return value of this function can be "OK" even if the command itself did not succeed. This is because the return value of this function only tells you whether the request has been answered. You need this parameter here to check for the result of the command itself.
recvBuffer pointer to a buffer for the answer from the card. It must at least have space for two bytes (the two result codes of any APDU)
recvBufferLength pointer to an integer variable initially containing the length of the buffer provided. Upon return this holds the number of bytes actually stored in the buffer. This is guaranteed to never exceed the initial value.

CHIPCARD_API int ChipCard_CheckConnect int  requestid,
int *  result,
char *  atrbuffer,
int *  atrbufferlength
 

This function checks whether there is a response for the request. All return parameters are only modified upon successfull return.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid unique request id assigned by the matching request function
result pointer to an integer variable to receive the result of the connect request. Please note that the return value of this function can be "OK" even if the connect itself did not succeed. This is because the return value of this function only tells you whether the request has been answered. You need this parameter here to check for the result of the connect itself.
atrbuffer pointer to a buffer which is filled upon successful return with the ATR ("Answer To Reset") string returned by a chipcard upon connect. This ATR is normally used to identify/verify the card type since it is quite unique.
atrbufferlength pointer to variable that tells this function about the size of the buffer supplied. Upon return that variable contains the number of bytes actually used by the ATR string. It is guaranteed to never exceed the entry value. Please note that the ATR string is a binary string not terminated by a zero byte (unlike ASCIIZ strings).

CHIPCARD_API int ChipCard_CheckDisconnect int  requestid,
int *  result
 

This function checks whether there is a response for the request.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid unique request id assigned by the matching request function
result pointer to an integer variable to receive the result of the disconnect request. Please note that the return value of this function can be "OK" even if the disconnect itself did not succeed. This is because the return value of this function only tells you whether the request has been answered. You need this parameter here to check for the result of the disconnect itself.

CHIPCARD_API int ChipCard_CheckFindReader int  requestid,
unsigned int *  readerbuffer,
int *  readerBufferLength
 

This function checks whether there is a response for the request. Since a FindReader request is send to all registered servers you should call this function repeatedly (intermixed with ChipCard_Work())until CHIPCARD_ERROR_NO_REQUEST is returned. If you have found a reader before CHIPCARD_ERROR_NO_REQUEST is returned then you should withdraw the request by calling ChipCard_WithdrawRequest().

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid unique request id assigned by the matching request function
readerbuffer a pointer to an integer array to receive the ids of the terminals found. Each of the entries returned in this buffer can be fed to ChipCard_RequestAllocReader.
readerBufferLength size of the buffer (as the number of integer values the array contains, not the size in bytes!)

CHIPCARD_API int ChipCard_CheckReleaseReader int  requestid  ) 
 

This function checks whether there is a response for the request.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid unique request id assigned by the matching request function

* CHIPCARD_API int ChipCard_CheckResponse int  requestid  ) 
 

Each request can be identified by its request id. This function here checks whether there is a response to the given request pending.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid unique request id of the request to check for responses

CHIPCARD_API int ChipCard_CheckStatReader int  requestid,
int *  result,
unsigned int *  status,
char *  atrbuffer,
int *  atrlen
 

This function checks whether there is a response for the request.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid unique request id assigned by the matching request function
result pointer to an integer variable to receive the result of the stat request. Please note that the return value of this function can be "OK" even if the stat itself did not succeed. This is because the return value of this function only tells you whether the request has been answered. You need this parameter here to check for the result of the stat itself.
status pointer to a variable to receive the status of the reader upon successfull return. It holds any OR combination of CHIPCARD_STATUS_XYZ values.
atrbuffer pointer to a buffer which is filled upon successful return with the ATR ("Answer To Reset") string returned by a chipcard upon connect. This ATR is normally used to identify/verify the card type since it is quite unique.
atrlen pointer to variable that tells this function about the size of the buffer supplied. Upon return that variable contains the number of bytes actually used by the ATR string. It is guaranteed to never exceed the entry value. Please note that the ATR string is a binary string not terminated by a zero byte (unlike ASCIIZ strings).

CHIPCARD_API int ChipCard_CheckStopConnect int  requestid,
int *  result
 

CHIPCARD_API int ChipCard_CheckWaitReader int  requestid,
int *  tid,
unsigned int *  status,
unsigned int *  readerflags,
unsigned int *  cardId
 

This function checks whether there is a response for the request.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid unique request id assigned by the matching request function
tid pointer to a variable to receive the id of a matching terminal. This is only altered if the function successfully returns.
status pointer to a variable to receive the current status of the terminal identified by tid
readerflags pointer to a variable to receive the readerflags of the terminal identified by tid

CHIPCARD_API int ChipCard_ExistsCommand const char *  command  ) 
 

Checks whether a given command exists. You can provide a full path here (including readertype and card type separated by "/")

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
command full path of the command to check for

CHIPCARD_API void ChipCard_Fini  ) 
 

This functions shuts down LibChipCard (the client part). It should be called when the program exits. However, when using the C++ API then it will be called internally when needed.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)

* CHIPCARD_API int ChipCard_Init const char *  configfile,
const char *  section
 

This function initializes LibChipCard. It loads all necessary configuration and command files. No communication with any server is done here. This function can be called directly (and must be called if only C code is to be used), but if you are using the C++ API (CTCard and derived classes) then this will be called internally when needed.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
configfile path and name of the client configuration file to use. If this is NULL then the hardcoded default file will be used
section the name of the configuration section which is to be used. If this is NULL (which is recommended) then the root of the configuration file will be used.

* CHIPCARD_API int ChipCard_LocateCommand const char *  command,
const char *  readertype,
const char *  cardtype,
char *  buffer,
int  bufferlen
 

This functions tries to lookup a card command (APDU) based on the type of the reader and the card. This allows adjusting commands to special cards or readers without the need for recompilation of LibChipCard.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
command name of the command (like "select_mf")
readertype type of the reader (either "towitoko", "kobil", "cyberjack" or "other")
buffer buffer to store the complete path and name of the command found
bufferlen size of the buffer provided

int ChipCard_MakeAPDU char *  buffer,
int *  bufferlen,
const char *  command,
int  argc,
  ...
 

Creates an APDU (card command) from the given parameters. This uses the core of the new configuration file driven command engine.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)

CHIPCARD_API void ChipCard_ReaderDescr_free CHIPCARD_READERDESCR rd  ) 
 

This function can be used to free a reader description received upon ChipCard_CheckConnect(). You should alway free such a reader description by using this function.

Author:
Martin Preuss<martin@libchipcard.de>

* CHIPCARD_API int ChipCard_RequestAllocReader int *  requestid,
unsigned int  tid
 

This function requests the allocation of a card reader. A card reader must be allocated in order to use it. After you have finished using the reader you should release it by ChipCard_RequestReleaseReader().

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid pointer to an integer variable to receive the request id This is only altered if this function returns without an error
tid the id of the terminal. You can get this by using ChipCard_RequestFindReader() or ChipCard_RequestWaitReader().

CHIPCARD_API int ChipCard_RequestCommand int *  requestid,
unsigned int  thdl,
const char *  sendBuffer,
int  sendBufferLength
 

This function requests executing a raw APDU on the card in the given reader.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid pointer to an integer variable to receive the request id This is only altered if this function returns without an error
thdl terminal handle assigned by ChipCard_RequestAllocReader()
sendBuffer pointer to the buffer containing the APDU to be executed
sendBufferLength length of the send buffer

CHIPCARD_API int ChipCard_RequestConnect int *  requestid,
unsigned int  thdl,
int  cardId,
int  waitForIt
 

This function requests connecting a card to the given reader.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid pointer to an integer variable to receive the request id This is only altered if this function returns without an error
thdl terminal handle assigned by ChipCard_RequestAllocReader()

CHIPCARD_API int ChipCard_RequestDisconnect int *  requestid,
unsigned int  thdl
 

This function requests disconnecting a card in the given reader. The card is reset by this function, so that any security status is guaranteed to be cleared upon successfull disconnect.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid pointer to an integer variable to receive the request id This is only altered if this function returns without an error
thdl terminal handle assigned by ChipCard_RequestAllocReader()

CHIPCARD_API int ChipCard_RequestFindReader int *  requestid,
const char *  readerType,
unsigned int  readerFlags,
unsigned int  readerFlagsMask
 

This function requests to find a reader by drivertype, readertype and/or readerflags.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid pointer to an integer variable to receive the request id This is only altered if this function returns without an error
readerType (e.g. "towitoko","kobil", "cyberjack") or -1 to match all)
readerFlags (any ORed combination of CHIPCARD_READERFLAGS_KEYPAD and CHIPCARD_READERFLAGS_DISPLAY)
readerFlagsMask may hold the same values as the readerFlags, but this one here is interpreted as a mask. E.g. if this is zero then all readerflags match.

CHIPCARD_API int ChipCard_RequestReleaseReader int *  requestid,
unsigned int  tid
 

This function requests to release a reader. You are expected to call this function when you are finished using the reader in order to free ressources allocated locally by the reader.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid pointer to an integer variable to receive the request id This is only altered if this function returns without an error

CHIPCARD_API int ChipCard_RequestStatReader int *  requestid,
int  thdl
 

This function requests the status of a card reader.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid pointer to an integer variable to receive the request id This is only altered if this function returns without an error
thdl terminal handle assigned by ChipCard_RequestAllocReader()

CHIPCARD_API int ChipCard_RequestStopConnect int *  requestid,
unsigned int  thdl,
int  prevRequest
 

This function requests aborting a pending connection request

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)
Parameters:
requestid pointer to an integer variable to receive the request id This is only altered if this function returns without an error
thdl terminal handle assigned by ChipCard_RequestAllocReader()

CHIPCARD_API int ChipCard_RequestWaitReader int *  requestid,
int  mustChange,
const char *  readerType,
unsigned int  readerFlags,
unsigned int  readerFlagsMask,
unsigned int  status,
unsigned int  statusMask,
unsigned int  statusDelta
 

This is nearly the same as the function above, but it allows to additionally give a delta status. Only changes in those parts of the reader status, whose bits are set in statusDelta are checked. So you can now effectively ignore some status changes. E.g. if statusDelta is "0" then all status changes are ignored, so you will never receive a status change notification.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)

CHIPCARD_API int ChipCard_StopWaitReader int  prevRequest  ) 
 

This function stops waiting for further reader notifications induced by ChipCard_RequestWaitReader(). It releases all ressources allocated by this request.

Author:
Martin Preuss<martin@libchipcard.de>
Parameters:
prevRequest unique request id assigned by the matching request function

CHIPCARD_API void ChipCard_WithdrawRequest int  requestid  ) 
 

If you issued a request and for any reason want to withdraw it (thereby telling LibChipCard that you're no longer interested in a response) then you are expected to call this function. It frees all ressources occupied by the request. All future responses to this request which may arrive after withdrawing the request are ignored.

Author:
Martin Preuss<martin@libchipcard.de>
Parameters:
request id unique request id

* CHIPCARD_API int ChipCard_Work  ) 
 

LibChipCard works asynchronously. Most functions only create a request and enqueue it internally. Every time you call this function the enqueued requests are actually send to the corresponding servers. So you will never get an answer to a request if you don't call this function. However, when using the C++ interface (CTCard and derived classes) then this function is called internally.

Author:
Martin Preuss<martin@libchipcard.de>
Returns:
result code (0==ok, all other values are CHIPCARD_ERROR_XYZ values)


Generated on Mon Jun 6 18:17:41 2005 for libchipcard by  doxygen 1.4.2