mykad-reader-api/API_REFERENCE.md

API Reference (from API.py)

This section details the programmatic functions available in API.py for integrating smart card functionality into your own Python applications.

Reader Management

list_readers()

Returns a list of available smart card reader objects.

Returns:

• List: List of reader objects. Returns an empty list if no readers are found or if an error occurs.

Example:

from API import list_readers

readers = list_readers()
for reader in readers:
    print(reader)

Command Processing

parse_command_string(hex_string)

Converts a hexadecimal string into a list of integers representing bytes.

Parameters:

• hex_string (str): Hexadecimal string with optional spaces (e.g., "FF CA 00 00" or "FFCA0000")

Returns:

• List[int]: List of integers representing bytes

Raises:

• ValueError: If string contains invalid characters or has odd length

Example:

from API import parse_command_string

bytes_list = parse_command_string("FF CA 00 00")
# Returns: [255, 202, 0, 0]

Connection Management

connect_to_reader(reader, mode='share', protocol='auto')

Establishes a connection to a specified smart card reader.

Parameters:

• reader: Reader object from list_readers() or reader name string
• mode (str): Connection mode
  • 'share' (default): For APDU communication with a smart card
  • 'direct': For sending low-level escape commands directly to the reader hardware
• protocol (str): Communication protocol specification
  • 'auto' (default): Automatically selects protocol based on platform
  • 't0t1': T=0 or T=1 protocol
  • 'undefined': Undefined protocol

Returns:

• tuple: (connection_object, error_message, context_handle)
  • connection_object: CardConnection object (APDU mode) or card handle (escape mode), or None on failure
  • error_message: Error message string or None on success
  • context_handle: Context handle for direct connections, or None for shared connections

Example:

from API import list_readers, connect_to_reader

readers = list_readers()
if readers:
    connection, error, context = connect_to_reader(readers[0], mode='share')
    if connection:
        print("Connected successfully")
    else:
        print(f"Connection failed: {error}")

disconnect_reader(connection, hcontext=None)

Disconnects from a smart card reader and releases context if applicable.

Parameters:

• connection: CardConnection object (APDU mode) or card handle (escape mode)
• hcontext: The established context handle for direct connections (optional, only needed for escape mode)

Example:

from API import connect_to_reader, disconnect_reader

# For APDU mode
connection, error, _ = connect_to_reader(reader, mode='share')
# ... use connection ...
disconnect_reader(connection)

# For escape mode
hcard, error, hcontext = connect_to_reader(reader, mode='direct')
# ... use hcard ...
disconnect_reader(hcard, hcontext)

Unified Command Interface

send_command(connection, command, mode='apdu', ioctl_code=3500)

Sends a command to a connected smart card or reader.

Parameters:

• connection: CardConnection object (APDU mode) or card handle (escape mode)
• command:
  • For APDU mode: Hex string (e.g., "FF CA 00 00 00")
  • For escape mode: Byte array/list or hex string
• mode (str): Command mode
  • 'apdu' (default): For sending APDU commands to a smart card
  • 'escape': For sending escape commands to a reader in direct mode
• ioctl_code (int): IOCTL code for escape commands (default: 3500 - CCID escape)

Returns:

• For APDU mode: (success, response_data, SW1, SW2, error_message)

  • success (bool): True if command was sent successfully
  • response_data (list): Response data bytes
  • SW1 (int): Status word 1
  • SW2 (int): Status word 2
  • error_message (str): Error message or None on success

• For escape mode: (success, response_data, error_message)

  • success (bool): True if command was sent successfully
  • response_data (list): Response data bytes
  • error_message (str): Error message or None on success

Example - APDU Mode:

from API import list_readers, connect_to_reader, send_command, disconnect_reader

readers = list_readers()
if readers:
    connection, error, _ = connect_to_reader(readers[0], mode='share')
    if connection:
        success, response, sw1, sw2, error_msg = send_command(
            connection, 
            "FF CA 00 00 00", 
            mode='apdu'
        )
        if success:
            print(f"Response: {response}, SW1: {sw1:02X}, SW2: {sw2:02X}")
        disconnect_reader(connection)

Example - Escape Mode:

from API import list_readers, connect_to_reader, send_command, disconnect_reader, parse_command_string

readers = list_readers()
if readers:
    hcard, error, hcontext = connect_to_reader(readers[0], mode='direct')
    if hcard:
        command_bytes = parse_command_string("E0 00 00 18 00")
        success, response, error_msg = send_command(
            hcard, 
            command_bytes, 
            mode='escape'
        )
        if success:
            print(f"Response: {response}")
        disconnect_reader(hcard, hcontext)