SIO - Serial I/O Library

sio is a library of routines for doing cross-platform serial I/O between most Unix varients and WIN32. WIN16 support is currently not in the code (as I don't have a need for it just at the moment).

sio is a collection of routines I've written at various times to handle serial comms that has been reworked into a much nicer interface on which portable application logic can be layered.

sio includes a test program (stest) designed for interfacing with low-level Smartcard readers. stest also has a SCAM low-level driver emulation mode for use with the dumbmouse reader. Using the perl-based SCAM code to probe cards is fairly straight forward.

The current documentation can be found at http://www.cryptsoft.com/scard/sio.html and the source code can be downloaded from ftp://ftp.cryptsoft.com/scard/.

1.1. Copyright

You can do what you like with this code except pretend that you wrote it provided that any derivative of this code includes the above comments unchanged. If you put this in a product then attribution is the only requirement as detailed in the COPYING file in the source distribution.

1.2. References

ISO 7816 Identification cards - Integrated circuit(s) card with contacts
- 7816-3 Part 3 - Electronic signals and transmission protocols
- 7816-4 Part 4 - Interindustry commands for interchange

Smartcard Handbook - Wolfgang Rankl, Wolfgang Effing
ISBN 0471967203
pp 440

(Translation of Handbuch der Chipkarten - Carl Hanser Verlag)

2. API

To use sio simply include sio.h. Read the header file for the current up to date list of functions.

int getATR(char *devicename)
{
  SIO_INFO *si;
  int ch;
  unsigned char achar;

  si=SIO_Open(devicename);
  if (si!=NULL) {
    /* setup for 9600, 8 data, 2 stop, even parity */
    SIO_SetSpeed(s,9600);
    SIO_SetDataBits(s,8);
    SIO_SetStopBits(s,2);
    SIO_SetParity(s,SIO_PARITY_EVEN);
    SIO_SetIOMode(s,SIO_IOMODE_INDIRECT);

    /* now actually change the line settings */
    SIO_WriteSettings(s);

    /* trigger ATR from a Smartcard */
    SIO_DropRTS(s);
    SIO_RaiseRTS(s);

    /* read data until there is none available for
     * the timeout period
     */
    while ((ch=SIO_ReadChar(s))!=-1) {
      achar=(unsigned char)(ch & 0xff);
      SIO_DumpBuffer(stderr,&achar,1,2);
    }

    /* finished ... cleanup time */
    SIO_Close(si);
  }
}

2.1. SIO_INFO

SIO_INFO holds all the relevant information related to a given serial connection. The state that is maintained is deliberately hidden from external view. If you stick to using the defined interfaces then your code will be portable (at least the part that talks to sio) between Unix and WIN32.

2.2. SIO_GetVersion

#define SIO_VERSION_MAJOR       1
#define SIO_VERSION_MINOR       1
int SIO_GetVersion(int *vmajor, int *vminor);

SIO_GetVersion returns the major and minor version number of the library.

2.3. SIO_Open

SIO_INFO *SIO_Open(char *device);

2.4. SIO_Close

int SIO_Close(SIO_INFO *s);

2.5. SIO_SetLogFile

int SIO_SetLogFile(SIO_INFO *s,char *name);

All data read or written will be logged to the specified file. The file is created or it is truncated if it already exists. The data is logged before any data conversion when writing and after any data conversion or echo suppression when reading. This gives the logical application level view of the data rather than the low-level serial view.

2.6. SIO_DumpBuffer

void SIO_DumpBuffer(FILE *fp,char *buf,int len,int text);

Dump a data buffer in different formats.

text=0 - hex dump
text=1 - printable chars
text=2 - both hex and printable chars

2.7. SIO_ReadSettings

int SIO_ReadSettings(SIO_INFO *s);

The current serial device parameters are fetched and converted into the sio view of the serial device.

2.8. SIO_WriteSettings

int SIO_WriteSettings(SIO_INFO *s);

The current sio view of the serial device is used to update the serial device parameters. Don't forget to call this function otherwise any parameter updates that effect the serial device will not actually be in effect yet.

2.9. SIO_GetSettingsString

char *SIO_GetSettingsString(SIO_INFO *s);

Return a terse text representation of the current sio comms settings.

2.10. SIO_SetSettingsString

int SIO_SetSettingsString(SIO_INFO *s,char *str);

Using the same format returned by SIO_GetSettingsString update the internal sio comms settings. Don't forget to call SIO_WriteSettings to update the device settings to match.

2.11. SIO_WaitForData

int SIO_WaitForData(SIO_INFO *s,int timedelay);

Wait up to timedelay microseconds for data activity.

2.12. SIO_ReadChar

int SIO_ReadChar(SIO_INFO *s);

Read a single character. Returns -1 if no data available.

2.13. SIO_ReadBuffer

int SIO_ReadBuffer(SIO_INFO *s,char *buf,int len);

2.14. SIO_WriteChar

int SIO_WriteChar(SIO_INFO *s,int data);

2.15. SIO_WriteBuffer

int SIO_WriteBuffer(SIO_INFO *s,char *buf,int len);

SIO - Serial I/O Library

Table of Contents