SCGETEVENT(3) Impressario SCGETEVENT(3)NAME
SCGetEventFD, SCEventPending, SCGetEvent - Receiving events from scanner
drivers
SYNOPSIS
#include <stdio.h>
#include <scanner.h>
int SCGetEventFD(SCANNER *s);
int SCEventPending(SCANNER *s);
int SCGetEvent(SCANNER *s, SCEVENT *event);
DESCRIPTION
Scanner applications need to be prepared to receive events from scanner
drivers. Events are used to inform the scanner application that it must
reread configuration information about the scanner; this is the
information obtained by calls to SCGetPageSize(3), SCGetMinMaxRes(3),
SCGetScannerRes(3), SCGetDataTypes(3), and SCFeederGetFlags(3).
For example, some scanners with transparency units have different scan
areas depending on whether transparent or reflective media is being
scanned. In this scenario, the user would indicate to the driver which
media was present using the scanner specific options program, and if this
changed the effective scanning area the driver would then inform the
application of the change by sending an event.
SCGetEventFD returns a file descriptor that can be passed to the
select(2) system call; when select indicates that the file descriptor is
ready for reading then there is an event pending. SCEventPending returns
1 if an event is currently pending or 0 otherwise. Scanner applications
should either pass the return value of SCGetEventFD to the select system
call, or arrange to periodically call SCEventPending.
SCGetEvent retrieves a pending event. event is a pointer to an EVENT
structure, which is defined in /usr/include/scanners.h as follows:
typedef struct tag_infoChange {
unsigned int pageSizeChanged : 1;
unsigned int resolutionChanged : 1;
unsigned int dataTypesChanged : 1;
unsigned int feederFlagsChanged : 1;
} SCINFOCHANGE;
#define SCEVENT_INFOCHANGE 1
typedef struct tag_scevent {
unsigned int eventType;
union {
SCINFOCHANGE infoChange;
} event;
Page 1
SCGETEVENT(3) Impressario SCGETEVENT(3)
} SCEVENT;
After calling SCGetEvent, event->eventType should be compared to
SCEVENT_INFOCHANGE before assuming that event->event.infoChange is valid;
future versions of Impressario may expand upon the event mechanism.
If event->event.infoChange.pageSizeChanged is 1, then the application
should call SCGetPageSize to query the changed scanning area; if event-
>event.infoChange.resolutionChanged is 1, then the application should
call SCGetMinMaxRes and SCGetScannerRes to query the changed resolutions;
if event->event.infoChange.dataTypesChanged is 1, then the application
should call SCGetDataTypes to query the changed data types; and if
event->event.infoChange.feederFlagsChanged is 1, then the application
should call SCFeederGetFlags to query the changed feeder flags.
For all functions, s is a SCANNER pointer returned by a call to
SCOpen(3), SCOpenFile(3), or SCOpenScreen(3).
RETURN VALUE
SCGetEventFD returns a file descriptor that should be passed to select;
when select indicates that the file descriptor is ready for reading then
there is an event pending.
SCEventPending returns 1 if an event is pending, 0 if no events are
pending, and -1 if an error occurs.
SCGetEvent returns 0 if an event was successfully retrieved and -1 if an
error occurred.
In the event of an error, SCEventPending and SCGetEvent will set SCerrno
to indicate the cause of the error.
EXECUTION ERROR CODES
SCENOEVENTPENDING No event pending
SCECOMM Error communicating with scanner driver
In addition, SCEventPending and SCGetEvent may fail as the result of a
failed system call, in which case SCerrno will be set to a value from
/usr/include/sys/errno.h.
SEE ALSOlibscan(3), select(2).
Page 2
