SCF_Session_getTerminal(3SMARTCARD)			    Smartcard Library Functions 		       SCF_Session_getTerminal(3SMARTCARD)

NAME

       SCF_Session_getTerminal - establish a context with a smartcard terminal (reader)

SYNOPSIS

       cc [ flag... ] file... -lsmartcard [ library...]
       #include <smartcard/scf.h>

       SCF_Status_t SCF_Session_getTerminal(SCF_Session_t session, const char *terminalName, SCF_Terminal_t *terminal);

PARAMETERS

       session	       The session (from SCF_Session_getSession(3SMARTCARD)) containing a terminal to be opened.

       terminal        A  pointer to an SCF_Terminal_t. If the terminal is successfully opened, a handle for the terminal will be returned through
		       this parameter.

       terminalName    Specifies the name of the terminal to access. If terminalName is a null pointer, it indicates that the library should  con-
		       nect with the default terminal for the session.

DESCRIPTION

       The  SCF_Session_getTerminal()  function  establishes a context with a specific smartcard terminal (also known as a reader) in the session.
       Terminal objects are used for detecting card movement (insertion or removal) and to create card objects for accessing a specific card.

       The list of available terminal names can be retrieved by calling SCF_Session_getInfo(3SMARTCARD). Unless the  user  explicitly  requests  a
       specific  terminal, applications should use the session's default terminal by calling SCF_Session_getTerminal() with a null pointer for the
       terminal name. This eliminates the need to first process an available-terminal list with just one element on systems  with  only  a  single
       smartcard  terminal.  On multi-terminal systems, the user can preconfigure one of the terminals as the default (or preferred) terminal. See
       USAGE below.

       If SCF_Session_getTerminal() is called multiple times in the same session to access the same physical  terminal,  the  same  SCF_Terminal_t
       will  be  returned in each call. Multithreaded applications must take care to avoid having one thread close a terminal 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.

       When  the  terminal  is no longer needed, SCF_Terminal_close(3SMARTCARD) should be called to release terminal resources. Closing a terminal
       will also close any cards opened from the terminal.

RETURN VALUES

       Upon success, SCF_STATUS_SUCCESS is returned and terminal contains the opened terminal. Otherwise, an error value is returned and  terminal
       remains unaltered.

ERRORS

       The SCF_Session_getTerminal() function will fail if:

       SCF_STATUS_BADARGS      The terminal argument is a null pointer.

       SCF_STATUS_BADHANDLE    The session was closed or is invalid.

       SCF_STATUS_BADTERMINAL  The specified terminalName is not valid for this session, or the default terminal could not be opened because there
			       are no terminals available in this session.

       SCF_STATUS_COMMERROR    The connection to the server was lost.

       SCF_STATUS_FAILED       An internal error occurred.

EXAMPLES

       Example 1: Use the default terminal.

       SCF_Status_t status;
       SCF_Session_t mySession;
       SCF_Terminal_t myTerminal;
       char *myName;

       /* (...call SCF_Session_getSession to open mySession...) */

       status = SCF_Session_getTerminal(mySession, NULL, &myTerminal);
       if (status != SCF_STATUS_SUCCESS) exit(1);

       status = SCF_Terminal_getInfo(myTerminal, "name", &myName);
       if (status != SCF_STATUS_SUCCESS) exit(1);

       printf("Please insert a card into the terminal named %s
", myName);

       /* ... */

       Example 2: Open a terminal by name.

       SCF_Status_t status;
       SCF_Session_t mySession;
       SCF_Terminal_t myTerminal;
       char *myName;

       /* (...call SCF_Session_getSession to open mySession...) */

       /*
	* The name should be selected from the list of terminal names
	* available from SCF_Session_getInfo, but it could also be
	* read from an appliation's config file or from user input.
	*/
       myName = "SunInternalReader";

       status = SCF_Session_getTerminal(mySession, myName, &myTerminal);
       if (status == SCF_STATUS_BADTERMINAL) {
	   printf("There is no terminal named %s.
", myName);
	   exit(1);
       } else if (status != SCF_STATUS_SUCCESS) exit(2);

       /* ... */

USAGE

       When using the Solaris OCF smartcard framework, the default reader is specified by the ocf.client.default.defaultreader property.  If  this
       property  is  not  set, the first available reader is chosen as the default. Users can set the SCF_DEFAULT_TERMINAL environment variable to
       the name of a terminal to override the normal default. The smartcard utility can also be used to add terminals to or remove terminals  from
       the system. See smartcard(1M) for information on how to add or modify the OCF property.

       Terminals can be accessed only by the user who expected to have physical access to the terminal. By default, this user is assumed to be the
       owner of /dev/console and the superuser. Certain terminals such as Sun Ray appliances can use a different method to restrict access to  the
       terminal.

       The  framework  also uses the DISPLAY environment variable to further restrict which terminals are listed for a user. By default, terminals
       are associated with the ":0" display. Sun Ray terminals are associated with the display for that session, for example ":25". If the DISPLAY
       environment variable is not set or is a display on another host, it is treated as though it were set to ":0". Terminals not associated with
       the user's DISPLAY are not listed. To override this behaviour, the SCF_FILTER_KEY environment variable can be set to the  desired  display,
       for  example  ":0",  ":25", and so on. To list all terminals to which  a user has access, SCF_FILTER_KEY can be set to the special value of
       ":*".

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       smartcard(1M),  libsmartcard(3LIB),  SCF_Session_getInfo(3SMARTCARD),  SCF_Session_getSession(3SMARTCARD),  SCF_Terminal_close(3SMARTCARD),
       attributes(5)

SunOS 5.10							    15 May 2002 			       SCF_Session_getTerminal(3SMARTCARD)