SCF_Terminal_waitForCardPrSmartcardSCF_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_get‐
Card(3SMARTCARD).
terminal A terminal that was returned from SCF_Session_getTermi‐
nal(3SMARTCARD).
timeout The maximum number or seconds to wait for the desired
state to be reached. If the timeout is 0, the function
will immediately return SCF_STATUS_TIMEOUT if the ter‐
minal 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 spec‐
ified terminal.
The SCF_Card_waitForCardRemoved() function differs from SCF_Termi‐
nal_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_STA‐
TUS_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!\n");
status = SCF_Terminal_waitForCardAbsent(myTerminal, 5);
}
if (status == SCF_STATUS_SUCCESS)
printf("Thank you.\n");
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 ALSOlibsmartcard(3LIB), SCF_Session_getTerminal(3SMARTCARD), SCF_Termi‐
nal_addEventListener(3SMARTCARD), SCF_Terminal_getCard(3SMARTCARD),
attributes(5)SunOS 5.101SCF_Terminal_waitForCardPresent(3SMARTCARD)
