SCF_Session_getTerminal(3SMARTCARD) (man pages section 3: Extended Library Functions)

man pages section 3: Extended 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>

session

terminalName

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 connect 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 seperate 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\n", 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.\n", 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