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)