SCF_Terminal_addEventListeSmartcardTLSCF_Terminal_addEventListener(3SMARTCARD)NAME
SCF_Terminal_addEventListener, SCF_Terminal_updateEventListener,
SCF_Terminal_removeEventListener - receive asychronous event notifica‐
tion
SYNOPSIS
cc [ flag... ] file... -lsmartcard [ library...]
#include <smartcard/scf.h>
SCF_Status_t SCF_Terminal_addEventListener(SCF_Terminal_t terminal,
SCF_Event_t events, void(*callback)(SCF_Event_t, SCF_Terminal_t, void
*), void *userData, SCF_ListenerHandle_t *listenerHandle);
SCF_Status_t SCF_Terminal_updateEventListener(SCF_Terminal_t terminal,
SCF_ListenerHandle_t listenerHandle, SCF_Event_t events);
SCF_Status_t SCF_Terminal_removeEventListener(SCF_Terminal_t terminal,
SCF_ListenerHandle_t listenerHandle);
PARAMETERS
terminal A terminal (from SCF_Session_getTerminal(3SMARTCARD))
to which the event listener should be added or removed.
events Events to deliver to the callback. An event will not be
delivered if it is not listed. The caller can register
for multiple events by performing a bitwise OR of the
desired events. The valid events are:
SCF_EVENT_ALL
All of the events listed below will be delivered.
SCF_EVENT_CARDINSERTED
A smartcard was inserted into the terminal.
SCF_EVENT_CARDREMOVED
A smartcard was removed from the terminal.
SCF_EVENT_CARDPRESENT
Indicates that a card was present in the terminal
when the event listener was first added. This event
allows event listeners to determine the initial
state of the terminal before an insert or remove
event occurs. Either this event or the
SCF_EVENT_CARDABSENT (see below) event will be
delivered only once upon adding an event listener
and immediately before any other events are deliv‐
ered. Future card movements will generate
SCF_EVENT_CARDINSERTED and SCF_EVENT_CARDREMOVED
events, but not SCF_EVENT_CARDPRESENT or
SCF_EVENT_CARDABSENT events. An event listener can
assume that if a SCF_EVENT_CARDPRESENT event is
delivered, the next card movement event will be a
SCF_EVENT_CARDREMOVED.
SCF_EVENT_CARDABSENT
Indicates that a card was not present in the termi‐
nal when the event listener was first added. This
event allows event listeners to determine the ini‐
tial state of the terminal before an insert or
remove event occurs. Either this event or the
SCF_EVENT_CARDPRESENT event (see above) will be
delivered only once upon adding an event listener
and immediately before any other events are deliv‐
ered. Future card movements will generate
SCF_EVENT_CARDINSERTED and SCF_EVENT_CARDREMOVED
events, but not SCF_EVENT_CARDPRESENT or
SCF_EVENT_CARDABSENT events. An event listener can
assume that if a SCF_EVENT_CARDABSENT event is
delivered, the next card movement event will be a
SCF_EVENT_CARDINSERTED.
SCF_EVENT_CARDRESET
The smartcard currently present has been reset (see
SCF_Card_reset(3SMARTCARD)).
SCF_EVENT_TERMINALCLOSED
The terminal is in the process of being closed (due
to a call to SCF_Session_close(3SMARTCARD) or
SCF_Terminal_close(3SMARTCARD)), so no further
events will be delivered. The terminal argument
provided to the callback will still be valid.
SCF_EVENT_COMMERROR
The connection to the server has been lost. No fur‐
ther events will be delivered.
callback A function pointer that will be executed when the
desired event occurs. The function must take three
arguments. The first is a SCF_Event_t containing the
event that occured. The second argument is an SCF_Ter‐
minal_t containing the terminal on which the event
occured. The third is a void * that can be used to pro‐
vide arbitrary data to the callback when it is exe‐
cuted.
userData A pointer to arbitrary user data. The data is not
accessed by the library. The pointer is simply provided
to the callback when an event is issued. This argument
can safely be set to NULL if not needed. The callback
must be able to handle this case.
listenerHandle A unique "key" that is provided by SCF_Terminal_addE‐
ventListener() to refer to a specific event listener
registration. This allows multiple event listeners to
be selectivly updated or removed.
DESCRIPTION
These functions allow an application to receive notification of events
on a terminal as they occur. The concept is similar to a signal han‐
dler. When an event occurs, a thread in the SCF library will execute
the provided callback function. Once added, the listener will receive
events until it is removed or either the terminal or session is closed.
When the callback function is executed, the callback arguments specify
the event that occured and the terminal on which it occurred. Addi‐
tionally, each callback will receive the userData pointer that was pro‐
vided when the listener was added. The library does not make a copy of
the memory pointed to by userData, so applications must take care not
to deallocate that memory until it is known that the callback will no
longer access it (for example, by removing the event listener). Each
invocation of the callback will be for exactly one event. If the
library needs to deliver multiple events, they will be dispatched one
at a time. Because the callback is executed from a thread, any opera‐
tions it performs must be thread safe. For each callback registration,
the library creates a new thread to deliver events to that callback.
The callback is expected to perform minimal work and return quickly.
An application can add multiple callbacks on a terminal. Any event that
occurs will be delivered to all listeners that registered for that
event type. The same callback can be registered multiple times. Each
call to SCF_Terminal_addEventListener() will result in a new SCF_Lis‐
tenerHandle_t. The events a callback receives can be changed by calling
SCF_Terminal_updateEventListener() with the handle that was returned
when the listener was initially added. If the listener is set to
receive no events (that is, the events parameter has no bits set), the
listener will remain registered but will not receive any events. To
remove a listener and release allocated resources, use SCF_Termi‐
nal_removeEventListener() or close the terminal.
RETURN VALUES
If the event listener was successfully added or removed, SCF_STA‐
TUS_SUCCESS is returned. Otherwise, an error value is returned and the
internal list of registered event listeners remains unaltered.
ERRORS
These functions will fail if:
SCF_STATUS_BADARGS The callback function pointer and/or listener‐
Handle is null, or an unknown event was speci‐
fied.
SCF_STATUS_BADHANDLE The specified terminal has been closed or is
invalid, or the event listener handle could not
be found to update or remove.
SCF_STATUS_COMMERROR The connection to the server was lost.
SCF_STATUS_FAILED An internal error occurred.
EXAMPLES
Example 1: Register for card movements.
struct myState_t {
int isStateKnown;
int isCardPresent;
};
void myCallback(SCF_Event_t event, SCF_Terminal_t eventTerminal,
void *data) {
struct myState_t *state = data;
if (event == SCF_EVENT_CARDINSERTED) {
printf("--- Card inserted ---\n");
state->isCardPresent = 1;
}
else if (event == SCF_EVENT_CARDREMOVED) {
printf("--- Card removed ---\n");
state->isCardPresent = 0;
}
state->isStateKnown = 1;
}
main() {
SCF_Status_t status;
SCF_Terminal_t myTerminal;
SCF_ListenerHandle_t myListener;
struct myState_t myState;
/* (...call SCF_Session_getTerminal to open myTerminal...) */
myState.isStateKnown = 0;
status = SCF_Terminal_addEventListener(myTerminal,
SCF_EVENT_CARDINSERTED|SCF_EVENT_CARDREMOVED, &myCallback,
&myState, &myListener);
if (status != SCF_STATUS_SUCCESS) exit(1);
while(1) {
if (!myState.isStateKnown)
printf("Waiting for first event...\n");
else {
if (myState.isCardPresent)
printf("Card is present.\n");
else
printf("Card is not present.\n");
}
sleep(1);
}
}
Example 2: Use different callbacks for each event.
void myInsertCallback(SCF_Event_t event, SCF_Terminal_t eventTerminal,
void *data) {
/* ... */
}
void myRemoveCallback(SCF_Event_t event, SCF_Terminal_t eventTerminal,
void *data) {
/* ... */
}
main () {
SCF_Status_t status;
SCF_Terminal_t terminal;
SCF_ListenerHandle_t myListener1, myListener2, myListener3;
int foo, bar;
/* (...call SCF_Session_getTerminal to open myTerminal...) */
status = SCF_Terminal_addEventListener(myTerminal,
SCF_EVENT_CARDINSERTED, &myInsertCallback, &foo,
&myListener1);
if (status != SCF_STATUS_SUCCESS) exit(1);
status = SCF_Terminal_addEventListener(myTerminal,
SCF_EVENT_CARDREMOVED, &myRemoveCallback, &foo,
&myListener2);
if (status != SCF_STATUS_SUCCESS) exit(1);
status = SCF_Terminal_addEventListener(myTerminal,
SCF_EVENT_CARDREMOVED, &myRemoveCallback, &bar,
&myListener3);
if (status != SCF_STATUS_SUCCESS) exit(1);
/*
* At this point, when each insertion occurs, myInsertCallback
* will be called once (with a pointer to foo). When each removal
* occurs, myRemoveCallback will be called twice. One call will
* be given a pointer to foo, and the other will be given a
* pointer to bar.
*/
status = SCF_Terminal_removeEventListener(myTerminal,
myListener2);
if (status != SCF_STATUS_SUCCESS) exit(1);
/*
* Now, when a removal occurs, myRemoveCallback will only be
* called once, with a pointer to bar.
*/
/* ... */
}
Example 3: Use initial state events to show user the terminal state in
a GUI.
void myCallback(SCF_Event_t event, SCF_Terminal_t eventTerminal,
void *unused) {
if (event == SCF_EVENT_CARDPRESENT) {
/* Set initial icon to a terminal with a card present. */
}
else if (event == SCF_EVENT_CARDABSENT) {
/* Set initial icon to a terminal without a card present. */
}
else if (event == SCF_EVENT_CARDINSERTED) {
/* Show animation for card being inserted into a terminal. */
}
else if (event == SCF_EVENT_CARDREMOVED) {
/* Show animation for card being removed from a terminal. */
}
}
main() {
SCF_Terminal_t myTerminal;
SCF_ListenerHandle_t myListener;
/* (...call SCF_Session_getTerminal to open myTerminal...) */
status = SCF_Terminal_addEventListener(myTerminal,
SCF_EVENT_ALL, &myCallback, NULL, &myListener);
if (status != SCF_STATUS_SUCCESS) exit(1);
/* ... */
}
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_Card_reset(3SMARTCARD), SCF_Ses‐
sion_close(3SMARTCARD), SCF_Session_getTerminal(3SMARTCARD), SCF_Termi‐
nal_updateEventListener(3SMARTCARD), SCF_Terminal_close(3SMARTCARD),
SCF_Terminal_removeEventListener(3SMARTCARD), attributes(5)SunOS 5.10 28 SCF_Terminal_addEventListener(3SMARTCARD)
