SCF_Terminal_getCard(3SMARSmartcard Library FuSCF_Terminal_getCard(3SMARTCARD)NAMESCF_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 success‐
fully 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.
DESCRIPTION
The SCF_Terminal_getCard() function establishes a context with a spe‐
cific 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 iden‐
tifty specific cards, so when a card is reinserted it will be repre‐
sented 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 applica‐
tion, or by having each thread open a separate session to avoid inter‐
ference.
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 │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOlibsmartcard(3LIB), SCF_Card_close(3SMARTCARD),
SCF_Card_exchangeAPDU(3SMARTCARD), SCF_Card_getInfo(3SMARTCARD),
SCF_Card_lock(3SMARTCARD), SCF_Session_getTerminal(3SMARTCARD),
attributes(5)SunOS 5.10 28 Feb 2001 SCF_Terminal_getCard(3SMARTCARD)
