visit Kofax web site

SPSmartcardDriver.h File Reference


Detailed Description

SignWare Dynamic Development toolkit, access smart card drivers.

Author:
uko
This header defines access to smart card drivers. The functions declared in this header are not yet implemented for Linux.

The application should query the number of installed drivers (see SPSmartcardDriverGetNumberDrivers), select the appropriate driver (see SPSmartcardDriverCreateByIndex, SPSmartcardDriverCreateByCompanyName, and SPSmartcardDriverCreateByDeviceName) and then create an SPSmartcard object (see SPSmartcardCreate). Any further access should use the SPSmartcard object.

// Example to enumerate smartcard drivers / readers
pSPSMARTCARDDRIVER_T selectSmartcardReader()
{
    pSPSMARTCARDDRIVER_T pDriver = 0;
    SPINT32 iNumReaders = 0;
    SPSmartcardDriverGetNumberDrivers(&iNumReaders);
    if(iNumReaders == 0)    // No smartcard readers installed or found
        return NULL;

    if(iNumReaders == 1) {
        SPSmartcardDriverCreateByIndex(&pDriver, 0);
        return pDriver;
    }
    // Build up a selection list
    std::vector<std::string> vDrivers;
    for(int ik = 0; ik < iNumDrivers; ik++) {
        char szDevice[256];
        SPSmartcardDriverCreateByIndex(&pDriver, 0);
        SPSmartcardDriverGetDeviceName(pDriver, szDevice, sizeof(szDevice));
        SPSmartcardDriverFree(&pDriver);
        vDrivers.push_back(szDevice);
    }

    // let the user select one of the drivers / readers
    std::string strSelected = selectReader(vDrivers);
    
    // create an instance of the selected driver / reader
    SPSmartcardDriverCreateByDeviceName(&pDriver, strSelected.c_str());
    return pDriver;
}


Functions

SPINT32 __cdecl SPSmartcardDriverClone (pSPSMARTCARDDRIVER_T pSmartcardDriver, pSPSMARTCARDDRIVER_T *ppSmartcardDriver)
 Create a copy of an SPSmartcardDriver object.
SPINT32 __cdecl SPSmartcardDriverCreateByCompanyName (pSPSMARTCARDDRIVER_T *ppSmartcardDriver, const SPCHAR *pszCompanyName)
 Create an SPSmartcardDriver object for a company name.
SPINT32 __cdecl SPSmartcardDriverCreateByDeviceName (pSPSMARTCARDDRIVER_T *ppSmartcardDriver, const SPCHAR *pszDeviceName)
 Create an SPSmartcardDriver object for a device name.
SPINT32 __cdecl SPSmartcardDriverCreateByIndex (pSPSMARTCARDDRIVER_T *ppSmartcardDriver, SPINT32 iNrDriver)
 Create an SPSmartcardDriver object by driver index.
SPINT32 __cdecl SPSmartcardDriverFree (pSPSMARTCARDDRIVER_T *ppSmartcardDriver)
 Deallocate an SPSmartcardDriver object.
SPINT32 __cdecl SPSmartcardDriverGetCompanyName (pSPSMARTCARDDRIVER_T pSmartcardDriver, SPCHAR *pszCompanyName, SPINT32 iCompanyNameLength)
 Get the company name from an SPSmartcardDriver object.
SPINT32 __cdecl SPSmartcardDriverGetDeviceName (pSPSMARTCARDDRIVER_T pSmartcardDriver, SPCHAR *pszDeviceName, SPINT32 iDeviceNameLength)
 Get the device name from an SPSmartcardDriver object.
SPINT32 __cdecl SPSmartcardDriverGetNumberDrivers (SPINT32 *piNrDrivers)
 Get the number of smart card drivers found in the system.
SPINT32 __cdecl SPSmartcardDriverGetTerminal (pSPSMARTCARDDRIVER_T pSmartcardDriver, SPINT32 *piDriverTerminal)
 Get the driver terminal number from an SPSmartcardDriver object.
SPINT32 __cdecl SPSmartcardDriverGetVersion (pSPSMARTCARDDRIVER_T pSmartcardDriver, SPCHAR *pszVersion, SPINT32 iVersionLength)
 Get the driver version from an SPSmartcardDriver object.
SPINT32 __cdecl SPSmartcardDriverReset ()
 Free all CT-API drivers to force reloading and reinitialization during the next call SPSmartcardDriverGetNumberDrivers.


Function Documentation

SPINT32 __cdecl SPSmartcardDriverClone pSPSMARTCARDDRIVER_T  pSmartcardDriver,
pSPSMARTCARDDRIVER_T ppSmartcardDriver
 

Create a copy of an SPSmartcardDriver object.

Parameters:
pSmartcardDriver [i] pointer to the SPSmartcardDriver object to be copied.
ppSmartcardDriver [o] pointer to a variable that will be filled with a pointer to a new SPSmartcardDriver object. The caller is responsible for deallocating the new object by calling SPSmartcardDriverFree.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDriverCreateByIndex, SPSmartcardDriverFree
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverCreateByCompanyName pSPSMARTCARDDRIVER_T ppSmartcardDriver,
const SPCHAR pszCompanyName
 

Create an SPSmartcardDriver object for a company name.

Parameters:
ppSmartcardDriver [o] pointer to a variable that will be filled with a pointer to a new SPSmartcardDriver object. The caller is responsible for deallocating the new object by calling SPSmartcardDriverFree. will be filled with the requested driver data.
pszCompanyName [i] name of the company as returned by SPSmartcardDriverGetCompanyName.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDriverCreateByDeviceName, SPSmartcardDriverCreateByIndex, SPSmartcardDriverFree
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverCreateByDeviceName pSPSMARTCARDDRIVER_T ppSmartcardDriver,
const SPCHAR pszDeviceName
 

Create an SPSmartcardDriver object for a device name.

Parameters:
ppSmartcardDriver [o] pointer to a variable that will be filled with a pointer to a new SPSmartcardDriver object. The caller is responsible for deallocating the new object by calling SPSmartcardDriverFree. will be filled with the requested driver data.
pszDeviceName [i] name of the device/driver as returned by SPSmartcardDriverGetDeviceName.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDriverCreateByCompanyName, SPSmartcardDriverCreateByIndex, SPSmartcardDriverFree
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverCreateByIndex pSPSMARTCARDDRIVER_T ppSmartcardDriver,
SPINT32  iNrDriver
 

Create an SPSmartcardDriver object by driver index.

Parameters:
ppSmartcardDriver [o] pointer to a variable that will be filled with a pointer to a new SPSmartcardDriver object. The caller is responsible for deallocating the new object by calling SPSmartcardDriverFree.
iNrDriver [i] zero-based index of the driver.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDriverCreateByCompanyName, SPSmartcardDriverCreateByDeviceName, SPSmartcardDriverFree, SPSmartcardDriverGetNumberDrivers
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverFree pSPSMARTCARDDRIVER_T ppSmartcardDriver  ) 
 

Deallocate an SPSmartcardDriver object.

The SPSmartcardDriver object must have been created by SPSmartcardDriverClone, SPSmartcardDriverCreateByCompanyName, SPSmartcardDriverCreateByDeviceName, or SPSmartcardDriverCreateByIndex.

Parameters:
ppSmartcardDriver [io] pointer to a variable containing a pointer to an SPSmartcardDriver object. The variable will be set to NULL if this function succeeds.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDriverCreateByIndex, SPSmartcardDriverCreateByCompanyName, SPSmartcardDriverCreateByDeviceName, SPSmartcardDriverClone, SPSmartcardCreate
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverGetCompanyName pSPSMARTCARDDRIVER_T  pSmartcardDriver,
SPCHAR pszCompanyName,
SPINT32  iCompanyNameLength
 

Get the company name from an SPSmartcardDriver object.

Parameters:
pSmartcardDriver [i] pointer to an SPSmartcardDriver object.
pszCompanyName [o] pointer to a buffer that will be filled with the company name.
iCompanyNameLength [i] size of the buffer (in bytes) pointed to by pszCompanyName.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDriverCreateByIndex, SPSmartcardDriverCreateByCompanyName, SPSmartcardDriverGetDeviceName, SPSmartcardDriverGetTerminal
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverGetDeviceName pSPSMARTCARDDRIVER_T  pSmartcardDriver,
SPCHAR pszDeviceName,
SPINT32  iDeviceNameLength
 

Get the device name from an SPSmartcardDriver object.

Parameters:
pSmartcardDriver [i] pointer to an SPSmartcardDriver object.
pszDeviceName [o] pointer to a buffer that will be filled with the device name.
iDeviceNameLength [i] size of the buffer (in bytes) pointed to by pszDeviceName.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDriverCreateByIndex, SPSmartcardDriverCreateByDeviceName, SPSmartcardDriverGetVersion
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverGetNumberDrivers SPINT32 piNrDrivers  ) 
 

Get the number of smart card drivers found in the system.

This function gives the number of drivers that are installed. There may be drivers without a physical reader connected.

Parameters:
piNrDrivers [o] pointer to a variable that will be filled with the number of smart card drivers found in the system.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverGetTerminal pSPSMARTCARDDRIVER_T  pSmartcardDriver,
SPINT32 piDriverTerminal
 

Get the driver terminal number from an SPSmartcardDriver object.

The terminal number is defined by the ctapi driver and the driver manufacturer. The terminal number may be used to select a specific reader if more than one reader of the same type are connected to the host.

Parameters:
pSmartcardDriver [i] pointer to an SPSmartcardDriver object.
piDriverTerminal [o] pointer to a variable that will be filled with the driver terminal number.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDriverCreateByIndex, SPSmartcardDriverGetCompanyName, SPSmartcardDriverGetDeviceName
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverGetVersion pSPSMARTCARDDRIVER_T  pSmartcardDriver,
SPCHAR pszVersion,
SPINT32  iVersionLength
 

Get the driver version from an SPSmartcardDriver object.

Parameters:
pSmartcardDriver [i] pointer to an SPSmartcardDriver object.
pszVersion [o] pointer to a buffer that will be filled with the driver version.
iVersionLength [i] size of the buffer (in bytes) pointed to by pszVersion.
Returns:
SP_NOERR on success, else error code:
Operating Systems:
Windows (Win32)
See also:
SPSmartcardDriverCreateByIndex, SPSmartcardDriverGetDeviceName
Todo:
Implement for Linux

SPINT32 __cdecl SPSmartcardDriverReset  ) 
 

Free all CT-API drivers to force reloading and reinitialization during the next call SPSmartcardDriverGetNumberDrivers.

You must not call this function if you have any SPSmartcardDriver or SPSmartcard objects instantiated, otherwise function calls for these objects will fail.

There should not be any reason for calling this function except for a Windows Service that is started very early in the Windows boot procedure, where you might have to try a few times until smart card drivers are available.

Returns:
SP_NOERR on success
Operating Systems:
Windows (Win32)
Todo:
Implement for Linux