SCGetEventFD(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;
          } 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 ALSO
     libscan(3), select(2).