pcsc.c File Reference

PC/SC smartcard helper registries and lookup utilities for VM opcodes. More...

#include <PCSC/winscard.h>
#include <PCSC/wintypes.h>
#include <string.h>
#include <stdio.h>

Include dependency graph for pcsc.c:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	pcsc_ctx_entry
	One slot in the PC/SC context registry. More...
struct	pcsc_card_entry
	One slot in the PC/SC card handle registry. More...

Functions
static int	pcsc_alloc_ctx_slot (void)
	Allocate a free context slot in the PC/SC registry.
static int	pcsc_alloc_card_slot (void)
	Allocate a free card slot in the PC/SC registry.
static pcsc_ctx_entry *	pcsc_get_ctx (int id)
	Lookup a context slot by id.
static pcsc_card_entry *	pcsc_get_card (int id)
	Lookup a card slot by id.

Variables
static pcsc_ctx_entry	g_pcsc_ctx [8]
static pcsc_card_entry	g_pcsc_card [32]

Detailed Description

PC/SC smartcard helper registries and lookup utilities for VM opcodes.

This module centralizes tiny fixed-size registries for PC/SC resources and minimal helper functions used by VM opcodes under src/vm/pcsc/*.c. Keeping the concrete handle management here allows the opcode implementations to focus on VM stack marshalling, mirroring the approach taken by other extensions (PCRE2, SQLite, XML2, JSON, INI, cURL, OpenSSL).

Build-time feature flag:

• All code in this file is compiled only when FUN_WITH_PCSC is enabled. When disabled, the referencing opcodes should compile to safe no-op fallbacks (typically pushing 0, Nil, or empty arrays) while retaining the same stack behaviour.

Registries and ownership model:

• Context registry (g_pcsc_ctx): stores SCARDCONTEXT values obtained via SCardEstablishContext(). The registry DOES NOT call SCardReleaseContext() automatically — releasing is the responsibility of the opcode that owns the lifecycle. The registry merely tracks usage and provides a stable, small integer id for referencing a context in later operations.
• Card registry (g_pcsc_card): stores SCARDHANDLE and the negotiated protocol (proto) obtained via SCardConnect(). Similarly, the registry does not call SCardDisconnect(); the VM opcode that created the handle is in charge of eventual teardown.
• Handles are 1-based indices into the fixed arrays (contexts: up to 8, cards: up to 32). A return value of 0 indicates failure (no free slot or invalid request).

Error handling and limits:

• Allocation helpers return 0 when no free slot is available. Lookup helpers return NULL if the id is out of range or the slot is not currently in use.
• The fixed sizes (8 contexts, 32 cards) are pragmatic defaults for typical scripts. Increase cautiously if your workloads require more concurrent resources.

Thread-safety:

• This module is not thread-safe. If the interpreter is used from multiple threads, coordinate access to these registries externally.

Definition in file pcsc.c.

Function Documentation

pcsc_alloc_card_slot()

int pcsc_alloc_card_slot ( void )

static

Allocate a free card slot in the PC/SC registry.

Scans the card registry for an unused entry, sets initial values, and returns a small positive identifier that can be used by opcodes to index the slot later.

Returns

int A 1-based slot id on success; 0 if no free slot is available.

Definition at line 127 of file pcsc.c.

pcsc_alloc_ctx_slot()

int pcsc_alloc_ctx_slot ( void )

static

Allocate a free context slot in the PC/SC registry.

Scans the small fixed-size context registry for an available slot, marks it as in use, clears the stored value, and returns a 1-based identifier.

Returns

int A 1-based slot id on success; 0 if no free slot is available.

Definition at line 107 of file pcsc.c.

pcsc_get_card()

pcsc_card_entry * pcsc_get_card ( int id )

static

Lookup a card slot by id.

Validates the provided 1-based identifier, ensures the slot is currently in use, and returns a pointer to the internal registry entry, which exposes the SCARDHANDLE and negotiated protocol for subsequent operations (e.g., SCardTransmit()).

Parameters

id	int 1-based card id previously returned by pcsc_alloc_card_slot().

Returns

pcsc_card_entry* Pointer to the entry if valid and in use; NULL otherwise.

Definition at line 167 of file pcsc.c.

pcsc_get_ctx()

pcsc_ctx_entry * pcsc_get_ctx ( int id )

static

Lookup a context slot by id.

Validates the provided 1-based identifier, ensures the slot is currently in use, and returns a pointer to the internal registry entry.

Parameters

id	int 1-based context id previously returned by pcsc_alloc_ctx_slot().

Returns

pcsc_ctx_entry* Pointer to the entry if valid and in use; NULL otherwise.

Definition at line 148 of file pcsc.c.

Variable Documentation

g_pcsc_card

pcsc_card_entry g_pcsc_card[32]

static

Definition at line 97 of file pcsc.c.

g_pcsc_ctx

pcsc_ctx_entry g_pcsc_ctx[8]

static

Definition at line 96 of file pcsc.c.