SCF_Terminal_getCard(3SMARTCARD)			    Smartcard Library Functions 			  SCF_Terminal_getCard(3SMARTCARD)

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.

DESCRIPTION

       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 separate 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.
");
	   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 ALSO

       libsmartcard(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)