The SCANINFO data structure is used to store static information about a scanner. The scan.c module uses SCANINFO to communicate with the main.c module. The SCANINFO data structure is defined as follows:

typedef struct tag_scaninfo {
   int metric;                                /* metric for res, page size*/
   float pagex, pagey, pagewidth, pageheight; /* page size */
   float minxres, maxxres, minyres, maxyres;  /* resolution bounds */
   float *xres, *yres;                        /* resolution arrays */
   int nres;                                  /* size of arrays */
   int canZoom;                               /* 1 if scanner can zoom */
   SCDATATYPE *types;                         /* supported types */
   int ntypes;                                /* number of types */
   SCANFUNC *options;                         /* scanner-specific options */
   int noptions;                              /* number of options */
   void *priv;                                /* private member */
   SCFEEDERFLAGS feederFlags;                 /* feeder flags */
} SCANINFO;

Field definitions:

The SCANPARAMS data structure contains dynamic values used to specify the parameters of a scanning operation, and also some administrative details. The SCANPARAMS data structure is defined as follows:

typedef struct tag_scanparams {
    float xres, yres;
    float x, y, width, height;
    SCDATATYPE type;
    int preview;
    SCQUEUE *scanq, *sfreeq;
    int xpixels, ylines, xbytes;
    void (*convert)(void *from, int fromx, void *to, int tox, int *zmap);
    int maxmem; /* maximum amount of memory to allocate */
    int readlines;
    SCANINFO *s;
} SCANPARAMS;

The fields of the SCANPARAMS data structure are defined as follows:

This function is called when the driver is first invoked.

For example:

SCANINFO *
OpenScanner(char *dev)
{
    static SCANINFO scan;
    
    /*
    Your code here!
    */

    if (something goes wrong) {
        drverr = appropriate error code;
        return NULL;
    }
    */
    
    return &scan;
}

dev is the name of the device (usually a device special file in /dev/scsi for SCSI devices) to open in order to communicate with the scanner. The task of the OpenScanner() function is to “open” dev, make sure that it corresponds to a device that scan.c knows how to talk to, get it into some reasonable initial state, and fill in a SCANINFO structure for the scanner. If all goes well, a pointer to the SCANINFO structure is returned.

If anything goes wrong, OpenScanner() should set the global variable drverr and return NULL. The value for drverr should be chosen from those in /usr/include/sys/errno.h or /usr/include/scanner.h; that value is communicated back to the scanning application, which can use the SCPerror() or SCErrorString() functions in libscan.a to get a human-readable error message that explains why OpenScanner() failed.

---

Caution: If you are writing a driver for a SCSI scanner, and you are using dslib(3X), make sure that you pass the O_EXCL flag defined in /usr/include/fcntl.h to dsopen:

---

dsreq_t *dsp = dsopen(dev, O_RDONLY | O_EXCL);

If you pass the O_EXCL flag, the open will fail with errno set to EBUSY if dev is the /dev/scsi device of a mounted disk; otherwise, the open can succeed and you could really screw up the disk!

In addition, it is recommended that before issuing any other SCSI commands you perform an inquiry command, and verify that the device is a scanner by examining the Device Type code of the inquiry buffer. (This field should be set to 6. You can use the INV_SCANNER #define from /usr/include/invent.h.) It is also recommended that you examine the vendor and product identifiers to make sure the device is a scanner of the type for which this driver is being written.

This function is called with a pointer to a SCANPARAMS struct to prepare for a scanning operation.

For example:

int
SetupScan(SCANPARAMS *params)
{
    /*
    Your code to tell the scanner the resolution, scanning window, 
    and data type.
    */
    
    /*
    Your code to find out from the scanner how many pixels are in a scan
    line, how many scan lines are in the scan, and how many bytes are
    in a scan line.
    */
    
    /*
    Your code to figure out what readlines should be, taking into
    consideration maxmem and xbytes.
    */
    
    if (anything went wrong) {
        drverr = an appropriate error code;
        return -1; /* indicates failure */
    }
    
    return 0; /* indicates success */
}

SetupScan() performs the following operations:

This function retrieves the data from the scanner.

For example:

void
DoScan(SCANPARAMS *params)
{
    SCANINFO *s = params->s;
    void *buf;
    int row, toread, curline;
   
    prctl(PR_TERMCHILD);
   
    for (curline = 0; curline < params->ylines;
        curline += params->readlines) {
        toread  = MIN(params->readlines, 
                  params->ylines - curline);
   
        buf = SCDequeue(params->sfreeq);
        /*
         * Get the scan data here!
         */
   
        /*
         * Chop the buffer up into scan line sized chunks
         */
        while (toread--) {
            SCEnqueue(params->scanq, buf);
            buf = (char *)buf + params->xbytes;
        }
    }
   
    exit(0);
}

DoScan() executes as its own process, sharing its address space with its parent, which is the process that communicates with the scanning application. (See the sproc(2) reference page. DoScan() is the entry parameter to sproc.)

Before entering the while loop, do whatever else is necessary to initialize the scanner if there's unfinished business from SetupScan(). Note the use of params->readlines, which you set in SetupScan(). In the body of the loop, the following things happen:

Since DoScan() is its own process, it calls the exit function instead of returning when it finishes scanning. If everything goes OK, DoScan() calls exit with a status of 0. If anything goes wrong, DoScan() sets the global variable drverr to an appropriate value from sys/errno.h or scanner.h and calls exit with a status of 1. (See the exit(2) reference page.)

The SetFeederFlags() function is called when the scanner application calls SCFeederSetFlags to specify whether automatic (SC_AUTOFEED) or programmatic (SC_PROGFEED) feeding is desired. This only happens if the feederFlags member of the SCANINFO struct returned by OpenScanner() has all three of the SC_HASFEEDER, SC_AUTOFEED, and SC_PROGFEED bits set.

For example:

int
SetFeederFlags(SCANINFO *scan, SCFEEDERFLAGS flags)
{
    drverr = SCENOFEEDER;
    return -1;
}

The template version of this function sets drverr to indicate that no feeder is present; if a feeder is present, SetFeederFlags() must set a flag so that it knows whether to automatically feed the next document in the next call to DoScan().

The AdvanceFeeder() function is called only if the SC_PROGFEED bit is set in the feederFlags member of the SCANINFO struct returned by OpenScanner(). This function should advance the feeder to the next document. If the feeder is empty or jammed, return -1 and set drverr to an appropriate error code from /usr/include/scanner.h or /usr/include/sys/errno.h.

For example:

int
AdvanceFeeder(SCANINFO *scan)
{
    drverr = SCENOFEEDER;
    return -1;
}

This function is called only if the SC_HASFEEDER bit of the feederFlags field of the SCANINFO struct returned by OpenScanner() is set.

For example:

int
FeederReady(SCANINFO *scan)
{
    drverr = SCENOFEEDER;
    return -1;
}

FeederReady() should return 0 if there is a document in the feeder; that is, if the next call to AdvanceFeeder() should succeed. If the feeder is empty, FeederReady() should return -1 and set drverr to SCFEEDEREMPTY.

The PrintID() function is used by the -query option that all scanner drivers support. It should print a string that identifies the type of scanner supported by this scanner driver, and one or more interface types supported. The scanner install tool, scanners, uses this information to help the end user choose the driver that best suits a particular scanner.

For example:

void
PrintID(FILE *fp)
{
    fprintf(fp, "Your Scanner Name\n");   /* String describing scanner */
    fprintf(fp, "SCSI Serial Parallel\n"); /* Device type; can be list */
}

The FindScanners() function is also used to implement the -query option.

For example:

void
FindScanners(FILE *fp)
{
    inventory_t *inv;
    char device[100];
    dsreq_t *dsp;
    /* int because it must be word aligned. */
    int inqbuf[(sizeof(INQDATA) + 3)/sizeof(int)];
    INQDATA *inq = (INQDATA *)inqbuf;
    
    /*
     * This example looks for SCSI scanners; do whatever is necessary
     * to find other types of scanner here.
     */
    setinvent();
    while ((inv = getinvent()) != NULL) {
        if (inv->inv_class == INV_SCSI && inv->inv_type == INV_SCANNER) {
            sprintf(device, "/dev/scsi/sc%dd%dl0", inv->inv_controller,
               inv->inv_unit);
            if ((dsp = dsopen(device, O_RDONLY)) == NULL) {
                continue;
            }
    
            if (inquiry12(dsp, (char *)inq, sizeof *inq, 0) == 0
               && strncmp((char *)inq->vid, "Your vendor", 11) == 0 &&
               strncmp((char *)inq->pid, "Your product", 12) == 0) {
                  fprintf(fp, "SCSI %s\n", device);
            }
            dsclose(dsp);
        }
    }
    
    endinvent();
}

FindScanners() should search the system for scanners that this driver is capable of supporting, and for each such scanner it prints the type of device (SCSI, Serial, Parallel, GPIB, EISA, or Other), a space, and the pathname that should be passed to OpenScanner() in order to access that scanner.

This gives scanners more information that it can use to help the end user pick a driver for a particular scanner. It is by no means required that FindScanners() find all scanners that it is capable of supporting; it is OK to do nothing at all here, especially if there is no hope of finding a scanner you support in a reasonable amount of time. This is important; scanners invokes EVERY scanner driver installed with the -query option when the user adds a scanner, so this function should be fast!

This function is called when the scanner driver is invoked with the -install option. InstallScanner() is used by scanners when the user tries to install a new scanner.

For example:

int
InstallScanner(char *dev)
{
   printf("The template driver doesn't support %s\n", dev);
   return -1;
}

The purpose of this entry point is verify that dev corresponds to a scanning device that this driver knows how to support, and to do any scanner-specific installation that is necessary.

The following example implementation calls OpenScanner() to verify that dev corresponds to a valid scanning device, and then changes the permissions of dev so that users other than root can access the scanner. This is important, because scanner drivers should not normally be set to user ID root programs, and users other than root want to use scanners. When InstallScanner() is called by scanners, the driver will have root permissions, which enables it to call chmod(2) on dev or create any auxiliary files or other resources that it needs:

int 
InstallScanner(char *dev)
{
    SCANINFO *scan;
    
    scan = OpenScanner(dev);
    
    if (!scan) {
        printf("Can't access %s: %s\n", dev, 
                SCErrorString(drverr));
        return -1;
    }
    
    chmod(dev, 0666);
    return 0;
}

If an error occurs, InstallScanner() should print an error message to standard out and return -1. The main.c module exits with a nonzero exit status if InstallScanner() returns -1, and scanners reads the driver's standard output and displays it to the user if the main.c exits with a nonzero status. That way, the exact cause of the error is propagated to the user.

The DeleteScanner() function is called when the driver is invoked with the -delete option by scanners. This gives the driver the opportunity to do any scanner-specific deletion required. This can be useful if auxiliary files specific to this scanner were created in InstallScanner().

For example:

int 
DeleteScanner(char *dev)
{
   return 0;
}

If an error occurs, DeleteScanner() prints an error message to standard out and returns -1. In this case, scanners displays this error message to the user and refuses to delete the scanner, so in most cases DeleteScanner() should return 0.