Other Alias
CT_init, CT_closeSYNOPSIS
#include <ctapi.h>
char CT_init(
unsigned short ctn,
unsigned short pn);
char CT_data(
unsigned short ctn,
unsigned char * dad,
unsigned char * sad,
unsigned short lenc,
unsigned char * command,
unsigned short * lenr,
unsigned char * response);
char CT_close(
unsigned short ctn);
DESCRIPTION
This manual page describes the CT-API functions used to handle
communication with integrated circuit cards and cardterminals. The
CT-API functions are generic, and allows the use of memory cards (often
referred as synchronous cards) and processor cards (often referred
as asynchronous cards).
The CT-API implementation is dependent on the cardterminal that is
used. For each cardterminal a CT-API library implementation
should be provided, either by the manufacturer or by third parties.
This manpage is not a complete specification of the CT-API, but
a general overview of the most common functionalities.
CT_init() selects and initializes the
interface with the cardterminal (f.i. serial port, USB bus, or any
other type of connector). The CT_init() function must be called before
communicating with the card or the cardterminal. A unique cardterminal
number chosen by the caller is assigned by the CT-API library to the
initialized connection.
- ctn
-
Cardterminal number: identifies the connection with the
cardterminal for further references. It's chosen by the caller
of the function.
- pn
-
Port number: selects the physical interface. The port number
assignment is dependent on the CT-API implementation. However most
serial cardterminal implementations use the convention of assigning
the value 0 to the first serial port, 1 to the second serial port and
so on. See the file /usr/include/ctapi.h of
your CT-API implementation for a list of allowed values.
CT_data() sends a command to the card or to
the cardterminal and returns the response to the calling program.
- ctn
-
Cardterminal number: the number specified in CT_init()
call for this cardterminal.
- dad
-
Destination address. If the command is sent to the cardterminal,
it must point to a variable containing the value CT (0x01). If the
command is sent to a card, the destination address variable must be
set to the number identifying the slot of the cardterminal where the
card is inserted, ranging from ICC1 (0x00) and ICC2 (0x02) to ICC14
(0x0E).
-
On the return of the response, the variable pointed by dad is set to
the value HOST (0x02) or REMOTE_HOST (0x05).
- sad
-
Source address. When the function is called it is usually set to
point to a variable with the value HOST (0x02), although the value
REMOTE_HOST (0x05) may ocurr in some applications if the CT-API
implementation supports remote calls.
-
On the return of the response, the variable pointed by sad is set to any
of the values from CT (0x01), ICC1 (0x00), ICC2 (0x02) to ICC14 (0x0E).
- lenc
-
Command length in bytes.
- command
-
Pointer to the buffer that conveys the command to be sent
to the card or cardterminal.
- lenr
-
Before function call, pointer to a variable containig the
maximum buffer size in bytes for the response data. After
successful function call it contains the size in bytes of the
response data.
- response
-
Pointer to the response data. Memory buffer of at least the size
in bytes specified in lenr must be allocated
before calling to the function.
CT_close() terminates the communication
with the cardterminal which has been assigned to a logical cardterminal
number by the function CT_init(). The function
shall be called for each initialized cardtreminal before the end of
the program in order to free resources if necessary.
- ctn
-
Cardterminal number: as specified in CT_init()
call for this cardterminal.
RETURN VALUE
CT_init(), CT_data(), and CT_close() functions return a value of type
char.
- OK
-
Function call was successful.
- ERR_INVALID
-
Invalid parameter or value.
- ERR_CT
-
Cardterminal Error. The cardterminal is temporarily not
accessible (busy with other or internal processes). The problem can
be solved by the application.
- ERR_TRANS
-
Transmission Error. Transmission errors due to mechanical,
electrical or protocol failures. Reset of the cardterminal is
necessary.
- ERR_MEMORY
-
Memory assignment error. A memory error occurred (f.i. the
allocated buffer is too small for the returned data).
- ERR_HTSI
-
Host Transport Service Interface error. Commonly returned if
the error is produced by the software layer and not in the
communication with the hardware.