CT-API(3)						     Library Functions Manual							 CT-API(3)

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  over-
       view 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 cardtermi-
		 nal 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 nec-
       essary.

       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 neces-
		 sary.

       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  communi-
		 cation 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>.

																	 CT-API(3)