visit Kofax web site

SPScanner.h File Reference


Detailed Description

SignWare Dynamic Development toolkit, scanner access object.

Author:
uko

Scanner Overview

The SPScanner objects implement access to scanners. The module includes two objects, a scanner enumeration object SPScannerEnum and the scanner device object SPScanner.


The SPScannerEnum object lists all scanner devices for a given Scanner Interface or for all supported Scanner Interfaces. You may choose a device of the returned list and instantiate a SPScanner object based on the device selection.


The SPScanner object will either create an instance of the selected device or popup a selection dialog for the specified scanner class. The popup equals the standard operating system scanner selection dialog.

The SPScanner object details capabilities, and settings of the selected device. Capabilities are read only and list features such as 'Can operate without GUI' etc. Settings can be modified and define the next capture process, see Scanner Settings and Capabilities.

The SPScanner object supports capturing an image with or without vendor GUI. If you choose to capture with vendor GUI then the manufacturers dialog will popup, and the user can setup the desired capture process.

The application must differentiate the connected device when capturing without vendor GUI.

The SPScanner capture process saves one or more SPImage object(s) in the SPScanner object on successfull completion, call SPScannerGetNumberImages and SPScannerGetImage to enumerate the returned image(s).

The Scanner module redirects all requests to the scanner driver. Scanner drivers might have some limitations:

More limitations may apply to the interfaces:

Scanner Settings and Capabilities

The table below lists all supported Settings and Capabilities.

Name C / S Type Description
"DeviceName" C String Device name
"DeviceType" C Int Device type, see DeviceType table below
"DeviceDescription" C String Device description
"DriverClassName" C String Driver Class name ("ScannerTwain", "ScannerWIA", "ScannerWIA2", "ScannerSane", "ScannerDirectShow")
"VendorName" C String vendor name
"DeviceId" C String unique device identifyer
"FirmwareVersion" C String vendor Firmware Version
"DriverName" C String driver name ("Twain", "WIA", "WIA2", "DirectShow" or "Sane")
"InterfaceCaps" C Int Driver builtin GUI, bit pattern of:
1: driver has builtin GUI to select a device
2: driver has builtin GUI to capture an image
"CanUserGui" C Bool Driver supports GUI-less operation
"HasDuplex" C Bool Device has duplex capability
"Papersize" S Int Paper size, see papersize table below
"OffsetX" S Int Horizontal capture Offset, in mm or Pixel for Cameras
"Width" C/S Int Capture Width, in mm or Pixel for Cameras
The capabilities indicate the maximum width
"OffsetY" S Int Vertical capture Offset, in mm or Pixel for Cameras
"Height" C/S Int Capture Height, in mm or Pixel for Cameras
The capabilities indicate the maximum height
"ResolutionX" C/S Int Horizontal resolution [DPI]
The capabilities indicate the maximum optical resolution
"ResolutionY" C/S Int Vertical resolution [DPI]
The capabilities indicate the maximum optical resolution
"ImageFormat" S Int Image format, see Image format table below
"BitsPerPixel" S Int Bits per pixel,
1: Black white
8: gray
24 color
"Threshold" S Int Binarization threshold fore black/white images, range 0 ... 255
"Contrast" S Int Contrast, range 0 ... 1000
"Brightness" S Int Brightness, range 0 ... 1000
"LightSource" S Int Light source, see LightSource table below
"ThumbWidth" C Int Thumbnail width, only camera / video
"ThumbHeight" C Int Thumbnail height, only camera / video
"AutoResize" S Bool Autoresize live video stream, only video, default false
"ForceImageSize" S Bool Resize the captured image if the size exceeds the spcified width or height, only video, default false

Settings and Capabilities table

Cameras and video devices (such as webcams) do not support any Settings.


Value Description
1 default device
2 Scanner
3 Camera
4 Video camera

Device type table


Value Description
2 bmp, Windows Bitmap
3 tiff
4 jpeg
5 png
6 gif

Image format table


Value Description
1 Custom papersize, must pass Width, Height, OffsetX, OffsetY
2 A0
3 A1
4 A2
5 A3
6 A4
7 A5
8 A6
9 A7
10 A8
11 B2
12 B3
13 B4
14 B5
15 B6
16 C3
17 C4
18 C5
19 C6

Papersize table


Value Description
1 Default light source
2 red light source
3 green light source
4 blue light source
5 no light source
6 white light source
7 UV light source
8 IR light source

LightSource table

Note:
All capability names and settings names are case-sensitive.


Typedefs

typedef int(_cdecl * pSPSCANNER_UNSUPPORTEDPROPERTY_T )(pSPSCANNER_T pScanner, const SPCHAR *pszPropertyName, SPINT32 iErrCode)
 Callback to notify the application that a specific property is not supported by the selected device.
typedef int(_cdecl * pSPSCANNER_UPDATE_T )(pSPSCANNER_T pScanner, SPINT32 iCompletion)
 Callback to notify the application on the completion of a capture process in percent.

Functions

SPINT32 __cdecl SPScannerCapture (pSPSCANNER_T pScanner, SPBOOL bWithGui, SPHWND hwndParent)
 Capture one or more images from the selected device.
SPINT32 __cdecl SPScannerCaptureInteractive (pSPSCANNER_T pScanner, SPHWND hwnd)
 Capture an image from a camera or a video device.
SPINT32 __cdecl SPScannerCaptureInteractiveDone (pSPSCANNER_T pScanner, SPINT32 iResult, SPINT32 iOption)
 Finalize a capture process that was started with SPScannerCaptureInteractive.
SPINT32 __cdecl SPScannerClearImages (pSPSCANNER_T pScanner)
 Clear all image.
SPINT32 __cdecl SPScannerCreate (pSPSCANNER_T *ppScanner, pSPPROPERTYMAP_T pDescriptor, SPHWND hwndParent)
 Create a scanner object.
SPINT32 __cdecl SPScannerEnumClone (pSPSCANNERENUM_T pScanner, pSPSCANNERENUM_T *ppScanner)
 Clone a ScannerEnum object.
SPINT32 __cdecl SPScannerEnumCreate (pSPSCANNERENUM_T *ppScanner, const char *pszClass)
 Create a new ScannerEnum object.
SPINT32 __cdecl SPScannerEnumFree (pSPSCANNERENUM_T *ppScanner)
 Free a ScannerEnum object.
SPINT32 __cdecl SPScannerEnumGetDescriptor (pSPSCANNERENUM_T pScanner, SPINT32 iIndex, pSPPROPERTYMAP_T *ppDescriptor)
 Query the descriptor for a enumerated scanner object.
SPINT32 __cdecl SPScannerEnumGetNumberScanners (pSPSCANNERENUM_T pScanner, SPINT32 *piScanners)
 Query the number of scanner devices enumerated in this object.
SPINT32 __cdecl SPScannerFree (pSPSCANNER_T *ppScanner)
 Free a Scanner object.
SPINT32 __cdecl SPScannerGetCapabilities (pSPSCANNER_T pScanner, pSPPROPERTYMAP_T *ppCapabilities)
 Query the capabilities of the scanner object.
SPINT32 __cdecl SPScannerGetImage (pSPSCANNER_T pScanner, SPINT32 iNumberImage, pSPIMAGE_T *ppImage)
 Query an image which was captured with the last capture process.
SPINT32 __cdecl SPScannerGetNumberImages (pSPSCANNER_T pScanner, SPINT32 *piNumberImages)
 Query the number of images which were captured with the last capture process.
SPINT32 __cdecl SPScannerGetSettings (pSPSCANNER_T pScanner, pSPPROPERTYMAP_T *ppSettings)
 Query the settings of the scanner object.
SPINT32 __cdecl SPScannerGetUserLong (pSPSCANNER_T pScanner, SPVPTR *ppUser)
 Query an application specific parameter.
SPINT32 __cdecl SPScannerSetListeners (pSPSCANNER_T pScanner, pSPSCANNER_UNSUPPORTEDPROPERTY_T pNotifyParameterError, pSPSCANNER_UPDATE_T pNotifyUpdate)
 Register Scanner event callback functions.
SPINT32 __cdecl SPScannerSetSettings (pSPSCANNER_T pScanner, pSPPROPERTYMAP_T pSettings)
 Set the settings of the scanner object.
SPINT32 __cdecl SPScannerSetUserLong (pSPSCANNER_T pScanner, SPVPTR pUser)
 Save an application specific parameter.


Typedef Documentation

typedef int( _cdecl * pSPSCANNER_UNSUPPORTEDPROPERTY_T)(pSPSCANNER_T pScanner, const SPCHAR *pszPropertyName, SPINT32 iErrCode)
 

Callback to notify the application that a specific property is not supported by the selected device.

Note:
The application may save a pointer in the SPSCANNER_T object to save state information, see SPScannerSetUserLong, SPScannerGetUserLong
Parameters:
pScanner [i] pointer to a valid SPSCANNER_T object
pszPropertyName [i] the name of the property that is not supported
iErrCode [i] error code as returned by the device driver, typically SP_UNSUPPORTEDERR
Returns:
int, SP_NOERR to ignore the parameter, the driver will use the closest possible value if applicable, or SP_CANCELERR to abort the capture request.

typedef int( _cdecl * pSPSCANNER_UPDATE_T)(pSPSCANNER_T pScanner, SPINT32 iCompletion)
 

Callback to notify the application on the completion of a capture process in percent.

Note:
The application may save a pointer in the SPSCANNER_T object to save state information, see SPScannerSetUserLong, SPScannerGetUserLong
Parameters:
pScanner [i] pointer to a valid SPSCANNER_T object
iCompletion [i] completion of the captur process in percent, range 0 ... 100
Returns:
int, SP_NOERR to continue, or SP_CANCELERR to abort the capture request.


Function Documentation

SPINT32 __cdecl SPScannerCapture pSPSCANNER_T  pScanner,
SPBOOL  bWithGui,
SPHWND  hwndParent
 

Capture one or more images from the selected device.

The captured images will be saved in the pSPSCANNER_T object, call SPScannerGetNumberImages and SPScannerGetImage to retrieve images.

Note:
This function is synchronous, however some drivers may process the windows message queue. The application must assure that it cannot exit while SPScannerCapture is called.
Parameters:
pScanner [i] A valid pSPSCANNER_T object
bWithGui [i] capture mode
  • true: popup the vendor capture GUI and pass the image based on the settings in the dialog
  • false: capture an image based on the local settings, see SPScannerSetSettings,
    GUI less operation is not supported for Video or Camera devices. The application may determine the device type using Property "DeviceType" in the Capabilities map, see SPScannerGetCapabilities
    GUI less operation is permitted for video live streams to capture a snapshot. See SPScannerCaptureInteractive for details to capture a snapshot.
hwndParent [i] Handle to the parent window, dialogs and messages will be modal to the parent window
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
  • SP_UNSUPPORTEDERR the function is not supported
  • SP_SESSIONERR wrong state
  • SP_BUSYERR the device is busy
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)
Example:
// Typical usage with vendor GUI:
int scanImage(pSPPROPERTYMAP_T pDescriptor, HWND hwndParent)
{
    pSPSCANNER_T pScanner = 0;
    int rc = 0;
    int iNumImages = 0;
    rc = SPScannerCreate(&pScanner, pDescriptor, hwndParent);
    if(rc != SP_NOERR) return rc;
    rc = SPScannerCapture(pScanner, true, hwndParent);
    if(rc != SP_NOERR) {
        SPScannerFree($pScanner);
        return rc;
    }
    rc = SPScannerGetNumberImages(pScanner), &iNumImages);
    for(int ik = 0; ik < iNumImages; ik++) {
        pSPIMAGE_T pImage = 0;
        rc = SPScannerGetImage(pScanner, ik, &pImage);
        if(rc == SP_NOERR) showImage(pImage);
        SPImageFree(&pImage);
    }
    SPScannerFree(&pScanner);
    return rc;
}
Example:
// Typical usage without vendor GUI
int scanImage(pSPPROPERTYMAP_T pDescriptor, HWND hwndParent)
{
    pSPSCANNER_T pScanner = 0;
    int rc = 0;
    int iNumImages = 0;
    rc = SPScannerCreate(&pScanner, pDescriptor, hwndParent);
    if(rc != SP_NOERR) return rc;
 
    pSPPROPERTYMAP_T pCaps = 0;
    SPScannerGetCapabilities(pScanner, &pCaps);
    int iType = 0;
    SPPropertyMapGetInt(pCaps, "DeviceType", &iType);
    SPPropertyMapFree(&pCaps);
    // if the device is not a scanner (default device, scanner) then return UNSUPPORTED
    if(iType != 1 && iType != 2) {
        SPScannerFree($pScanner);
        return SP_UNSUPPORTEDERR;
    }
 
    // Popup a dialog to edit settings
    pSPPROPERTYMAP_T pSettings = 0;
    rc = SPScannerGetSettings(pScanner, &pSettings);
    if(popupSettingDialog(hwndParent, pSettings) != SP_NOERR) {
        SPScannerFree($pScanner);
        SPPropertyMapFree(&pSettings);
        return SP_CANCELERR;
    }
    rc = SPScannerSetSettings(pScanner, pSettings);
    SPPropertyMapFree(&pSettings);
    if(rc != SP_NOERR) {
        SPScannerFree($pScanner);
        return rc;
    }
    rc = SPScannerCapture(pScanner, false, hwndParent);
    if(rc != SP_NOERR) {
        SPScannerFree($pScanner);
        return rc;
    }
    rc = SPScannerGetNumberImages(pScanner), &iNumImages);
    for(int ik = 0; ik < iNumImages; ik++) {
        pSPIMAGE_T pImage = 0;
        rc = SPScannerGetImage(pScanner, ik, &pImage);
        if(rc == SP_NOERR) showImage(pImage);
        SPImageFree(&pImage);
    }
    SPScannerFree(&pScanner);
    return rc;
}

SPINT32 __cdecl SPScannerCaptureInteractive pSPSCANNER_T  pScanner,
SPHWND  hwnd
 

Capture an image from a camera or a video device.

This function returns immediately. You must call SPScannerCaptureInteractiveDone to complete the capture process.

This function behaves different depending on the device type:

  • Scanner: not supported
  • Camera: all images currently saved in the camera will be enumerated and thumbnails will be created in the images container when the method returns. Call SPScannerGetNumberImages and SPScannerGetImage to enumerate the returned thumbnails.
  • Video: a live video stream will be displayed in the passed window handle.
    Resizing the live video stream window requires the Setting 'AutoResize' to be set (default is false).
    ScannerDirectShow does not provide for a GUI to display the live video, ScannerDirectShow returns SP_UNSUPPORTED when invoked with GUI
    Call SPScannerCapture (without vendow GUI!) to capture snapshots of the live video stream.
Note:
The twain interface supports cameras and video devices only when using the vendor gui. The Twain implementation of SPScannerCaptureInteractive will return SP_UNSUPPORTEDERR.

The WIA2 interface does not support video cameras, the WIA2 implementation of SPScannerCaptureInteractive will return SP_UNSUPPORTEDERR if the device is a video camera.

The DirectShow interface only supports video cameras (webcams etc). The DirectShow implementation does not offer vendor dialogs to display the live stream ot to select a device, the according methods (SPScannerCapture) return SP_UNSUPPORTEDERR.

Parameters:
pScanner [i] A valid pSPSCANNER_T object
hwnd [i] Handle to the window, the window will be used to display the video stream
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
  • SP_UNSUPPORTEDERR the function is not supported
  • SP_SESSIONERR wrong state
  • SP_BUSYERR the device is busy
Operating Systems:
Windows (Win32)

SPINT32 __cdecl SPScannerCaptureInteractiveDone pSPSCANNER_T  pScanner,
SPINT32  iResult,
SPINT32  iOption
 

Finalize a capture process that was started with SPScannerCaptureInteractive.

Parameters:
pScanner [i] A valid pSPSCANNER_T object
iResult [i] pass SP_NOERR to query the image, SP_CANCELERR to abort the capture process without image transfer
iOption [i] optional parameter, depends on the device
  • Scanner: iOption ignored, pass 0
  • Camera: iOption equals the zero based index of the requested image
  • Video camera: iOption is ignored, pass 0
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
  • SP_UNSUPPORTEDERR the function is not supported
  • SP_SESSIONERR wrong state
  • SP_BUSYERR the device is busy
Operating Systems:
Windows (Win32)
See also:
SPScannerCaptureInteractive

SPINT32 __cdecl SPScannerClearImages pSPSCANNER_T  pScanner  ) 
 

Clear all image.

This method is intended to free resources that may be used by saved images.

Parameters:
pScanner [i] A valid pSPSCANNER_T object
Returns:
SPINT32 result, SP_NOERR on success, else error code
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)

SPINT32 __cdecl SPScannerCreate pSPSCANNER_T ppScanner,
pSPPROPERTYMAP_T  pDescriptor,
SPHWND  hwndParent
 

Create a scanner object.

SPScannerCreate will create the according scanner object if pDescriptor contains a valid driver class string and a valid device identifyer string.
SPScannerCreate will popup a device selection dialog if pDescriptor contains a valid driver class string, but no device identifyer string. If the driver does not provide for a selection GUI and the class enumerates one scaanner driver then this driver will be selected, else SP_UNSUPPORTEDERR will be returned.
The dialog will be modal to the passed parent window handle.
SPScannerCreate will return an error if an invalid driver class string or an invalid device identifyer string is passed.

Note:
The class ScannerDirectShow does not provide for a device selection dialog, you must pass a valid driver string and a valid device identifyer string to instantiate objects of class ScannerDirectShow.
Parameters:
ppScanner [io] pointer to a pSPSCANNER_T object that will be filled with a valid instance of pSPSCANNER_T
pDescriptor [i] valid pSPPROPERTYMAP_T object. pDescriptor must include the scanner class "DriverClassName" and optionally the scanner identifyer in "DeviceId", as returned in a SPScannerEnum object
hwndParent [i] the parent window handle, if the scanner identifyer is not defined
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
  • SP_MEMERR out of memory
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)
See also:
SPScannerEnumCreate for valid scanner class names

SPINT32 __cdecl SPScannerEnumClone pSPSCANNERENUM_T  pScanner,
pSPSCANNERENUM_T ppScanner
 

Clone a ScannerEnum object.

Parameters:
pScanner [i] A valid pSPSCANNERENUM_T object
ppScanner [io] Pointer to a pSPSCANNERENUM_T object that will be filled with a cloned instance of pScanner
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_MEMERR out of memory
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)

SPINT32 __cdecl SPScannerEnumCreate pSPSCANNERENUM_T ppScanner,
const char *  pszClass
 

Create a new ScannerEnum object.

See example below for typical usage of SPSCANNERENUM_T objects.

Parameters:
ppScanner [io] Pointer to a pSPSCANNERENUM_T object that will be filled with a valid instance of a pSPSCANNERENUM_T object
pszClass [i] The scanner class name. The class name may be empty (or NULL) to enumerate all known scanner implementation classes, or may be one of the following:
  • ScannerTwain enumerate twain scanners, only Windows
  • ScannerWIA enumerate WIA scannrs, only Windows
  • ScannerWIA2 enumerate WIA2 scannrs, only Windows, not yet implemented
  • ScannerSane enumerate Sane scannrs, only Linux, not yet implemented
  • ScannerDirectShow enumerate DirectShow video streams, only Windows
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_MEMERR out of memory
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)
Example:
 int SelectScanner(const char *aDeviceId)
 {
     pSPSCANNERENUMT_T pScannerEnum = 0;
     int rc = SPScannerEnumCreate(&pScannerEnum, NULL);
     if(rc != NO_ERR) return rc;
     int iScanners = 0;
     rc = SPScannerEnumGetNumberScanners(pScannerEnum, &iScanners);
     if(rc != NO_ERR) return rc;
     int iMatch = SP_CANCELERR;
     for(int ik = 0; ik < iScanners; ik++) {
         pSPPROPERTYMAP_T pMap = 0;
         rc = SPScannerEnumGetDescriptor(pScannerEnum, ik, &pMap);
         if(rc != SP_NOERR) continue;
         char *pszDeviceName = 0;
         char *pszDeviceId = 0;
         char *pszClassName = 0;
         SPPropertyMapGetString(pMap, "DeviceName", &pszDeviceName);
         SPPropertyMapGetString(pMap, "DriverClassName", &pszClassName);
         SPPropertyMapGetString(pMap, "DeviceId", &pszDeviceId);
         printf("Found Scanner[%d]: Class %s, Device %s\n", ik, pszClassName, pszDeviceName);
         if(strcmp(pszDeviceId, aDeviceId) == 0) iMatch = ik;
         SPFreeString(&pszClassName);
         SPFreeString(&pszDeviceName);
         SPFreeString(&pszDeviceId);
         SPPropertyMapFree(&pMap);
     }
     return iMatch;
 }

SPINT32 __cdecl SPScannerEnumFree pSPSCANNERENUM_T ppScanner  ) 
 

Free a ScannerEnum object.

Parameters:
ppScanner [io] Pointer to a pSPSCANNERENUM_T object that contains a valid instance of a pSPSCANNERENUM_T object
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)

SPINT32 __cdecl SPScannerEnumGetDescriptor pSPSCANNERENUM_T  pScanner,
SPINT32  iIndex,
pSPPROPERTYMAP_T ppDescriptor
 

Query the descriptor for a enumerated scanner object.

Note:
All string values in the PropertyMap will be filled, however some values may be empty
The property "InterfaceCaps" will be identic for all devices within the same class
Parameters:
pScanner [i] A valid pSPSCANNERENUM_T object
iIndex [i] zero based index
ppDescriptor [io] pointer to a pSPPROPERTYMAP_T object that will be filled with a valid pPROPEERETYMAP_T object. The propertymap will include these String elements:
  • "DriverClassName" the driver class name ("ScannerTwain", "ScannerWIA", "ScannerWIA2", "ScannerDirectShow" or "ScannerSane")
  • "DeviceDescription" the scanner description
  • "DeviceName" the scanner device name
  • "DeviceId" the scanner identifyer
  • "DriverName" the name of the driver ("Twain", "WIA", "WIA2", "DirectShow" or "Sane")
  • "VendorName" the scanner vendor
  • "InterfaceCaps" bit combination of builtin dialogs
    • 1: the interface has a builtin GUI to select a device
    • 2: the interface has a builtin GUI to capture an image
  • "DeviceConfiguration" optional configuration string, typically empty
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
  • SP_MEMERR out of memory
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)

SPINT32 __cdecl SPScannerEnumGetNumberScanners pSPSCANNERENUM_T  pScanner,
SPINT32 piScanners
 

Query the number of scanner devices enumerated in this object.

Parameters:
pScanner [i] A valid pSPSCANNERENUM_T object
piScanners [i] pointer to an integer object, that will be filled with the number of scanners enumerated in this pSPSCANNERENUM_T object
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)

SPINT32 __cdecl SPScannerFree pSPSCANNER_T ppScanner  ) 
 

Free a Scanner object.

Parameters:
ppScanner [io] Pointer to a pSPSCANNER_T object that contains a valid instance of a pSPSCANNER_T object
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)

SPINT32 __cdecl SPScannerGetCapabilities pSPSCANNER_T  pScanner,
pSPPROPERTYMAP_T ppCapabilities
 

Query the capabilities of the scanner object.

Note:
Capabilities are read only
Parameters:
pScanner [i] A valid pSPSCANNER_T object
ppCapabilities [io] pointer to a pSPPROPERTYMAP_T object that will be filled with the capabilities of the scanner. Call SPPropertyMapFree if you no longer need the object.
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_APPLERR wrong state, no scanner access point defined
  • SP_MEMERR out of memory
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)
See also:
Scanner Settings and Capabilities

SPINT32 __cdecl SPScannerGetImage pSPSCANNER_T  pScanner,
SPINT32  iNumberImage,
pSPIMAGE_T ppImage
 

Query an image which was captured with the last capture process.

Parameters:
pScanner [i] A valid pSPSCANNER_T object
iNumberImage [i] zero based index to the image
ppImage [o] pointer to a pSPIMAGE_T object that will receive the capture image
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
  • SP_MEMERR out of memory error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)

SPINT32 __cdecl SPScannerGetNumberImages pSPSCANNER_T  pScanner,
SPINT32 piNumberImages
 

Query the number of images which were captured with the last capture process.

Parameters:
pScanner [i] A valid pSPSCANNER_T object
piNumberImages [o] pointer to an integer that will be filled with the number of images available
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)

SPINT32 __cdecl SPScannerGetSettings pSPSCANNER_T  pScanner,
pSPPROPERTYMAP_T ppSettings
 

Query the settings of the scanner object.

Parameters:
pScanner [i] A valid pSPSCANNER_T object
ppSettings [io] pointer to a pSPPROPERTYMAP_T object that will be filled with the settings of the scanner. Call SPPropertyMapFree if you no longer need the object.
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_APPLERR wrong state, no scanner access point defined
  • SP_MEMERR out of memory
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)
See also:
Scanner Settings and Capabilities

SPINT32 __cdecl SPScannerGetUserLong pSPSCANNER_T  pScanner,
SPVPTR ppUser
 

Query an application specific parameter.

The parameter pUser will be saved in the pSPSCANNER_T object, however the pSPSCANNER_T object will not touch the application parameter.

Parameters:
pScanner [i] A valid pSPSCANNER_T object
ppUser [i] a pointer to a SPVPTR variable that will be filled with the application parameter
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)
See also:
SPScannerSetListeners, SPScannerSetUserLong

SPINT32 __cdecl SPScannerSetListeners pSPSCANNER_T  pScanner,
pSPSCANNER_UNSUPPORTEDPROPERTY_T  pNotifyParameterError,
pSPSCANNER_UPDATE_T  pNotifyUpdate
 

Register Scanner event callback functions.

Pass a NULL pointer to deregister a listener.
Callbacks will be called while capturing images.

Parameters:
pScanner [i] A valid pSPSCANNER_T object
pNotifyParameterError [i] callback function that will be invoked if the scanner device does not support a parameter, see pSPSCANNER_UNSUPPORTEDPROPERTY_T
pNotifyUpdate [i] callback function that will be invoked as the capture process progress', see pSPSCANNER_UPDATE_T
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)

SPINT32 __cdecl SPScannerSetSettings pSPSCANNER_T  pScanner,
pSPPROPERTYMAP_T  pSettings
 

Set the settings of the scanner object.

Unknown or unsupported properties are ignored; properties with wrong types are ignored.

Note:
This function overrides those values of the SPScanner settings object, which are set in the provided pSettings object, any other values remain unchanged
Parameters:
pScanner [i] A valid pSPSCANNER_T object
pSettings [i] A valid pSPPROPERTYMAP_T object that contains the settings of the scanner.
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_APPLERR wrong state, no scanner access point defined
  • SP_MEMERR out of memory
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)
See also:
Scanner Settings and Capabilities

SPINT32 __cdecl SPScannerSetUserLong pSPSCANNER_T  pScanner,
SPVPTR  pUser
 

Save an application specific parameter.

The parameter pUser will be saved in the pSCANNER_T object, however the pSCANNER_T object will not touch the application parameter.

Parameters:
pScanner [i] A valid pSPSCANNER_T object
pUser [i] an application parameter
Returns:
SPINT32 result, SP_NOERR on success, else error code
  • SP_PARAMERR parameter error
Operating Systems:
Windows (Win32), Linux (i386), Linux (x86_64)
See also:
SPScannerSetListeners, SPScannerGetUserLong