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