DTWAIN_SetCallback
|
The DTWAIN_SetCallback allows an application to use a callback function for DTWAIN notifications.
DTWAIN_CALLBACK_PROC DTWAIN_SetCallback (
Parameters lpProc A pointer to a function that will be called whenever a DTWAIN notification is sent, or NULL to turn off the callback mechanism.
UserData Optional user-defined data that will be passed when Callback function is invoked. If the UserData requires a 64-bit type, use DTWAIN_SetCallback64.
Return Values If a callback function was previously set, this function returns the last callback function. Otherwise a NULL is returned.
Comments DTWAIN_SetCallback allows an application to use a callback function for DTWAIN notifications instead of a window handle. Whenever an image is being acquired, notifications are sent to the user-application as to the current status of the acquisition. Usually, notifications are sent to the window handle that is used in the call to DTWAIN_StartTwainSession. With DTWAIN_SetCallback, a user-defined function will be called for the notifications. The advantage of using callback functions over a window procedure to route the notifications is that an application may not even have a window, but would still desire to retrieve notifications. Another advantage is that you can keep the window procedure clean of any code associated with DTWAIN. To retrieve the current callback function pointer, the DTWAIN_GetCallbackfunction is used.
To enable DTWAIN_SetCallback, the DTWAIN_EnableMsgNotify must have previously been called with a TRUE value. If both has been called with a valid window handle as the first parameter and there is a callback set with DTWAIN_SetCallback, the window procedure will always get the notification first, and then the callback will get the same notification afterwards. Therefore if both notification techniques (window procedure and callback) are used, your application must make sure that the callback will ultimately control what happens, since it is the final functions that will be called when a notification is sent.
The DTWAIN_CALLBACK_PROC is a function pointer with the following prototype:
LRESULT CALLBACK DTWAINCallbackProc(WPARAM wParam, LPARAM lParam, LONG UserData);
where LRESULT is actually a LONG value. The CALLBACK is a constant defined by Windows.h to signify that this function will be a callback function (the CALLBACK constant is only important for C or C++ programs). The wParam and lParam values are the WPARAM and LPARAM of the notification that is sent to the procedure. The WPARAM and LPARAM values are exactly the same values that are sent when a DTWAIN notification is sent to a window. For example, if WPARAM is DTWAIN_TN_ACQUIREDONE, the LPARAM is actually the DTWAIN_SOURCE that has finished acquiring an image.
The DTWAIN callback function must always return TRUE for proper processing to be done. The only exception to this rule is if the WPARAM value is DTWAIN_TN_PAGECONTINUE or DTWAIN_TN_PAGEFAILED.
For DTWAIN_TN_PAGECONTINUE, if the return value from the callback function is TRUE, the next page will be acquired. If the return value is FALSE, no more pages are acquired.
For DTWAIN_TN_PAGEFAILED, the return value of the callback should be either 0, 1, or 2, depending on the following
Note that the return value for DTWAIN_SetCallback is the previously set callback function. The reason for the return value being the previously set function is that this will allow function chaining. For example, if you need to override the behavior of a previous callback function, you install your function, and store the pointer to the old function. Whenever your callback gets called, you can do whatever processing needs to be done with your handler, and then call the old handler that your application saved somewhere to do the default handling (or possibly you call the old handler first, and then your new handler finishes up).
See DTWAIN Notifications Using a Callback Function for more details.
TWAIN State Transitions None.
Prerequisite Function Call(s)
See Also |