SCF_Session_getTerminal(3SSmartcard LibrarySCF_Session_getTerminal(3SMARTCARD)NAMESCF_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 suc‐
cessfully opened, a handle for the terminal will be
returned through this parameter.
terminalName Specifies the name of the terminal to access. If termi‐
nalName 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 termi‐
nal 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 preconfig‐
ure one of the terminals as the default (or preferred) terminal. See
USAGE below.
If SCF_Session_getTerminal() is called multiple times in the same ses‐
sion 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 avail‐
able 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 physi‐
cal 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 ALSOsmartcard(1M), libsmartcard(3LIB), SCF_Session_getInfo(3SMARTCARD),
SCF_Session_getSession(3SMARTCARD), SCF_Terminal_close(3SMARTCARD),
attributes(5)SunOS 5.10 15 May 20SCF_Session_getTerminal(3SMARTCARD)
