ctapi






CT_init, CT_data, CT_close  —      Functions to handle
communication with integrated circuit cards and
cardterminals




     #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);



     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.









                             ‐2‐


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.











                             ‐3‐


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.




     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









                             ‐4‐


          layer and not in the communication with the
          hardware.




     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.




     This manual page was written by Carlos Prados
<cprados@yahoo.com>.