SCGETSAVEOPTIONS(3) Impressario 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);
DESCRIPTIONSCGetSaveOptions 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 VALUESCGetSaveOptions 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
Page 1
SCGETSAVEOPTIONS(3) Impressario SCGETSAVEOPTIONS(3)
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 ALSOlibscan(3).
Page 2
