Проект OpenNet: MAN SCF_Session_getTerminal (3) Библиотечные вызовы (FreeBSD и Linux)

Интерактивная система просмотра системных руководств (man-ов)

SCF_Session_getTerminal (3)

>> SCF_Session_getTerminal (3) ( Solaris man: Библиотечные вызовы )

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 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 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\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 ":*".