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:**
```python
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:**
```python
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:**
```python
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:**
```python
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:**
```python
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:**
```python
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)
```