SCF_Session_getInfo(3SMARTCARD) Smartcard Library Functions SCF_Session_getInfo(3SMARTCARD)
NAME
SCF_Session_getInfo, SCF_Terminal_getInfo, SCF_Card_getInfo - retrieve information about a session, terminal, or card
SYNOPSIS
cc [ flag... ] file... -lsmartcard [ library...]
#include <smartcard/scf.h>
SCF_Status_t SCF_Session_getInfo(SCF_Session_t session, const char *name, void *value);
SCF_Status_t SCF_Terminal_getInfo(SCF_Terminal_t terminal, const char *name, void *value);
SCF_Status_t SCF_Card_getInfo(SCF_Card_t card, const char *name, void *value);
PARAMETERS
card An object that was returned from SCF_Terminal_getCard(3SMARTCARD).
name The name of a property for which a value is to be returned. The name is case-sensitive.
session An object that was returned from SCF_Session_getSession(3SMARTCARD).
terminal An object that was returned from SCF_Session_getTerminal(3SMARTCARD).
value The value of the property. The actual type of the value depends on what property was being queried.
DESCRIPTION
These functions obtain information about a session, terminal, or card. The information returned represents the current state of the object
and can change between calls.
Each call allocates new storage for the returned result. This storage is tracked internally and is deallocated when the object is closed.
An application repeatedly asking for information can cause memory bloat until the object is closed. The application can optionally call
SCF_Session_freeInfo(3SMARTCARD), SCF_Terminal_freeInfo(3SMARTCARD), or SCF_Card_freeInfo(3SMARTCARD) to cause immediate deallocation of
the value. Applications must not use other means such asfree(3C) to deallocate the memory.
Applications must not access values that have been deallocated. For example, accessing a Card's ATR after the card has been closed results
in undefined behavior.
For a session, the valid property names and value types are:
terminalnames (pointer to char **)
The list of terminal names that can currently be used in this session. The returned value is an array of char *, each element of the
list is a pointer to a terminal name. The end of the array is denoted by a null pointer. The first element of the list is the default
terminal for the session, which will be used when SCF_Session_getTerminal() is called with a null pointer for the terminal name.
For a terminal, the standard property names and value types are as follows. Some terminal drivers can define additional driver-specific
properties.
name (pointer to char *)
The name of the terminal. If the default terminal was used (a null pointer was passed to SCF_Session_getTerminal()), the value will
contain the actual name of the default terminal. For example, "MyInternalCardReader".
type (pointer to char *)
The type of the terminal. For example, "SunISCRI".
devname (pointer to char *)
Information about how the device is attached to the system. This can be a UNIX device name (for example, "/dev/scmi2c0") or some other
terminal-specific string describing its relation to the system.
For a card, the valid property names and value types are:
type (pointer to char *)
The type of the smartcard, as recognized by the framework (For example, "Cyberflex"). If the framework does not recognize the card
type, "UnknownCard" is returned.
atr (pointer to struct SCF_BinaryData_t *)
The Answer To Reset (ATR) data returned by the card when it was last inserted or reset. The structure member length denotes how many
bytes are in the ATR. The structure member data is a pointer to the actual ATR bytes.
RETURN VALUES
Upon success, SCF_STATUS_SUCCESS is returned and value will contain the requested information. Otherwise, an error value is returned and
value remains unaltered.
ERRORS
These functions will fail if:
SCF_STATUS_BADARGS Either name or value is a null pointer.
SCF_STATUS_BADHANDLE The session, terminal, or card has been closed or is invalid.
SCF_STATUS_FAILED An internal error occurred.
SCF_STATUS_UNKNOWNPROPERTY The property specified by name was not found.
EXAMPLES
Example 1: Simple string information.
SCF_Status_t status;
SCF_Terminal_t myTerminal;
const char *myName, *myType;
/* (...call SCF_Session_getTerminal to open myTerminal...) */
status = SCF_Terminal_getInfo(myTerminal, "name", &myName);
if (status != SCF_STATUS_SUCCESS) exit(1);
status = SCF_Terminal_getInfo(myTerminal, "type", &myType);
if (status != SCF_STATUS_SUCCESS) exit(1);
printf("The terminal called %s is a %s
", myName, myType);
Example 2: Display the names of all terminals available in the session.
SCF_Status_t status;
SCF_Session_t mySession;
const char **myList; /* Technically "const char * const *". */
int i;
/* (...call SCF_Session_getSession to open mySession...) */
status = SCF_Session_getInfo(mySession, "terminalnames", &myList);
if (status != SCF_STATUS_SUCCESS) exit(1);
printf("The following terminals are available:
");
for (i=0; myList[i] != NULL; i++) {
printf("%d: %s
", i, myList[i]);
}
Example 3: Display the card's ATR.
SCF_Status_t status;
SCF_Card_t myCard;
struct SCF_BinaryData_t *myATR;
int i;
/* (...call SCF_Terminal_getCard to open myCard...) */
status = SCF_Card_getInfo(myCard, "atr", &myATR);
if (status != SCF_STATUS_SUCCESS) exit(1);
printf("The card's ATR is: 0x");
for(i=0; i < myATR->length; i++) {
printf("%02.2x", myATR->data[i]);
}
printf("
");
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_freeInfo(3SMARTCARD), SCF_Session_getSession(3SMARTCARD), SCF_Session_getTerminal(3SMARTCARD), SCF_Termi-
nal_getCard(3SMARTCARD), attributes(5)
SunOS 5.10 28 Feb 2001 SCF_Session_getInfo(3SMARTCARD)