visit Kofax web site
ACTIVESWLib::ISPSmartCard

ACTIVESWLib::ISPSmartCard Interface Reference

Detailed Description

SignWare Dynamic Development toolkit, ActiveX wrapper for SPSmartcardInterface ISPSmartCard.

Access smartcards


Public Member Functions

HRESULT APDU ([in] SAFEARRAY(BYTE)*pucCommand,[in, out] SAFEARRAY(BYTE)*pucResult,[in] long iCmdRespType,[out, retval] long *result)
 Send an APDU (Application protocol data unit).
HRESULT Create ([in] ISPSmartCardDriver *pSmartcardDriver,[out, retval] long *result)
 Create a new Smartcard object from a Smart card driver.
HRESULT DisplayText ([in] BSTR pszDisplayText,[out, retval] long *result)
 Display a text on the Card terminal.
HRESULT GetCardType ([out] long *piCardType,[out, retval] long *result)
 Query the Smartcard type that is currently inserted.
HRESULT GetInput ([in] BSTR pszDisplayText,[in] long iOptionFlags,[out] BSTR *pszInputBuffer,[out, retval] long *result)
 Query input from the Card terminal.
HRESULT GetLastResult ([out] long *piResult,[out, retval] long *result)
 Query the result of the last SPSmartcardCommand or SPSmartcardAPDU operation.
HRESULT GetStatus ([out] long *piStatus,[out, retval] long *result)
 Query the status of a Smartcard object.
HRESULT LoadTemplate ([out] ISPTemplate **ppTemplate,[out, retval] long *result)
 Load a Template from a Smartcard.
HRESULT SaveTemplate ([in] ISPTemplate *pTemplate,[out, retval] long *result)
 Save a Template on a Smartcard.
HRESULT SaveTemplatePassword ([in] ISPTemplate *pTemplate,[in] BSTR pucPassword,[out, retval] long *result)
 Save a Template on a Smartcard in a password protected file.

Member Function Documentation

HRESULT ACTIVESWLib::ISPSmartCard::APDU (  [in] SAFEARRAY(BYTE)*  pucCommand,
[in, out] SAFEARRAY(BYTE)*  pucResult,
[in] long  iCmdRespType,
[out, retval] long *  result
) 
 

Send an APDU (Application protocol data unit).

Send an APDU command to the Smartcard. The application should not call SPSmartcardAPDU, but rather use the higher communication levels. SPSmartcardAPDU is provided to allow for application specific command extensions.

Parameters:
pucCommand [i] a pointer to a byte array containing the command bytes.
CTAPI Command layout:
  • byte 0: Class byte
  • byte 1: Parameter P1
  • byte 2: Parameter P2
  • byte 3: optional Lc field
  • byte 4 ...: optional data
  • byte n - 1: optional Le field
pucResult [o] a pointer to a byte array to receive the result. The result buffer will be structured on exit as follows:
  • byte 0 .. byte *piResultLength - 2: optional result data
  • byte *piResultLength - 2: Returncode SW1
  • byte *piResultLength - 1: Returncode SW2
iCmdRespType [i] Command Response length specifier:
  • SC_APDU_CASE_1 Lc = 0, Le = 0
  • SC_APDU_CASE_2_SHORT Lc = 0, Le <= 256
  • SC_APDU_CASE_3_SHORT Lc <= 255, Le = 0
  • SC_APDU_CASE_4_SHORT Lc <= 255, Le <= 256
  • SC_APDU_CASE_2_EXT Lc = 0, Le <= 65536
  • SC_APDU_CASE_3_EXT Lc <= 65535, Le = 0
  • SC_APDU_CASE_4_EXT Lc <= 65535, Le <= 65536
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
  • SP_PARAMERR invalid parameter
  • SP_SMARTCARDERR a smartcard driver error occured
Returns:
automation result
Note:
The application must set the open or connect state, before sending any commands, and finally reset to the closed state.
See also:
SPSmartcardGotoState

SPSmartcardGetStatus

SC_APDU_CASE_1, SC_APDU_CASE_2_SHORT, SC_APDU_CASE_3_SHORT, SC_APDU_CASE_4_SHORT

SC_APDU_CASE_2_EXT, SC_APDU_CASE_3_EXT, SC_APDU_CASE_4_EXT

SPSmartcardGetLastResult

HRESULT ACTIVESWLib::ISPSmartCard::Create (  [in] ISPSmartCardDriver *  pSmartcardDriver,
[out, retval] long *  result
) 
 

Create a new Smartcard object from a Smart card driver.

Parameters:
pSmartcardDriver [i] A valid SPSMARTCARDDRICER_T object
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
  • SP_PARAMERR invalid parameter
  • SP_MEMERR out of memory
  • SP_SMARTCARDERR a smartcard driver error occured
Returns:
automation result
See also:
SPSmartcardCreate

HRESULT ACTIVESWLib::ISPSmartCard::DisplayText (  [in] BSTR  pszDisplayText,
[out, retval] long *  result
) 
 

Display a text on the Card terminal.

Parameters:
pszDisplayText [i] The text to be displayed as zero terminated char string
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
  • SP_PARAMERR invalid parameter
  • SP_SMARTCARDERR a smartcard driver error occured
Returns:
automation result
See also:
SP_SMARTCARD_INSERTED

HRESULT ACTIVESWLib::ISPSmartCard::GetCardType (  [out] long *  piCardType,
[out, retval] long *  result
) 
 

Query the Smartcard type that is currently inserted.

Parameters:
piCardType [o] A pointer to an integer that will be filled with the Smartcard type.
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
  • SP_PARAMERR invalid parameter
  • SP_SMARTCARDERR a smartcard driver error occured
See also:
SC_CARD_UNKNOWN, SC_CARD_TCOS, SC_CARD_STARCOS, SC_CARD_SMARTCAFE
Note:
Other Smartcard types may be returned, but these are not fully supported in this Version of the SDK.

HRESULT ACTIVESWLib::ISPSmartCard::GetInput (  [in] BSTR  pszDisplayText,
[in] long  iOptionFlags,
[out] BSTR *  pszInputBuffer,
[out, retval] long *  result
) 
 

Query input from the Card terminal.

Parameters:
iOptionFlags [i] optional Flags SP_SUPRESS_INPUT to display characters as asterics
pszDisplayText [i] an optional text to be displayed on the card terminal (only for terminals with integrated display), or NULL if not required
pszInputBuffer [o] A character buffer to receive the input from the card terminal (typical 32 bytes long].
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
  • SP_PARAMERR invalid parameter
  • SP_SMARTCARDERR a smartcard driver error occured
Returns:
automation result
See also:
SP_SMARTCARD_INSERTED

SP_SUPRESS_INPUT

HRESULT ACTIVESWLib::ISPSmartCard::GetLastResult (  [out] long *  piResult,
[out, retval] long *  result
) 
 

Query the result of the last SPSmartcardCommand or SPSmartcardAPDU operation.

Parameters:
piResult [o] A pointer to an integer that will be filled with the result of the last command.
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
Returns:
0: success, else error code
errors:
  • SP_PARAMERR invalid parameter
  • SP_SMARTCARDERR a smartcard driver error occured
Note:
Each command returns a 2 byte status word. The typical no error result is 0x9000.

HRESULT ACTIVESWLib::ISPSmartCard::GetStatus (  [out] long *  piStatus,
[out, retval] long *  result
) 
 

Query the status of a Smartcard object.

Parameters:
piStatus [o] A pointer to an integer that will be filled with the device status.
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
errors:
  • SP_PARAMERR invalid parameter
  • SP_SMARTCARDERR a smartcard driver error occured
Returns:
automation result
See also:
SP_SMARTCARD_INSERTED, SP_SMARTCARD_CHANGED
Note:
the returned status represents a bit field for the status values.

HRESULT ACTIVESWLib::ISPSmartCard::LoadTemplate (  [out] ISPTemplate **  ppTemplate,
[out, retval] long *  result
) 
 

Load a Template from a Smartcard.

Parameters:
ppTemplate [o] A pointer to pSPTEMPLATE_T object, that will be filled with a valid reference template data structure.
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
Returns:
0: success, else error code
errors:
  • SP_PARAMERR invalid parameter
  • SP_SMARTCARDERR a smartcard driver error occured
See also:
SPSmartcardSaveTemplate, SPTemplateCreateFromSmartcard

HRESULT ACTIVESWLib::ISPSmartCard::SaveTemplate (  [in] ISPTemplate *  pTemplate,
[out, retval] long *  result
) 
 

Save a Template on a Smartcard.

Parameters:
pTemplate [i] A pointer to valid SPTEMPLATE_T object
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
Returns:
0: success, else error code
errors:
  • SP_PARAMERR invalid parameter
  • SP_SMARTCARDERR a smartcard driver error occured
See also:
SPSmartcardLoadTemplate, SPTemplateCreateFromSmartcard

HRESULT ACTIVESWLib::ISPSmartCard::SaveTemplatePassword (  [in] ISPTemplate *  pTemplate,
[in] BSTR  pucPassword,
[out, retval] long *  result
) 
 

Save a Template on a Smartcard in a password protected file.

Parameters:
pTemplate [i] A pointer to valid SPTEMPLATE_T object
pucPassword [i] A pointer to password to unprotect the smartcard
result [io] pointer to an long that will be filled with the SDK result, if the functions returns S_OK
Returns:
0: success, else error code
errors:
  • SP_PARAMERR invalid parameter
  • SP_SMARTCARDERR a smartcard driver error occured
See also:
SPSmartcardLoadTemplate, SPTemplateCreateFromSmartcard

The documentation for this interface was generated from the following file: