NAME¶
CT_init, CT_data, CT_close — Functions to handle communication
with integrated circuit cards and cardterminals
SYNOPSIS¶
#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.
SEE ALSO¶
ctbcs (3).
The
MKT (Multifunktionale KartenTerminals) specifications, available for
download from Teletrust website
http://www.teletrust.de (link to URL
http://www.teletrust.de) . In special the documents:
- Part 3:
- CT-API. Cardterminal Applications Programming Interface.
- Part 4:
- CT-BCS. Cardterminal Basic Command Set.
- Part 7:
- IC cards with synchronous transmission Part3: Usage of interindustry
Commands.
ISO/IEC 7816:
Identification cards - Integrated circuit(s) cards with
contacts:
- Part 4:
- Interindustry commands for interchange.
AUTHOR¶
This manual page was written by Carlos Prados <cprados@yahoo.com>.