CT-API(3)

📦 version 2.0.7, in ubuntu jammy

CT-API(3) 💖 the cardterminal whisperer page

okay bestie so this one lives in the Library Functions Manual, and it's literally the glow-up guide to talking to smart cards and cardterminals. sit down, hydrate, let's go 🫶

✨ NAME ✨

CT_init, CT_data, CT_close — the trio of functions that handle communication with integrated circuit cards and cardterminals. no cap.

✨ 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 page is your bestie guide to the CT-API functions — the ones that handle communication with integrated circuit cards and cardterminals. The CT-API functions are generic, which means they let you use memory cards (people usually call these synchronous cards) and processor cards (aka asynchronous cards). versatile queen behavior 👑

The CT-API implementation is dependent on the cardterminal you're using. Every cardterminal should come with its own CT-API library implementation, either from the manufacturer or from third parties. Also, real talk: this manpage is not a complete specification of the CT-API — it's a general overview of the most common functionalities. iykyk.

💫 CT_init() — the meet-cute

CT_init() selects and initializes the interface with the cardterminal (f.i. serial port, USB bus, or any other type of connector). You must call CT_init() before communicating with the card or the cardterminal. The CT-API library then assigns a unique cardterminal number — chosen by the caller — to that initialized connection. iconic.

  • ctn — Cardterminal number: identifies the connection with the cardterminal for further references. It's chosen by the caller of the function. 👈 you pick it, bestie.
  • pn — Port number: selects the physical interface. The port number assignment is dependent on the CT-API implementation. That said, 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. Peep the file /usr/include/ctapi.h of your CT-API implementation for the list of allowed values. 📋

💫 CT_data() — the actual convo

CT_data() sends a command to the card or to the cardterminal and returns the response to the calling program. the moment we've all been waiting for.

  • ctn — Cardterminal number: the number you specified in the 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 the function call, a pointer to a variable containing the maximum buffer size in bytes for the response data. After a successful function call it contains the size in bytes of the response data. it's giving "before and after" 💅
  • response — Pointer to the response data. A memory buffer of at least the size in bytes specified in lenr must be allocated before calling the function. ⚠️ do not skip this step bestie.

💫 CT_close() — the graceful goodbye

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. clean up after yourself, it's self-care 🌸

  • ctn — Cardterminal number: as specified in the 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. 🎉 we love to see it.
  • 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>. shoutout to the author, absolute legend 🫶

and that's the whole page bestie!! no notes, we ate, periodt. 💖✨

later babes — this was the CT-API(3) page from the Library Functions Manual 🎀🦋

📦 where this page comes from