|
DTWAIN_SetUpdateDibProc |
Top Previous Next |
|
The DTWAIN_SetUpdateDibProc allows an application to use a callback function to an acquired image from a TWAIN device..
DTWAIN_DIBUPDATE_PROC DTWAIN_SetUpdateDibProc ( DTWAIN_DIBUPDATE_PROC lpProc );
Parameters lpProc A pointer to a function that will be called whenever an image is acquired.
Return Values If a callback function was previously set, this function returns the last callback function. Otherwise a NULL is returned.
Comments DTWAIN_SetUpdateDibProc allows an application to use a callback function for access to the image that is acquired. The image is in the form of a Device Independent Bitmap (DIB), and is the image directly acquired from the device before DTWAIN further processes the image.
The DTWAIN_DIBUPDATE_PROC is a function pointer with the following prototype:
HANDLE CALLBACK DibUpdateCallbackProc( DTWAIN_SOURCE Source, LONG CurrentPage, HANDLE hDib );
The return value will be either 0, or a HANDLE to a new DIB that the application will replace with the current DIB. If the return value is 0, then the original DIB, denoted by hDib is used by DTWAIN. The Source argument is the current DTWAIN_SOURCE that acquired the image. The CurrentPage is the current page number of the DIB. The hDib is the HANDLE to the image that was acquired for page CurrentPage.
The callback function is allowed to replace the DIB represented by hDib with another DIB if that is what is desired. For example, the application may want to access the DIB, and then do some image processing on the DIB before returning from the callback function.
If your application desires to inspect and possibly change the DIB in some way, you can use this callback function for this purpose. For example, if you are using another imaging library that adjusts the DIB (maybe rotate it, change the bits-per-pixel, etc.), you can accomplish it by using the callback.
There are rules if you plan to take the DIB hDib and change it in any way:
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 |