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 the 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 == 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 == 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 since this is not the "real" scan. After calling SCSetup, SCScan is called to actually 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 will be coming. 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(2) 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.