DTwainAcquirer::AddListener

Syntax

DTwainAcquirer& AddListener( DTwainListener *pListener );

Parameters

pListener

Pointer to a DTwainListener

Return Value

Returns reference to current DTwainAcquirer object (*this).

Comments

This function adds a DTwainListener to the DTwainAcquirer object.  A listener is used to capture notifications sent from DTWAIN to your application.  For example, if you desire to know when a transfer is ready, when a transfer is completed, whether there is an error in saving the image file, etc. listeners are used.  Listeners are not required, but are highly useful if you need to know the status of what is going on while your application is acquiring images.

You can add as many DTwainListener's to the DTwainAcquirer object as desired.  Each listener that is added will get the notification in the order in which the listener was added to the DTwainAcquirer object.  For example, if you add three listeners, and a OnTransferReady notification is sent, the first listener added will retrieve this notification, then the second listener added will get the notification, and then the third listener that was added will retrieve the notification.

The DTwainListener object must not go out of scope or be destroyed (i.e. the destructor for the DTwainListener should not be invoked) during the lifetime of the acquisition process.  Therefore it is desirable to either create the DTwainListener object using operator new, or declare the object so that it will not be destroyed by going out of scope (i.e. a global object, a member of a class that doesn't get destroyed prematurely, etc.).

See the Example programs for usage of DTwainListener objects.

DTwainListeners are analogous to the DTWAIN Notifications discussed in the main manual.  Note that you do not need to call functions such as DTWAIN_EnableMsgNotify, DTWAIN_SetCallback, etc. to use DTwainListeners -- all of this work is done automatically by the C++ classes.