LWIAACQUIRECALLBACK

#include "ltwia.h"

L_INT pEXT_CALLBACK YourFunction(hSession, pBitmap, pszFilename, uPercent, uFlags, pUserData)

HWIASESSION hSession;

/* handle to an existing WIA session */

pBITMAPHANDLE pBitmap;

/* pointer to the bitmap handle */

L_TCHAR * pszFilename;

/* file name */

L_UINT32 uPercent;

/* the percent completion of the acquire process */

L_UINT32 uFlags;

/* flags that indicates whether the device finished acquiring the page */

L_VOID * pUserData;

/* pointer to additional parameters */

Called for each image being acquired from the WIA source to the application. The address of this callback is passed as an argument in L_WiaAcquire and L_WiaAcquireSimple.

Parameter

Description

hSession

Handle to an existing WIA session. This handle is obtained by calling the L_WiaInitSession function.

pBitmap

Pointer to the bitmap handle that references the bitmap acquired from the WIA source.

pszFilename

Character string containing the name of the file to which to save the scanned image(s). This parameter is valid only if the transfer mode is set to file transfer.

uPercent

The percent completion of the page being scanned.

uFlags

Flag that indicates the start or the end of the scanned page. Possible values are:

 

Value

Meaning

 

0

Default value when this is not the first transferred chunk or the last transferred chunk.

 

L_WIA_ACQUIRE_START_OF_PAGE

[0x00000001] Indicates the start of the page being scanned.

 

L_WIA_ACQUIRE_END_OF_PAGE

[0x00000002] Indicates the end of the page being scanned. Use this value to reset the progress bar.

pUserData

A void pointer that you can use to access a variable or structure containing data that your callback function needs. This gives you a way to receive data indirectly from the function that uses this callback function. (This is the same pointer that you pass in the pUserData parameter of L_WiaAcquire or L_WiaAcquireSimple.)

 

Keep in mind that this is a void pointer, which must be cast to the appropriate data type within your callback function.

Returns

SUCCESS

The function was successful.

ERROR_USER_ABORT

The callback wants to abort the scanning operation.

< 1

An error occurred. Refer to Return Codes.

Comments

This feature is available in version 16 or higher.

This callback will be called through the acquire process to provide the user with the percent completed of the process so he can update his progress bar and at the end it provides him/her with the bitmap handle after its prepared (if the user is doing memory transfer) and also passes the user the L_WIA_ACQUIRE_END_OF_PAGE flag in the uFlags parameter to indicate each end of page.

To prevent memory leaks, the user should free the bitmap within the callback function.

Note:

If you are using WIA 2.0 while the L_WIA_SHOW_USER_INTERFACE is set then no need to provide a callback pointer since Microsofts WIA 2.0 acquire dialog doesnt provide a callback and it does all the process and return back to you with the saved files count and paths.

Required DLLs and Libraries

LTWIA

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

See Also

Functions:

L_WiaAcquire, L_WiaAcquireToFile, L_WiaAcquireSimple, L_WiaInitSession, L_WiaEndSession

Topics:

How to Acquire from the WIA Source

 

WIA Functionality: Property Functions

 

WIA Functionality: Callbacks

Example

For an example, refer to L_WiaIsAvailable.