Distribution: COMPANY CONFIDENTIAL
Project: NCD1
Issue: 0.01
Author(s): Rich Buckley
Date: 04-Jul-96
Last Issue: none
0.01 04-Jul-96 First created based on original spec issue 0.03.
| Symbolic name | Value | Description |
| SCI_E_SEQ | 1 | The function is called out of sequence, for example an issue command call before an open call, or an attempt to read a response before issuing a command. |
| SCI_E_INVAL | 2 | A function argument is invalid. |
| SCI_E_NODATA | 3 | An attempt has been made to get response data before it is available. This is not an error. The caller should either loop on a response read or wait for an event notification. |
| SCI_E_TRANS | 4 | The function cannot be performed because another process has locked the card by calling sci_StartTrans() |
| SCI_E_TRUNC | 5 | A buffer was not long enough to contain all the data for which it was intended. |
| SCI_E_SYS | 6 | Unexpected error returned by the system software. |
| SCI_E_API | 7 | Unexpected error detected within the API |
int sci_Open(UINT msg_id)
This function will establish a connection to the smart card and return a card handle to be used in subsequent calls to identify the connection.
The arguments provide an asynchronous notification mechanism. When the caller needs to be notified about an event concerning the card the message msg_id will be signalled to the caller together with an additional parameter to indicate the reason for the notification. Possible values for this are as follows.
| SCI_REMOVED | The card has been removed |
| SCI_INSERTED | The card has been inserted |
| SCI_TRANS_END | A transaction has ended and so other connections are now free to access the card |
| SCI_CMD_DONE | The previous command has completed. There will be a response waiting to be read and there may be data. |
| SCI_ERROR | An error condition has been detected for the card |
If msg_id is zero the event signalling mechanism will not be used, it is assumed that the caller will poll for the response data.
If this function is called when a card is already present and it is the first such call a reset will be issued to the appropriate card, and the answer-to-reset data stream interpreted to enable the card protocol to be correctly set internally. A success response will be returned by the function. The answer-to-reset data should be retrieved by calling the function sci_RetrieveATR() either when the notification is retrieved or repeatedly.
If the card is not present an error response will be returned but the specified notification details will be remembered and invoked when the card is eventually inserted. In this case the open action will not be automatically performed, the user must re-issue the Open() call. If msg_id is zero and the card is not present the open must be repeated until the card is inserted and the command succeeds.
The return value from this call is a card handle to be used in subsequent calls to identify the connection. A value of SCI_ERROR indicates a failure, call sci_Error() for further details.
int sci_RetrieveATR(int card_hnd, SCI_ATR *atrBYTE *hist, int hist_len, int *rcv_len)
This function should be the first call after a successful open call on connection card_hnd to retrieve the answer-to-reset data from the smartcard.
The historical data part of this answer-to-reset will be extracted and copied into the data area hist and the length copied written into rcv_len. If the size of the historical data is greater than the length of hist as specified in hist_len then hist_len bytes will be copied, SCI_ERROR returned with sci_Error() yielding SCI_E_TRUNC and rcv_len containing the actual length available to be copied.
If the application is using asynchronous notification the function should be called in response to the first such notification. Otherwise it would be called repeatedly after the open until a return value of SCI_SUCCESS indicates that the answer-to-reset data has been successfully returned. The call may be repeated at any time while the connection is open without the card being reset. Similarly for a card with several connections the ATR will only be received once when the card is first reset and stored internally within the API for presentation when requested.
int sci_Close(int card_hnd)
The function will close a connection to a smart card. The card will no longer be available until another sci_Open() is performed. Any data waiting to be read or written to the smart card will be discarded and if the card is locked for this connection by a previous call to sci_StartTrans() the lock will be released. The argument identifies the connection to be closed.
int sci_IssueCommand(int card_hnd, BYTE *cmd_hdr, int data_len, BYTE *data, int exp_len)
This function is invoked to send a command to the smart card on the connection identifed by card_hnd as returned from a previous call of sci_Open().
It is assumed that the command header complies with the standard defined in [ref 1] consisting of the 4 bytes CLA, INS, P1, P2. The fifth byte of the standard in which the number of following data bytes is held will be automatically generated from the data_len and exp_len arguments. data_len is the length of the data to be sent to the card and exp_len is the length of the data expected to be returned. No check is performed on the validity of the header or the consistency of the data and header.
int sci_ReadResponse(int card_hnd, BYTE *buff, int buff_len, int *rcv_len, BYTE *resp)
This function obtains the smart card response to the previous command issued on connection card_hnd as returned from a previous call of sci_Open().
The function should be invoked after each sci_IssueCommand() call, the format of the response data will be as for the command to which it relates. The argument buff is a string into which any data will be copied, buff_len should contain the length of buff.
The argument resp is a buffer of at least 2 bytes length which will contain bytes SW1 and SW2 of the application response PDU as defined in [ref 1]. This will contain details of the success or otherwise of the previous command. If the function returns SCI_SUCCESS it means that the previous command was delivered and a response received. In order to determine the actual outcome of the command it is important to examine the response bytes SW1 and SW2.
After completion the argument buff will contain any data returned, rcv_len the length of this data and resp the bytes SW1 and SW2. If buff is not long enough to contain all the data received buff_len bytes will be copied into it and the function will return SCI_FAIL with sci_Error() giving SCI_E_TRUNC and rcv_len containing the actual length. which could have been read.
int sci_StartTrans(int card_hnd)
This function causes the card to be unavailable to any connection other than the one from which this command was invoked as specified by card_hnd. The card is unlocked either by calling sci_EndTrans(), calling sci_Close() or the card being removed.
int sci_EndTrans(int card_hnd)
This causes a card previously locked by a call to sci_StartTrans() on connection card_hnd to be unlocked.
Any other connections open are now free to use the card. Those connections opened specifying asynchronous notification will receive a signal with message SCI_TRANS_END.
int sci_Error(int card_hnd)
If the last function call for connection card_hnd failed this function will return the error code giving details of the failure. Calling this function will not clear the error code, it may be retrieved repeatedly until it is cleared by either closure of the connection or success of a function.
In the event of a sci_Open() call failing there will be no card_hnd available to pass as the argument. In this case pass in a value of SCI_ERROR and the last error code generated by this process will be returned.