first init

2026-09-01 10:12:31 +08:00
commit ca6e55f853
718 changed files with 204746 additions and 0 deletions
@@ -0,0 +1,163 @@
+## 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)
+```