void SCPerror(char *ident)

This function prints the value of ident, a colon, and a string of text corresponding to the current value of SCerrno.

char *SCErrorString(int err)

This function returns a character string containing a useful message describing the error condition represented by err. If err is not in the range 0 to LASTERRNO or SCEBASE to SCELAST, SCErrorString() returns a text string containing the words “Error code err,” where err is the value passed to SCErrorString().

SCANNER *SCOpen(char *name)

The SCOpen() function prepares to perform operations on the scanner named by name by starting the appropriate driver on the appropriate device. SCOpen() performs the lookup in the name -> (driver, device, options) mapping. If name is NULL, the default scanner is used.

SCOpen() returns a pointer to a SCANNER struct if successful, or NULL if there is an error. If name is NULL and no default scanner has been set, SCOpen() opens the first scanner found in /usr/lib/scan/scanners.

SCANNER *SCOpenScreen(char *screen)

This function invokes the screen scanner driver to scan from the specified screen. It returns a pointer to a SCANNER struct if successful, NULL if there is an error.

SCANNER *SCOpenFile(char *file)

This function invokes the file scanner driver to scan from the specified file. It returns a pointer to a SCANNER struct if successful, NULL if there is an error.

int SCClose(SCANNER *s)

This function breaks the connection between the application and the driver program. It returns 0 on success, -1 if there is an error.

FILE *SCSetScanEnt(void)

This function opens the scanner configuration file. It returns a pointer to the open FILE structure on success, NULL if there is an error.

typedef struct tag_scanent {
   char *name;
   char *driver;
   char *device;
   char *options;
} SCANENT;

SCANENT *SCGetScanEnt(FILE *fp)

To get a SCANENT structure for each scanner installed on the system, this function should be called repeatedly until it returns NULL. The contents of the memory pointed to by the return value of SCGetScanEnt() are undefined after any subsequent calls to this function, so copy the return value if you need to preserve it across calls to SCGetScanEnt().

int SCEndScanEnt(FILE *fp)

This function frees the resources used to enumerate scanners. It returns 0 on success, -1 if there is an error.

char *SCScannerName(SCANNER *s)

This function returns the name associated with the scanner at installation. Applications can use this to get at the name of the default scanner being used if SCOpen() was called with NULL. It returns a pointer to a character string on success, NULL if there is an error. The memory pointed to by the return value of SCScannerName() belongs to libscan and should not be modified or freed.

SCANENT *SCScannerEnt(SCANNER *s)

This function returns a SCANENT structure describing an open scanner. The memory pointed to by the returned value of SCScannerEnt() belongs to libscan and should not be modified or freed.

char *SCDefaultScannerName(void)

This function gets the default scanner name, if any. It returns the name of the default scanner, or NULL if no default scanner has been set. The memory pointed to by the returned value of SCDefaultScannerName() belongs to libscan and should not be modified or freed.

int SCGetScannerRes(SCANNER *s, int metric,
    float **xres, float **yres, int *nres)

This function returns arrays of hardware-supported resolutions. The xres and yres arrays specify supported horizontal and vertical resolutions. metric should be one of SC_INCHES or SC_CENTIM. nres sets the number of resolution pairs in the xres and yres arrays. SCGetScannerRes() returns 0 if successful, -1 if there is an error.

int SCGetMinMaxRes(SCANNER *s, int metric,
    float *minx, float *miny, float *maxx, float *maxy);

This function determines the resolution bounds; that is, the minimum and maximum horizontal and vertical resolutions that the scanner supports. It is an error to call SCGetMinMaxRes() with metric equal to SC_PIXELS. SCGetMinMaxRes() returns 0 if successful, -1 if there is an error.

int SCGetPageSize(SCANNER *s, int metric, float *x, float *y,
                  float *width, float *height)

This function gets the entire scannable area. It is an error to call it with metric equal to SC_PIXELS. SCGetPageSize() returns 0 if successful, -1 if there is an error.

int SCGetDataTypes(SCANNER *s, SCDATATYPE **dt, int *ntypes)

This function sets *dt to point to an array of the data types supported by the scanner driver. ntypes gets the number of data types supported. The memory pointed to by *dt belongs to libscan and should not be modified or freed. It should also not be expected to retain its values after subsequent calls to SCGetDataTypes().

SCSetup(SCANNER *s, int preview, SCDATATYPE *type,
      int rmetric, float xres, float yres,
      int wmetric, float x, float y, float width, 
      float height)

This function is used to prepare the scanner for a scan. The type of data, the resolution, and the scanning area are specified. preview is nonzero if this is a “preview” scan; that is, when the driver is faced with a trade-off between speed and image quality, it should choose speed, because this is not the “real” scan. After calling SCSetup(), SCScan() is called to initiate scanning. SCSetup() returns 0 if successful, -1 if there is an error.

int SCGetScanSize(SCANNER *s, int *width, int *height,
                  int *bytesPerLine)

This function is called after SCSetup() to determine the width, height, and number of bytes per scan line that will be returned by the driver. It returns 0 if successful, -1 if there is an error.

int SCScan(SCANNER *s)

This function tells the driver to start scanning. The driver immediately starts to scan and buffer the data. SCScan() does not fetch any scan data (see SCGetScanLine()). SCScan() returns 0 if successful, -1 if there is an error.

int SCGetScanLine(SCANNER *s, void *buf, int bytes)

This function retrieves scan line data. bytes should be set to the number of bytes in a scan line as determined by SCGetScanSize().

Note that for color planar data, SCGetScanLine() is called once for each line in each plane of data. For 100 lines of 24-bit RGB planar data, SCGetScanLine() is called a total of 300 times, with the first 100 calls retrieving the red plane, the second 100 calls retrieving the green plane, and the third 100 calls retrieving the blue plane.

int SCDataReady(SCANNER *s)

This function is used to determine whether any data is available for calls to SCGetScanLine(); that is, whether a call to SCGetScanLine() will block waiting for data to become available.

SCDataReady() returns 1 if data is available (SCGetScanLine() will not block), 0 if no data is available (SCGetScanLine() will block), or -1 if there is an error. It is an error to call SCDataReady() if scanning was started by a call to SCScanFD().

int SCGetFD(SCANNER *s)

This function returns the file descriptor over which scan data from the scanner driver comes. Checking the state of this descriptor with the select(2) system call is equivalent to calling SCDataReady(). If SCScanFD() was called, SCGetFD() returns the file descriptor that was passed to that function. SCGetFD() returns -1 if there is an error.

int SCScanFD(SCANNER *s, int fd)

This function is an alternative to calling SCScan() to start scanning and SCGetLine() to fetch the data. After SCScanFD() is called, the driver writes the scanned data to fd; this is useful if the output data format of the scanner interface matches the input data type of another interface. SCScanFD() returns 0 if successful, -1 if there is an error.

int SCAbort(SCANNER *s)

This function aborts the current scan. Data buffered by the driver is discarded. SCAbort() returns 0 if successful, -1 if there is an error.

enum scstate { SC_READY, SC_SCANNING, SC_ERROR };
typdef struct tag_scstatus {
    enum scstate state;      /* ready, scanning, error */
    int errno;               /* only valid if state == SC_ERROR */
    long curline;            /* current line being scanned */
    int pass;                /* current scanning pass */
} SCSTATUS;

int SCGetStatus(SCANNER *s, SCSTATUS *st)

This function gets the status of the scanner. It returns 0 if successful, -1 if there is an error.

int SCGetStatusFD(SCANNER *s)

This function 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, the scanner driver has updated the scanning status. Retrieve the status by calling SCGetStatus(); do NOT pass the file descriptor returned from SCGetStatusFD() to any other system call.

SCGetStatusFD() provides a mechanism whereby it is not necessary for an application to periodically call SCGetStatus() in a timer loop to detect changes in scanner status. SCGetStatusFD() returns -1 if there is an error.

typedef unsigned int SCFEEDERFLAGS;

#define SC_HASFEEDER 1
#define SC_AUTOFEED  2
#define SC_PROGFEED  4

int SCFeederGetFlags(SCANNER *s, SCFEEDERFLAGS *flags);

This function fills in the flags variable with flags appropriate for the scanner associated with s. If SC_AUTOFEED and SC_PROGFEED are both set, SCFeederSetFlags() should be called before any calls to SCScan() to establish how the application is to interact with the feeder. The meanings of the flags are as follows:

SCFeederGetFlags() returns 0 if successful, -1 if there is an error.

int SCFeederSetFlags(SCANNER *s, SCFEEDERFLAGS flags);

This function should be called before calling SCScan() for scanners in which SCFeederGetFlags() sets both SC_AUTOFEED and SC_PROGFEED. After calling SCFeederSetFlags(s, SC_AUTOFEED), the feeder advances to the next document after every call to SCScan(). After calling SCFeederSetFlags(s, SC_PROGFEED), a call to SCFeederAdvance() is necessary to advance to the next document. SCFeederSetFlags() returns 0 if successful, -1 if there is an error.

int SCFeederAdvance(SCANNER *s)

This function advances the feeder to the next document. This call is valid only if the scanner supports the SC_PROGFEED mode. For scanners that support both the SC_AUTOFEED and SC_PROGFEED modes, SCFeederSetFlags(s, SC_PROGFEED) must have been called previously.

SCFeederAdvance() returns 0 if successful, -1 if there is an error. When unloading the last document, this function returns -1 with SCerrno set to SCFEEDEREMPTY.

int SCFeederReady(SCANNER *s)

This function checks if the feeder is ready for feeding. SCFeederReady() returns 0 if the feeder is ready, -1 if not. If the feeder is empty, SCerrno is set to SCFEEDEREMPTY; if any other error conditions exist, SCerrno is set appropriately.

Note that this function needs to be called before SCFeederAdvance() to determine whether a document is ready to be scanned after the call to SCFeederAdvance().