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_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 immediately 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!\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