SunOS man pages


sun.com \| docs.sun.com		How To Buy \| My Sun \| Worldwide Sites

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

NAME
SYNOPSIS
PARAMETERS
DESCRIPTION
RETURN VALUES
ERRORS
EXAMPLES
ATTRIBUTES
SEE ALSO

NAME

SCF_Terminal_getCard - establish a context with a smartcard

SYNOPSIS

cc [ flag... ] file... -lsmartcard [ library...] #include <smartcard/scf.h> SCF_Status_t SCF_Terminal_getCard(SCF_Terminal_t terminal, SCF_Card_t *card);

PARAMETERS

card: A pointer to a SCF_Card_t. If the smartcard is successfully opened, a handle for the card will be returned through this parameter.
terminal: The terminal (from SCF_Session_getTerminal(3SMARTCARD)) containing a smartcard to open.

The SCF_Terminal_getCard() function establishes a context with a specific smartcard in a terminal. Card objects can be used to send APDUs (Application Protocol Data Units) to the card with SCF_Card_exchangeAPDU(3SMARTCARD). When the card is no longer needed, SCF_Card_close(3SMARTCARD) should be called to release allocated resources.

If SCF_Terminal_getCard() is called multiple times in the same session to access the same physical card (while the card remains inserted), the same SCF_Card_t will be returned in each call. The library cannot identifty specific cards, so when a card is reinserted it will be represented by a new SCF_Card_t. Multithreaded applications must take care to avoid having one thread close a card that is still needed by another thread. This can be accomplished by coordination within the application, or by having each thread open a seperate session to avoid interference.

RETURN VALUES

If a working card is present in the reader, SCF_STATUS_SUCCESS is returned and card is a valid reference to the card. Otherwise, an error value is returned and card remains unaltered.

ERRORS

The SCF_Terminal_getCard() function will fail if:

SCF_STATUS_BADARGS: The card argument is a null pointer.
SCF_STATUS_BADHANDLE: The specified terminal has been closed or is invalid.
SCF_STATUS_FAILED: An internal error occured.
SCF_STATUS_NOCARD: No card is present in the terminal.

EXAMPLES

Example 1. Access a smartcard.

SCF_Status_t status;
SCF_Terminal_t myTerminal;
SCF_Card_t myCard;

/* (...call SCF_Session_getTerminal to open myTerminal...) */

status = SCF_Terminal_getCard(myTerminal, &myCard);
if (status == SCF_STATUS_NOCARD) {
    printf("Please insert your smartcard and try again.\n");
    exit(0);
}
else if (status != SCF_STATUS_SUCCESS) exit(1);

/* (...go on to use the card with SCF_Card_exchangeAPDU()...) */

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving
MT-Level	MT-Safe