Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

scf_terminal_getcard(3smartca) [sunos man page]

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)

Check Out this Related Man Page

SCF_Terminal_waitForCardPresent(3SMARTCARD)		    Smartcard Library Functions 	       SCF_Terminal_waitForCardPresent(3SMARTCARD)

NAME
SCF_Terminal_waitForCardPresent, SCF_Terminal_waitForCardAbsent, SCF_Card_waitForCardRemoved - wait for a card to be inserted or removed SYNOPSIS
cc [ flag... ] file... -lsmartcard [ library...] #include <smartcard/scf.h> SCF_Status_t SCF_Terminal_waitForCardPresent(SCF_Terminal_t terminal, unsigned int timeout); SCF_Status_t SCF_Terminal_waitForCardAbsent(SCF_Terminal_t terminal, unsigned int timeout); SCF_Status_t SCF_Card_waitForCardRemoved(SCF_Card_t card, unsigned int timeout); PARAMETERS
card A card that was returned from SCF_Terminal_getCard(3SMARTCARD). terminal A terminal that was returned from SCF_Session_getTerminal(3SMARTCARD). timeout The maximum number or seconds to wait for the desired state to be reached. If the timeout is 0, the function will immedi- ately return SCF_STATUS_TIMEOUT if the terminal or card is not in the desired state. A timeout of SCF_TIMEOUT_MAX can be specified to indicate that the function should never timeout. DESCRIPTION
These functions determine if a card is currently available in the specified terminal. The SCF_Card_waitForCardRemoved() function differs from SCF_Terminal_waitForCardAbsent() in that it checks to see if a specific card has been removed. If another card (or even the same card) has since been reinserted, SCF_Card_waitForCardRemoved() will report that the old card was removed, while the SCF_Terminal_waitForCardAbsent() will instead report that there is a card present. If the desired state is already true, the function will immediately return SCF_STATUS_SUCCESS. Otherwise it will wait for a change to the desired state, or for the timeout to expire, whichever occurs first. Unlike an event listener (SCF_Terminal_addEventListener(3SMARTCARD)), these functions return the state of the terminal, not just events. To use an electronics analogy, event listeners are edge-triggered, while these functions are level-triggered. RETURN VALUES
If the desired state is reached before the timeout expires, SCF_STATUS_SUCCESS is returned. If the timeout expires, SCF_STATUS_TIMEOUT is returned. Otherwise, an error value is returned. ERRORS
These functions will fail if: SCF_STATUS_BADHANDLE The specified terminal or card has been closed or is invalid. SCF_STATUS_COMMERROR The server closed the connection. SCF_STATUS_FAILED An internal error occured. EXAMPLES
Example 1: Determine if a card is currently inserted. int isCardCurrentlyPresent(SCF_Terminal_t myTerminal) { SCF_Status_t status; /* * The timeout of zero makes sure this call will always * return immediately. */ status = SCF_Terminal_waitForCardPresent(myTerminal, 0); if (status == SCF_STATUS_SUCCESS) return (TRUE); else if (status == SCF_STATUS_TIMEOUT) return (FALSE); /* * For other errors, this example just assumes no card * is present. We don't really know. */ return (FALSE); } Example 2: Remind the user every 5 seconds to remove their card. SCF_Status_t status; SCF_Terminal_t myTerminal; /* (...call SCF_Session_getTerminal to open myTerminal...) */ status = SCF_Terminal_waitForCardAbsent(myTerminal, 0); while (status == SCF_STATUS_TIMEOUT) { printf("Please remove the card from the terminal! "); status = SCF_Terminal_waitForCardAbsent(myTerminal, 5); } if (status == SCF_STATUS_SUCCESS) printf("Thank you. "); else exit(1); /* ... */ Example 3: Demonstrate the difference between the card-specific and terminal-specific calls. 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_SUCCESS) exit(1); /* * While we sleep, assume user removes the card * and inserts another card. */ sleep(10); status = SCF_Terminal_waitForCardAbsent(myTerminal, 0); /* * In this case, status is expected to be SCF_STATUS_TIMEOUT, as there * is a card present. */ status = SCF_Card_waitForCardRemoved(myCard, 0); /* * In this case, status is expected to be SCF_STATUS_SUCCESS, as the * card returned from SCF_Terminal_getCard was indeed removed (even * though another card is currently in the terminal). */ /* ... */ 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_Session_getTerminal(3SMARTCARD), SCF_Terminal_addEventListener(3SMARTCARD), SCF_Terminal_getCard(3SMARTCARD), attributes(5) SunOS 5.10 15 May 2002 SCF_Terminal_waitForCardPresent(3SMARTCARD)
Man Page