SCF_Session_getInfo(3SMARTSmartcard Library FunSCF_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_get‐
Card(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_getSes‐
sion(3SMARTCARD).
terminal An object that was returned from SCF_Session_getTermi‐
nal(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 deallo‐
cate 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 ses‐
sion. 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_Ses‐
sion_getTerminal() is called with a null pointer for the terminal
name.
For a terminal, the standard property names and value types are as fol‐
lows. 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 sys‐
tem.
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\n", 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:\n");
for (i=0; myList[i] != NULL; i++) {
printf("%d: %s\n", 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("\n");
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │MT-Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOlibsmartcard(3LIB), SCF_Session_freeInfo(3SMARTCARD), SCF_Session_get‐
Session(3SMARTCARD), SCF_Session_getTerminal(3SMARTCARD), SCF_Termi‐
nal_getCard(3SMARTCARD), attributes(5)SunOS 5.10 28 Feb 2001 SCF_Session_getInfo(3SMARTCARD)
