DTWAIN_GetCustomDSData
|
The DTWAIN_GetCustomDSData retrieves the custom data from a Source.
HANDLE DTWAIN_GetCustomDSData (
Parameters: Source An open TWAIN Source.
lpData A pointer to an array of BYTE's where the retrieved Source data will be copied, or NULL
nSize Specifies the number of bytes to copy to lpData. If lpData is NULL, this argument is ignored.
pActualSize On return, filled in with the actual size of the source data.
nFlags Flags to determine how to interpret the lpData and nSize arguments.
Returns: A Global HANDLE to the source data or a positive number. If there is an error, NULL is returned.
Comments: DTWAIN_GetCustomDSData uses the DAT_CUSTOMDSDATA TWAIN group to retrieve the Source's custom data. This is usually done after the application calls the DTWAIN_ShowUIOnly function so the application can retrieve the set values. To test if the Source supports custom data, call DTWAIN_IsCustomDSDataSupported. Usually mid to high-volume scanners support this type of operation.
Note: The format of the returned data is Source dependent and is not defined by TWAIN, therefore your application must have knowledge of the format of the data from the creator of the Source. Usually the manufacturer of the device has specifications as to what format the data is returned and how to interpret the data..
Depending on the value of the nFlags argument, the return value will be the global handle to the Source data. The application must call the Windows API function GlobalLock to retrieve the data from the handle, and also be responsible for calling GlobalUnlock and GlobalFree to release the handle and return the memory back to the operating system.
If the application does not desire to do the memory management, an alternative is for the application to specify that the data be placed in a buffer pointed to by the lpData parameter. The nSize argument determines how many bytes of data to copy to lpData. If nSize is -1, all of the data must be copied to lpData. The application must make sure that there is enough room to copy the data.
If the application wants to know the size of the data so as to set aside the correct amount of memory, specify 0 as the nSize value and call DTWAIN_GetCustomDSData. The pActualSize argument that is returned will be the size of the data. A subsequent call to DTWAIN_GetCustomDSData with nSize equal to this value will copy the data to lpData.
The pActualSize argument is always filled in with the actual size in bytes of the Source data. If pActualSize is NULL, no value is copied.
The nFlags argument must be one of the following values: DTWAINGCD_RETURNHANDLE DTWAINGCD_COPYDATA
The DTWAINGCD_RETURNHANDLE setting ignores the lpData and nSize arguments, and only returns a handle to the data. The application is then responsible for locking the handle with GlobalLock( ) and later freeing the handle with GlobalUnlock / GlobalFree( ).
The DTWAINGCD_COPYDATA uses the lpData and nSize arguments to copy the source data to lpData. If nSize is -1, all of the data is copied to lpData. If nSize is 0, the pActualSize argument is filled in with the size of the data, and no data is copied. This is useful if you want to know the size of the Source data to determine how many bytes to reserve for lpData. With DTWAINGCD_COPYDATA the application does not make any calls to GlobalLock( ), GlobalFree( ), etc. All of this memory management is handled internally by DTWAIN. The return value when using DTWAINGCD_COPYDATA is a positive integer on success. This return value is not a valid global handle, so it cannot be freed. It is only for informational purposes to let your application know whether the function is successful.
To set the Source's custom data, call DTWAIN_SetCustomDSData.
TWAIN State Transitions The Source must be in State 4 or higher
Prerequisite Function Call(s)
DTWAIN Source Selection Function
See Also |