Importing TwainPRO as a COM Object

TwainPRO provides the dual interface necessary to import a component as a COM object. The following technique illustrates how to use TwainPRO as an imported COM object in Visual C++. References will be made to files in the TwainPRO Visual C++ sample, twnpro.dsw, and the pertinent statements are shown in boldface.

1. Import a Control into Visual C++

The #import directive line can be added to the stdafx.h file to provide the appropriate functionality to all source files in the project.

C++ Example	Copy Code
#include "TwainPro9Events.h" // CTwnPRODlg dialog class CTwnPRODlg : public CDialog, CTwnPROEventHandler { // Construction public: CTwnPRODlg(CWnd* pParent = NULL); // standard constructor // this will be the pointer to our COM instance CTwainPRO *ppCTwainPRO; ITwainPROPtr pTwainPRO;

C++ Example

Copy Code

#include "TwainPro9Events.h"
// CTwnPRODlg dialog
class CTwnPRODlg : public CDialog, CTwnPROEventHandler
{
// Construction
public:
CTwnPRODlg(CWnd* pParent = NULL); // standard constructor
// this will be the pointer to our COM instance
CTwainPRO *ppCTwainPRO;
ITwainPROPtr pTwainPRO;

2. Initialize COM

You need to initialize the COM library before you can call COM functions. Also, you need to close the COM library and delete the TwainPRO COM object when your program ends. This is illustrated in the TwnPRO.cpp file as follows:

C++ Example	Copy Code
// This code demonstrates how the COM library must be initialized // Initialize the COM library on the current apartment and // identify the currency model as single-thread apartment (STA). // Applications must initialize the COM library before they // can call COM library functions other than CoGetMalloc and // memory allocation functions. CoInitialize(NULL); AfxEnableControlContainer(); // Standard initialization // If you are not using these features and wish to reduce the size // of your final executable, you should remove from the following // the specific initialization routines you do not need. CTwnPRODlg dlg; m_pMainWnd = &dlg; int nResponse = dlg.DoModal(); if (nResponse == IDOK) { // TODO: Place code here to handle when the dialog is // dismissed with OK } else if (nResponse == IDCANCEL) { // TODO: Place code here to handle when the dialog is // dismissed with Cancel } // Closes the COM library on the current apartment, // unloads all DLLs loaded by apartment, // frees any other resources that the apartment maintains, and // forces all RPC connections on the apartment to close. CoUninitialize(); // Since the dialog has been closed, return FALSE so that we exit the // application, rather than start the application's message pump. return FALSE;

C++ Example

Copy Code

// This code demonstrates how the COM library must be initialized

// Initialize the COM library on the current apartment and
// identify the currency model as single-thread apartment (STA).
// Applications must initialize the COM library before they
// can call COM library functions other than CoGetMalloc and
// memory allocation functions.
CoInitialize(NULL);
AfxEnableControlContainer();
// Standard initialization
// If you are not using these features and wish to reduce the size
// of your final executable, you should remove from the following
// the specific initialization routines you do not need.
CTwnPRODlg dlg;
m_pMainWnd = &dlg;
int nResponse = dlg.DoModal();
if (nResponse == IDOK)
{
// TODO: Place code here to handle when the dialog is
// dismissed with OK
}
else if (nResponse == IDCANCEL)
{
// TODO: Place code here to handle when the dialog is
// dismissed with Cancel
}
// Closes the COM library on the current apartment,
// unloads all DLLs loaded by apartment,
// frees any other resources that the apartment maintains, and
// forces all RPC connections on the apartment to close.
CoUninitialize();
// Since the dialog has been closed, return FALSE so that we exit the
// application, rather than start the application's message pump.
return FALSE;

3. Create the TwainPRO COM Object

You need to create an instance of the TwainPRO COM object. In the TwnPRO project, the COM object is created in the OnInitDialog function in the TwnPRODlg.cpp file. After creating the object, the first thing that must be done is to set the hParentWnd property. This tells the TwainPRO object what window to use as a parent. If this property is not set, the Twain device will not function correctly. Normally, this is handled by the container, but when #importing a control, there is no container. If you want to handle events fired from the TwainPRO object, you will have to create a sink. This is also done in the OnInitDialog function. The relevant portions of the OnInitDialog are as follows:

C++ Example	Copy Code
// This code demonstrates how the TwainPRO COM object is created BOOL CTwnPRODlg::OnInitDialog() { CDialog::OnInitDialog(); // Open TwainPRO Initialization // Set the icon for this dialog. The framework does // this automatically when the application's main window // is not a dialog SetIcon(m_hIcon, TRUE); // Set big icon SetIcon(m_hIcon, FALSE); // Set small icon // Create a TwainPRO object ppCTwainPRO = new CTwainPRO(this, 1); pTwainPRO = ppCTwainPRO->pTwainPRO; // Set the application window handle to TwainPRO. // This property was added specifically for creating // TwainPRO in-proc and the control will not work // unless this property is set with the application's // window handle. pTwainPRO->hParentWnd = HandleToLong(m_hWnd); // Set up the PostScan event Handler ppCTwainPRO->SetPostScanEvent(PostScan); // Must close the initialization AFTER the first // instance of the TwainPRO control is created return TRUE; // return TRUE unless you set the focus to a control } // Create an in-proc instance of the COM object inside our ActiveX

C++ Example

Copy Code

// This code demonstrates how the TwainPRO COM object is created 
BOOL CTwnPRODlg::OnInitDialog()
{
CDialog::OnInitDialog();
// Open TwainPRO Initialization
// Set the icon for this dialog. The framework does
// this automatically when the application's main window
// is not a dialog
SetIcon(m_hIcon, TRUE); // Set big icon
SetIcon(m_hIcon, FALSE); // Set small icon
// Create a TwainPRO object
ppCTwainPRO = new CTwainPRO(this, 1);
pTwainPRO = ppCTwainPRO->pTwainPRO;
// Set the application window handle to TwainPRO.
// This property was added specifically for creating
// TwainPRO in-proc and the control will not work
// unless this property is set with the application's
// window handle.
pTwainPRO->hParentWnd = HandleToLong(m_hWnd);
// Set up the PostScan event Handler
ppCTwainPRO->SetPostScanEvent(PostScan);
// Must close the initialization AFTER the first
// instance of the TwainPRO control is created
return TRUE; // return TRUE unless you set the focus to a control
}
// Create an in-proc instance of the COM object inside our ActiveX

When creating a new TwainPRO object, you must pass the following parameters:

LPVOID classPtr - The Dialog's this pointer.
DWORD objID - A unique object ID that you assign to the object’s instance. This ID can be used in event handling to determine which instance of an object has triggered the event.

4. Use the TwainPRO COM Object to Set Properties and Call Methods

After an instance of the TwainPRO COM object is created, the object can be used to set TwainPRO properties and call TwainPRO methods.

C++ Example	Copy Code
// This code demonstrates the property used to show the scanner's user interface and the method used to start a TWAIN session pTwainPRO->ShowUI = true; pTwainPRO->StartSession();

5. Delete the TwainPRO COM Object

The TwainPRO COM object must be deleted when it is no longer needed. The object is usually deleted before the application exits. In the TwainPRO sample, this is done in the OnDestroy message handler as follows:

C++ Example	Copy Code
// This code demonstrates how to delete the TwainPRO COM object void CTwnPRODlg::OnDestroy() { CDialog::OnDestroy(); pTwainPRO = NULL; if (ppCTwainPRO) { delete ppCTwainPRO; } }