Import ISIS Xpress as a COM Object

1. Importing 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
// This code demonstrates the #import directive used in the stdafx.h file #if !defined(AFX_STDAFX_H__E86B75CA_B4A0_11D3_9453_00105A098C21__INCLUDED_) #define AFX_STDAFX_H__E86B75CA_B4A0_11D3_9453_00105A098C21__INCLUDED_ #if _MSC_VER >= 1000 #pragma once #endif // _MSC_VER >= 1000 #define VC_EXTRALEAN // Exclude rarely-used stuff from Windows headers #include <AFXWIN.H> // MFC core and standard components #include <AFXEXT.H> // MFC extensions #include <AFXDISP.H> // MFC OLE automation classes #ifndef _AFX_NO_AFXCMN_SUPPORT #include <AFXCMN.H> // MFC support for Windows Common Controls #endif // _AFX_NO_AFXCMN_SUPPORT //#import the ISISXpress7 DLL here #import "Accusoft.ISISXpress7.ActiveX.dll" //{{AFX_INSERT_LOCATION}} // Microsoft Developer Studio will insert additional declarations immediately before the previous line. #endif // !defined(AFX_STDAFX_H__E86B75CA_B4A0_11D3_9453_00105A098C21__INCLUDED_)

C++ Example

Copy Code

// This code demonstrates the #import directive used in the stdafx.h file
#if !defined(AFX_STDAFX_H__E86B75CA_B4A0_11D3_9453_00105A098C21__INCLUDED_)
#define AFX_STDAFX_H__E86B75CA_B4A0_11D3_9453_00105A098C21__INCLUDED_

#if _MSC_VER >= 1000
     #pragma once
#endif // _MSC_VER >= 1000

#define VC_EXTRALEAN          // Exclude rarely-used stuff from Windows headers

#include <AFXWIN.H>            // MFC core and standard components
#include <AFXEXT.H>            // MFC extensions
#include <AFXDISP.H>           // MFC OLE automation classes
#ifndef _AFX_NO_AFXCMN_SUPPORT
      #include <AFXCMN.H>     // MFC support for Windows Common Controls
#endif // _AFX_NO_AFXCMN_SUPPORT

//#import the ISISXpress7 DLL here
#import "Accusoft.ISISXpress7.ActiveX.dll"

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_STDAFX_H__E86B75CA_B4A0_11D3_9453_00105A098C21__INCLUDED_)

The #import directive simply points to the ISIS Xpress control. When the ISIS Xpress control is imported with the #import directive, the compiler produces 2 files – a .tli and a .tlh file – that together create the necessary COM wrapper for the control’s properties and methods. Since the directive is in your stdafx.h file, the wrappers are immediately available to your other modules. The wrapper code defines COM smart pointers to your .IDL-defined interfaces. To use this COM object, you simply create an instance of the interface you want and then call methods directly by using this instance pointer.

2. Declare a Pointer to the COM Object

After the #import directive is added, a pointer to the ISIS Xpress COM object must be defined. In the ISISXpressBasic project, the pointer is called pISISXpr and it is implemented in the ISISXpressBasicDlg.h file as follows:

C++ Example	Copy Code
#if !defined(AFX_ISISXPRESSBASICDLG_H__E86B75C8_B4A0_11D3_9453_00105A098C21__INCLUDED_) #define AFX_ISISXPRESSBASICDLG_H__E86B75C8_B4A0_11D3_9453_00105A098C21__INCLUDED_ #if _MSC_VER >= 1000 #pragma once #endif // _MSC_VER >= 1000 // add the ISISXpress namespace here using namespace AccusoftISISXpress7; #include "..\\..\\..\\..\\Components\\ActiveX-COM\\Include\\ISISXpress7Events.h" ///////////////////////////////////////////////////////////////////////////// // CIsisXpressBasicDlg dialog class CIsisXpressBasicDlg : public CDialog { // Event Handler Prototypes static HRESULT FeederEmpty(DWORD instancePtr, DWORD objID, long PageNumber, VARIANT_BOOL StopScan); static HRESULT Progress(DWORD instancePtr, DWORD objID, long Percent); static HRESULT Scanning(DWORD instancePtr, DWORD objID, long PageNumber); static HRESULT Scanned(DWORD instancePtr, DWORD objID, long PageNumber); // Construction public: CIsisXpressBasicDlg (CWnd* pParent = NULL); // standard constructor CISISXpress *ppCISISXpress; // Pointer to the CISISXpress class IISISXpressPtr pISISXpr; // Pointer to the ISISXpress COM object

C++ Example

Copy Code

#if !defined(AFX_ISISXPRESSBASICDLG_H__E86B75C8_B4A0_11D3_9453_00105A098C21__INCLUDED_)
#define AFX_ISISXPRESSBASICDLG_H__E86B75C8_B4A0_11D3_9453_00105A098C21__INCLUDED_

#if _MSC_VER >= 1000
     #pragma once
#endif // _MSC_VER >= 1000

// add the ISISXpress namespace here
using namespace AccusoftISISXpress7;

#include "..\\..\\..\\..\\Components\\ActiveX-COM\\Include\\ISISXpress7Events.h"  

/////////////////////////////////////////////////////////////////////////////
// CIsisXpressBasicDlg dialog

class CIsisXpressBasicDlg : public CDialog
{
     // Event Handler Prototypes
     static HRESULT FeederEmpty(DWORD instancePtr, DWORD objID, long PageNumber, VARIANT_BOOL StopScan);
     static HRESULT Progress(DWORD instancePtr, DWORD objID, long Percent);
     static HRESULT Scanning(DWORD instancePtr, DWORD objID, long PageNumber);
     static HRESULT Scanned(DWORD instancePtr, DWORD objID, long PageNumber); 

// Construction
public:
     CIsisXpressBasicDlg (CWnd* pParent = NULL); // standard constructor

     CISISXpress *ppCISISXpress;      // Pointer to the CISISXpress class
     IISISXpressPtr pISISXpr;             // Pointer to the ISISXpress COM object

The ISISXpress7Events.h file contains the CISISXpress class. The CISISXpress class is used to create a ISIS Xpress COM object and it also sets up the event-handling interface. The event handler prototypes shown above must only be implemented for the events used in the application. The ISISXpressBasic project uses all of the events. Implementation of these events is covered later in this discussion.

3. Initialize COM

The COM library must be initialized before COM functions can be called and it must be closed before the program exits. This is illustrated in the ISISXpressBasic.cpp file as follows:

C++ Example	Copy Code
BOOL CISISXpressBasic::InitInstance() { // 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. #ifdef _AFXDLL Enable3dControls() // Call this when using MFC in a shared DLL #else Enable3dControlsStatic(); // Call this when linking to MFC statically #endif CIsisXpressBasicDlg dlg; m_pMainWnd = &dlg; int nResponse = dlg.DoModal(); if (nResponse = = IDOK) { // TODO: Place code here to handle when the dialog is // dismissed with OK } // 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

BOOL CISISXpressBasic::InitInstance()
{
     // 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.

     #ifdef _AFXDLL
          Enable3dControls() // Call this when using MFC in a shared DLL
     #else 
          Enable3dControlsStatic(); // Call this when linking to MFC statically
     #endif

     CIsisXpressBasicDlg dlg;
     m_pMainWnd = &dlg;
     int nResponse = dlg.DoModal();
     if (nResponse = = IDOK)
     {
          // TODO: Place code here to handle when the dialog is
          // dismissed with OK
     }

     // 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;
}

4. Create the ISIS Xpress COM Object

To use ISIS Xpress, an instance of the ISIS Xpress COM object must be created. After the object is created, the object’s properties and methods can be used to create your scanning application. In the ISISXpressBasic project, the COM object is created in the ISISXpressBasicDlg.cpp file as follows:

C++ Example	Copy Code
// The following typedef is required by ISISX3_Open.cpp unless you include // the ISISX3_Open.h file. typedef HRESULT (WINAPI* LPFNDLL_PSUnlock)(long, long, long, long); // Before you distribute applications that use the ISIS Xpress COM object, you need to edit // the ISISX2_Open.cpp file and change the integrator key passed to the PS_Unlock function. // The integrator key is obtained from Accusoft. // Include the ISIS Xpress COM initialization routines #include "..\\..\\..\\..\\Components\\ActiveX-COM\\Include\\ISISX3_Open.cpp" BOOL CIsisXpressBasicDlg ::OnInitDialog() { char tempStr[100]; CDialog::OnInitDialog(); // Add "About..." menu item to system menu. // IDM_ABOUTBOX must be in the system command range. ASSERT((IDM_ABOUTBOX & 0xFFF0) == IDM_ABOUTBOX); ASSERT(IDM_ABOUTBOX < 0xF000); CMenu* pSysMenu = GetSystemMenu(FALSE); if (pSysMenu != NULL) { CString strAboutMenu; strAboutMenu.LoadString(IDS_ABOUTBOX); if (!strAboutMenu.IsEmpty()) { pSysMenu->AppendMenu(MF_SEPARATOR); pSysMenu->AppendMenu(MF_STRING, IDM_ABOUTBOX, strAboutMenu); } } // 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 // Initialize ISISXpress. You must call ISISX_Open before creating the first ISISXpress COM object HINSTANCE hDLL = ISISX_Open(); // Create a ISISXpress class object. The ISISXpress class object // automatically creates a ISISXpress COM object. ppCISISXpress = new CISISXpress((DWORD)this, 1); // The second parameter (1) represents the ID of the ScanXpress COM // object. This ID is used to determine which COM object caused an // event when more than one ScanXpress COM objects are used in an application. // Get the pointer to the created ISISXpress COM object. This is the pointer that // you will use to access ISISXpress properties and methods. pISISXpr = ppCISISXpress->pISISXpress; pISISXpr->SetSolutionKey(1234,1234,1234,1234); // Initialize the ISISXpress event handlers if (ppCISISXpress) { ppCISISXpress->SetFeederEmptyEvent(FeederEmpty); ppCISISXpress->SetProgressEvent(Progress); ppCISISXpress->SetScanningEvent(Scanning); ppCISISXpress->SetScannedEvent(Scanned); } //****Close the ISISXpress initialization. You must call this AFTER creating the first ISISXpress COM object ISISX_Close(hDLL);

C++ Example

Copy Code

// The following typedef is required by ISISX3_Open.cpp unless you include
// the ISISX3_Open.h file.
typedef HRESULT (WINAPI* LPFNDLL_PSUnlock)(long, long, long, long);
// Before you distribute applications that use the ISIS Xpress COM object, you need to edit
// the ISISX2_Open.cpp file and change the integrator key passed to the PS_Unlock function.
// The integrator key is obtained from Accusoft.
// Include the ISIS Xpress COM initialization routines
#include "..\\..\\..\\..\\Components\\ActiveX-COM\\Include\\ISISX3_Open.cpp"
BOOL CIsisXpressBasicDlg ::OnInitDialog()
{
     char tempStr[100];

     CDialog::OnInitDialog();

     // Add "About..." menu item to system menu.

     // IDM_ABOUTBOX must be in the system command range.
     ASSERT((IDM_ABOUTBOX & 0xFFF0) == IDM_ABOUTBOX);
     ASSERT(IDM_ABOUTBOX < 0xF000);

     CMenu* pSysMenu = GetSystemMenu(FALSE);
     if (pSysMenu != NULL)
     {
          CString strAboutMenu;
          strAboutMenu.LoadString(IDS_ABOUTBOX);
          if (!strAboutMenu.IsEmpty())
          {
               pSysMenu->AppendMenu(MF_SEPARATOR);
               pSysMenu->AppendMenu(MF_STRING, IDM_ABOUTBOX, strAboutMenu);
          }
     }

     // 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

     // Initialize ISISXpress. You must call ISISX_Open before creating the first ISISXpress COM object
     HINSTANCE hDLL = ISISX_Open();

     // Create a ISISXpress class object. The ISISXpress class object
     // automatically creates a ISISXpress COM object.
     ppCISISXpress = new CISISXpress((DWORD)this, 1); 
     // The second parameter (1) represents the ID of the ScanXpress COM
     // object. This ID is used to determine which COM object caused an
     // event when more than one ScanXpress COM objects are used in an application.

     // Get the pointer to the created ISISXpress COM object. This is the pointer that
     // you will use to access ISISXpress properties and methods.
     pISISXpr = ppCISISXpress->pISISXpress;

     pISISXpr->SetSolutionKey(1234,1234,1234,1234);

     // Initialize the ISISXpress event handlers
     if (ppCISISXpress)
     {
          ppCISISXpress->SetFeederEmptyEvent(FeederEmpty);
          ppCISISXpress->SetProgressEvent(Progress);
          ppCISISXpress->SetScanningEvent(Scanning);
          ppCISISXpress->SetScannedEvent(Scanned);
     }

     //****Close the ISISXpress initialization. You must call this AFTER creating the first ISISXpress COM object
     ISISX_Close(hDLL);

5. Implement the Event Handlers

An event handler must be implemented for every ISIS Xpress event used in your application. The ISISXpressBasic application uses the FeederEmpty, Progress, Scanning and Scanned events. The implementation of the Scanned event is shown below:

C++ Example	Copy Code
HRESULT CIsisXpressBasicDlg::Scanned(DWORD instancePtr, DWORD objID, long PageNumber) { long nElapsedSec; double nPagesPerMin; time_t nStopTime; char tempStr[100]; long hDIB; // Get a pointer to the current application CIsisXpressBasicDlg p = (CIsisXpressBasicDlg ) instancePtr; // Get the current time time(&nStopTime); // Determine how long it took to scan nElapsedSec = nStopTime - gStartTime; if (nElapsedSec == 0) nElapsedSec = 1; // Determine the pages per minute nPagesPerMin = (gNumPages * 60) / nElapsedSec; sprintf(tempStr, "%3.2f", nPagesPerMin); // Display the pages per minute p->SetDlgItemText(IDC_LBL_PAGESPERMIN, tempStr); // Display the scanned image if (p->pISISXpr->CreateDib) { hDIB = p->pISISXpr->hDib; p->DisplayDib(hDIB); } return S_OK; }

C++ Example

Copy Code

HRESULT CIsisXpressBasicDlg::Scanned(DWORD instancePtr, DWORD objID, long PageNumber)
{
     long nElapsedSec;
     double nPagesPerMin;
     time_t nStopTime;
     char tempStr[100];
     long hDIB;

     // Get a pointer to the current application
     CIsisXpressBasicDlg *p = (CIsisXpressBasicDlg *) instancePtr;

     // Get the current time
     time(&nStopTime);
     // Determine how long it took to scan
     nElapsedSec = nStopTime - gStartTime;
     if (nElapsedSec == 0) nElapsedSec = 1;

     // Determine the pages per minute
     nPagesPerMin = (gNumPages * 60) / nElapsedSec;
     sprintf(tempStr, "%3.2f", nPagesPerMin);

     // Display the pages per minute
     p->SetDlgItemText(IDC_LBL_PAGESPERMIN, tempStr);

     // Display the scanned image
     if (p->pISISXpr->CreateDib)
     {
          hDIB = p->pISISXpr->hDib;
          p->DisplayDib(hDIB);
     }

     return S_OK;
}

The objID parameter passed into the event functions can be used to determine what COM object caused the event. The following code illustrates this:

C++ Example	Copy Code
CIsisXpressBasicDlg p = (CIsisXpressBasicDlg ) instancePtr; if (objID == p->ppISISXpressBasic->m_objID) { // We know that the ppISISXpressBasic object caused the event }

6. Use the ISIS Xpress COM Object to Set Properties and Call Methods

After an instance of the ISIS Xpress COM object is created, the object can be used to set ISIS Xpress properties and call ISIS® Xpress methods. In the ISISXpressBasic project, this is illustrated in the OnCmdScansingle function shown below. This function is called when the user clicks the Scan Single button.

C++ Example	Copy Code
void CIsisXpressBasicDlg::OnCmdScansingle() { ::SetWindowPos((HWND)m_ix.GetHWnd(), HWND_TOP, 0, 0, rImg.right, rImg.bottom, SWP_NOMOVE \| SWP_SHOWWINDOW); try { // Update the controls in the application if (UpdatePrgm() == FALSE) return; // Enable/Disable command buttons ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANBATCH), FALSE); ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANSINGLE), FALSE); ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_CANCEL), TRUE); SetDlgItemText(IDC_LBL_PAGESPERMIN, "0.00"); // Call the ScanSingle method in the ISIS® Xpress COM object pISISXpr->ScanSingle(); // Reset the progress control SendDlgItemMessage(IDC_PB, PBM_SETPOS, 0, 0); ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANBATCH), TRUE); ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANSINGLE), TRUE); ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_CANCEL), FALSE); } catch(_com_error &e) { // Handle any exceptions caused by the ISIS® Xpress object ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANBATCH), TRUE); ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANSINGLE), TRUE); ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_CANCEL), FALSE); HandleError( e ); } }

C++ Example

Copy Code

void CIsisXpressBasicDlg::OnCmdScansingle()
{
     ::SetWindowPos((HWND)m_ix.GetHWnd(), HWND_TOP, 0, 0, rImg.right, rImg.bottom, SWP_NOMOVE | SWP_SHOWWINDOW);

     try
     {
          // Update the controls in the application
          if (UpdatePrgm() == FALSE) return;

          // Enable/Disable command buttons
          ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANBATCH), FALSE);
          ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANSINGLE), FALSE);
          ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_CANCEL), TRUE);
          SetDlgItemText(IDC_LBL_PAGESPERMIN, "0.00");

          // Call the ScanSingle method in the ISIS® Xpress COM object
          pISISXpr->ScanSingle();

          // Reset the progress control 
          SendDlgItemMessage(IDC_PB, PBM_SETPOS, 0, 0);

          ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANBATCH), TRUE);
          ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANSINGLE), TRUE);
          ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_CANCEL), FALSE);
     }
     catch(_com_error &e)
     {
          // Handle any exceptions caused by the ISIS® Xpress object
          ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANBATCH), TRUE);
          ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_SCANSINGLE), TRUE);
          ::EnableWindow(::GetDlgItem(m_hWnd, IDC_CMD_CANCEL), FALSE); HandleError( e );
      }
}

7. Delete the ISIS Xpress COM Object

The ISIS Xpress COM object must be deleted when it is no longer needed. The ISIS Xpress COM object is usually deleted before the application exits. In the ISISXpressBasic project, the COM object is deleted in the ISISXpressBasicDlg.cpp file as follows:

C++ Example	Copy Code
void CIsisXpressBasicDlg::OnDestroy() { CDialog::OnDestroy(); // Clean up the ISISXpress COM object pISISXpr = NULL; if (ppCISISXpress) delete ppCISISXpress; }