SCGetSaveOptions(3)

NAME
     SCGetSaveOptions, SCSetSaveOptions - Getting and setting saved scanner
     specific options

SYNOPSIS
     #include <stdio.h>
     #include <scanner.h>

     int SCGetSaveOptions(SCANNER *s, void **options, int *nBytes);

     int SCSetSaveOptions(SCANNER *s, void *options, int nBytes);

DESCRIPTION
     SCGetSaveOptions and SCSetSaveOptions exist as a mechanism for scanner
     applications to save scanner specific settings for later restoration.
     gscan(1) uses these functions to save scanner specific settings when you
     choose "Save Current Settings..." from the "Setup" menu.

     SCGetSaveOptions retrieves a sequence of bytes which when passed back to
     the scanner driver via a subsequent call to SCSetSaveOptions restores the
     scanner specific settings for s to what the were at the time that
     SCGetSaveOptions was called.

     For both functions, s is a SCANNER pointer returned by a call to
     SCOpen(3), SCOpenFile(3), or SCOpenScreen(3).

     After SCGetSaveOptions returns successfully, *options will point to
     *nBytes bytes worth of scanner specific options settings.  The layout of
     this memory is completely at the discretion of the scanner driver and
     should not be interpreted in any way by the scanner application.  The
     only thing the application should do with this memory is save it to a
     permanent location for later restoration.  The memory pointed to by
     *options is owned by libscan(3) and should not be modified or freed, and
     should not be expected to maintain its contents across subsequent calls
     to SCGetSaveOptions.

     For SCSetSaveOptions, options is a pointer to nBytes of memory which will
     be transmitted to the scanner driver as scanner specific options
     settings.  The only valid way for a scanner application to have obtained
     data for passing to SCSetSaveOptions is to have previously called
     SCGetSaveOptions and saved the results.

RETURN VALUE
     SCGetSaveOptions and SCSetSaveOptions return 0 if successful, and -1 if
     an error occurs.  In the event of an error, SCerrno will be set to
     indicate the cause of the error.

EXECUTION ERROR CODES
     SCENOSAVEOPT             No scanner specific savable options
     SCENOMEM                 Out of memory

     SCECOMM                  Error communicating with scanner driver

WARNING
     The pointer obtained by calling SCGetSaveOptions points to memory owned
     by libscan(3).  The calling program should not modify the memory pointed
     to by the return value of SCGetSaveOptions, nor should any assumptions be
     made about its value after subsequent calls to SCGetSaveOptions. Any
     needed information should be copied into program memory before calling
     SCGetSaveOptions again.

SEE ALSO
     libscan(3).