DOCUMENT:Q140616 26-JUN-2002 [visualc] TITLE :MFCDISP: Replacing MFC IDispatch Implementation PRODUCT :Microsoft C Compiler PROD/VER::3.51,4.0,5.0,6.0 OPER/SYS: KEYWORDS:kbfile kbSample kbActiveX kbAutomation kbCOMt kbMFC kbVC400 kbVC500 kbVC600 MSGRAPH kbG ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Visual C++, 32-bit Editions, version 4.0 - Microsoft Visual C++, 32-bit Enterprise Edition, versions 5.0, 6.0 - Microsoft Visual C++, 32-bit Professional Edition, versions 5.0, 6.0 - Microsoft Visual C++, 32-bit Learning Edition, version 6.0 - Microsoft Visual C++.NET (2002) - Microsoft OLE Libraries, used with: - Microsoft Windows NT Server version 3.51 - Microsoft Windows NT Workstation version 3.51 ------------------------------------------------------------------------------- NOTE: Microsoft Visual C++ .NET (2002) supports both the managed code model that is provided by the Microsoft .NET Framework and the unmanaged native Microsoft Windows code model. The information in this article applies to unmanaged Visual C++ code only. SUMMARY ======= MFCDISP demonstrates how to replace MFC's IDispatch implementation with a type-library-based IDispatch implementation that uses the OLE system API DispInvoke and DispGetIDsOfNames to implement IDispatch::Invoke and IDispatch::GetIDsOfNames. MORE INFORMATION ================ The following files are available for download from the Microsoft Download Center: Visual C++ 6.0: DownloadDownload Mfcdisp.exe now (http://download.microsoft.com/download/vc40pro/demo/1/WIN98/EN-US/Mfcdisp.exe) For additional information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base: Q119591 How to Obtain Microsoft Support Files from Online Services Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on secure servers that prevent any unauthorized changes to the file. Visual C++ .NET: DownloadDownload Mfcdispvcnet.exe now (http://download.microsoft.com/download/VisualStudioNET/sample/2.0/WIN98MeXP/EN-US/Mfcdispvcnet.exe) Release Date: June 24, 2002 For additional information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base: Q119591 How to Obtain Microsoft Support Files from Online Services Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on secure servers that prevent any unauthorized changes to the file. After downloading the file, use the following command to extract the sample and build the appropriate directory structure: MFCDISP.EXE -d MFC's implementation of server OLE Automation currently has the following limitations. These limitations can be removed by replacing or modifying MFC's IDispatch implementation with a type-library-based implementation of IDispatch. 1. MFC's IDispatch doesn't support named arguments. A type-library-based implementation supports this. 2. MFC's IDispatch::Invoke doesn't fully support array parameters. Array parameters are passed in a VARIANT to an automation property/method implementation. This requires the automation method/property to type check the VARIANT. A type-library-based implementation allows an array parameter type to be SAFEARRAY*. It will also type check this parameter before passing it to the automation method/property. 3. MFC's IDispatch::Invoke doesn't fully support automation methods with the vararg attribute. These are methods that can have a variable number of arguments. The method implementation will see the variable number of arguments as a SAFEARRAY of VARIANTs. MFC will support this if the client passes a VARIANT containing a SAFEARRAY of VARIANTs, with each array element representing a parameter. However late-binding clients will not pass parameters in this manner. Instead these client will pass variable parameters the same as other parameters. Consequently MFC automation servers will not support these clients. A type-library-based implementation completely supports vararg methods. It will create an array of parameters and will pass it to the automation method implementation even if the client doesn't pass the array. (Optional arguments are supported in MFC's implementation through parameters whose type is VARIANT. Note that optional parameters are different from methods with the vararg attribute. The number of parameters of a method that has optional parameters is bounded. The number of parameters of a method that has the vararg attribute is not bounded.) 4. MFC's implementation doesn't support vtbl-binding. However it is possible to add vtbl-binding support without having to replace MFC's IDispatch implementation. Visual C++ 4.1 includes a sample, ACDUAL, that illustrates one way to do this using a type-library-based implementation. Steps to Replace MFC's IDispatch Implementation ----------------------------------------------- If you do not already know how to create a non-MFC automation server, please see the HELLO sample in the Win32 SDK and the OLE Automation documentation in the Win32 online documentation (\Ole\Ole Automation) before using the following steps. The following instructions use Visual C++ 4.0. However, a type-library- based IDispatch implementation can be added to any MFC application. The instructions build a sample called Test. You can use names appropriate for your project. 1. Create an MFC application that includes the automation header files and links with the automation libraries. One way to do this is to generate an application with OLE Automation support using AppWizard. The sample was generated using AppWizard, and 'Test' was used as the project name. The following steps show how to add a type-library-based IDispatch implementation to the CTestDoc class. The same steps can be used to add automation to any CCmdTarget-derived class. 2. Modify the Test.odl file created by AppWizard by replacing the dispinterface with an interface and by specifying a locale ID for the type library. The interface should define the automation properties and methods that need to be exposed. (DispInvoke will not work with a dispinterface.) The sample uses the Test.odl file: [ uuid(C04AADF0-2A82-11CF-84F5-00AA00C006CF), version(1.0), lcid(0x09) ] library Test { importlib("stdole32.tlb"); [ uuid(C04AADF1-2A82-11CF-84F5-00AA00C006CF), oleautomation, dual ] interface ITest : IDispatch { [id(1), propput] HRESULT TestProperty([in]short nNewValue); [id(1), propget] HRESULT TestProperty([out, retval] short *retval); [id(2)] HRESULT TestMethod([in] short n, [out,retval] short *retval); }; // Primary dispatch interface for CTestDoc /* // Replace this dispinterface with a interface [ uuid(C04AADF1-2A82-11CF-84F5-00AA00C006CF) ] dispinterface ITest { properties: // NOTE - ClassWizard will maintain property information here. // Use extreme caution when editing this section. //{{AFX_ODL_PROP(CTestDoc) //}}AFX_ODL_PROP methods: // NOTE - ClassWizard will maintain method information here. // Use extreme caution when editing this section. //{{AFX_ODL_METHOD(CTestDoc) //}}AFX_ODL_METHOD }; */ [ uuid(943B3F80-CD85-11CE-815A-00AA0060D733) ] coclass CTestDoc { [default] interface ITest; }; //{{AFX_APPEND_ODL}} }; A coclass must be provided if the object is a top-level object (that is, if the object can be created by CoCreateInstance). The UUID of the coclass must be the CLSID of the object. The GUID generated by AppWizard for the dispinterface can be used for the interface that replaces it. Add a locale id for the type library (the sample uses lcid(0x09) for English). New CCmdTarget-derived automation objects can be added using ClassWizard. Edit the .odl file to make the changes after each object is added. (The sample adds automation only to the CDocument- derived class, CTestDoc.) 3. Change the project settings for the .odl file. Open the appropriate platform folder in the left pane of the Project Settings dialog box, and select the .odl file. Click the OLE Types tab in the right pane, and enter an output header file name (Itest.h). mktyplib will generate this header file when it compiles the .odl file. This header file will contain the C/C++ definition of the ITest interface. It will also contain the CLSID of the object, the Interface GUID of the ITest interface, and the GUID of the type library. Space must be allocated for the GUIDs that are defined in Itest.h. This is done by creating a separate source file (Guids.cpp) that includes Ole2.h, Initguid.h, and Itest.h. The OLE header file Initguid.h will cause space to be allocated for the GUIDs defined in Itest.h. Make sure that Guids.cpp is not built with a pre-compiled header. To do this, add Guids.cpp to the project. Then change the project settings for the Guids.cpp file. First open the appropriate platform folder in the left pane of the Project Settings dialog box. Select Guids.cpp in the build folder in the left pane of the Project Settings dialog box, click the C/C++ tab, click the Precompiled headers category, and select Not using precompiled headers. Include Itest.h in each source file that uses the GUIDs or interfaces that it defines. The sample includes Itest.h in Test.cpp, Testdoc.h, and Testdoc.cpp. 4. Define the interface as a nested class of the object that is going to implement it by using the BEGIN_INTERFACE_PART and END_INTERFACE_PART macros. The sample defines the ITest interface as a nested class of the CTestDoc class in testdoc.h as follows: DECLARE_INTERFACE_MAP() BEGIN_INTERFACE_PART(MyDispatch, ITest) STDMETHOD(GetTypeInfoCount)(UINT FAR* pctinfo); STDMETHOD(GetTypeInfo)( UINT itinfo, LCID lcid, ITypeInfo FAR* FAR* pptinfo); STDMETHOD(GetIDsOfNames)( REFIID riid, OLECHAR FAR* FAR* rgszNames, UINT cNames, LCID lcid, DISPID FAR* rgdispid); STDMETHOD(Invoke)( DISPID dispidMember, REFIID riid, LCID lcid, WORD wFlags, DISPPARAMS FAR* pdispparams, VARIANT FAR* pvarResult, EXCEPINFO FAR* pexcepinfo, UINT FAR* puArgErr); /* ITest methods */ STDMETHOD(put_TestProperty)(short nNewValue); STDMETHOD(get_TestProperty)(short FAR* retval); STDMETHOD(TestMethod)(short n, short FAR* retval); END_INTERFACE_PART(MyDispatch) Add a private class member to the object's class to hold the typeinfo of the interface: private: LPTYPEINFO m_ptinfo; // ITest type information 5. Implement the interface. The sample implements the ITest interface as follows in Testdoc.cpp: a. An interface map is declared as follows to hook into the object's IUnknown::QueryInterface implementation. When a client asks for IDispatch (late binding/id-binding) or ITest (vtbl-binding) using IUnknown::QueryInterface, the vtbl for the XMyDispatch nested class will be returned. BEGIN_INTERFACE_MAP(CTestDoc, CDocument) INTERFACE_PART(CTestDoc, IID_IDispatch, MyDispatch) INTERFACE_PART(CTestDoc, IID_ITest, MyDispatch) END_INTERFACE_MAP() Remove the interface map inserted by AppWizard. For example, the sample removes the following interface map from Testdoc.cpp: BEGIN_INTERFACE_MAP(CTestDoc, CDocument) INTERFACE_PART(CTestDoc, IID_ITest, Dispatch) END_INTERFACE_MAP() b. Remove the declaration of the interface IID because Guids.cpp will allocate space for it. For example, the sample removes the following from Testdoc.cpp: static const IID IID_ITest = {0xc04aadf1, 0x2a82, 0x11cf, { 0x84, 0xf5, 0x0, 0xaa, 0x0, 0xc0, 0x6, 0xcf } }; c. Load the typeinfo of the interface from the type library when the object is created. BOOL CTestDoc::OnNewDocument() { HRESULT hr; LPTYPELIB ptlib; if (!CDocument::OnNewDocument()) return FALSE; hr = LoadRegTypeLib(LIBID_Test, 1, 0, 0x09, &ptlib); if (FAILED(hr)) { AfxMessageBox("Can't find type library test.tlb. Re-register \ by running test.exe"); return FALSE; } hr = ptlib->GetTypeInfoOfGuid(IID_ITest, &m_ptinfo); if (FAILED(hr)) { ptlib->Release(); return FALSE; } ptlib->Release(); return TRUE; } d. Release the typeinfo of the interface in the destructor of the object. CTestDoc::~CTestDoc() { m_ptinfo->Release(); AfxOleUnlockApp(); } e. The ITest interface is implemented as follows. Note the use of the METHOD_PROLOGUE macro to gain access to the member functions of the object by using the pThis variable. QueryInterface, AddRef, and Release are delegated to MFC's implementation. IDispatch is implemented using DispGetIDsOfNames and DispInvoke. DispInvoke will call the appropriate automation method or property function. ULONG FAR EXPORT CTestDoc::XMyDispatch::AddRef() { METHOD_PROLOGUE(CTestDoc, MyDispatch) return pThis->ExternalAddRef(); } ULONG FAR EXPORT CTestDoc::XMyDispatch::Release() { METHOD_PROLOGUE(CTestDoc, MyDispatch) return pThis->ExternalRelease(); } STDMETHODIMP CTestDoc::XMyDispatch::QueryInterface(REFIID riid, LPVOID FAR* ppvObj) { METHOD_PROLOGUE(CTestDoc, MyDispatch) return (HRESULT)pThis->ExternalQueryInterface(&riid, ppvObj); } STDMETHODIMP CTestDoc::XMyDispatch::GetTypeInfoCount(UINT FAR* pctinfo) { METHOD_PROLOGUE(CTestDoc, MyDispatch) *pctinfo = 1; return NOERROR; } STDMETHODIMP CTestDoc::XMyDispatch::GetTypeInfo( UINT itinfo, LCID lcid, ITypeInfo FAR* FAR* pptinfo) { METHOD_PROLOGUE(CTestDoc, MyDispatch) *pptinfo = NULL; if(itinfo != 0) return ResultFromScode(DISP_E_BADINDEX); pThis->m_ptinfo->AddRef(); *pptinfo = pThis->m_ptinfo; return NOERROR; } STDMETHODIMP CTestDoc::XMyDispatch::GetIDsOfNames( REFIID riid, OLECHAR FAR* FAR* rgszNames, UINT cNames, LCID lcid, DISPID FAR* rgdispid) { METHOD_PROLOGUE(CTestDoc, MyDispatch) return DispGetIDsOfNames(pThis->m_ptinfo, rgszNames, cNames, rgdispid); } STDMETHODIMP CTestDoc::XMyDispatch::Invoke( DISPID dispidMember, REFIID riid, LCID lcid, WORD wFlags, DISPPARAMS FAR* pdispparams, VARIANT FAR* pvarResult, EXCEPINFO FAR* pexcepinfo, UINT FAR* puArgErr) { METHOD_PROLOGUE(CTestDoc, MyDispatch) return DispInvoke( &pThis->m_xMyDispatch, pThis->m_ptinfo, dispidMember, wFlags, pdispparams, pvarResult, pexcepinfo, puArgErr); } STDMETHODIMP CTestDoc::XMyDispatch::get_TestProperty(short *pnRetVal) { METHOD_PROLOGUE(CTestDoc, MyDispatch) *pnRetVal = pThis->m_nTestProperty; return NOERROR; } STDMETHODIMP CTestDoc::XMyDispatch::put_TestProperty(short nNewValue) { METHOD_PROLOGUE(CTestDoc, MyDispatch) pThis->m_nTestProperty = nNewValue; return NOERROR; } STDMETHODIMP CTestDoc::XMyDispatch::TestMethod(short n, short *pnRetVal) { *pnRetVal = n; return NOERROR; } 6. Use AfxOleRegisterTypeLib to register the type library on start up in CWinApp::InitInstance. The sample does it in Test.cpp. Ensure that Afxctl.h is included in the source file that uses AfxOleRegisterTypeLib. // Register type library and the interfaces in it AfxOleRegisterTypeLib(AfxGetInstanceHandle(), LIBID_Test, _T("test.TLB")); Testing the Sample Server ------------------------- Run the sample server, Test.exe, so that it registers itself in the registration database. Then use the Visual Basic files in the vb directory in the sample to control the server. The server will be launched invisible and it doesn't have an automation method to make it visible. Vb.vbp and Vb.frm use late-binding (IDispatch) to control the server with code similar to the following: Dim o As Object Set o = CreateObject("Test.Document") Value = o.TestProperty o.TestProperty = Value Value = o.TestMethod(99) vbvtbl.vbp, vbvtbl.frm uses vtbl-binding (ITest) to control the server using code similar to the following. Use the Tools/References menu in VB to select the server's type library (Test) before executing this code. Dim o As ITest Set o = New CTestDoc 'Use the name of the coclass Value = o.TestProperty o.TestProperty = Value Value = o.TestMethod(99) Handling Errors --------------- AfxThrowOleDispatchException cannot be used to throw exceptions in the automation method or property implementation when a type-library-based IDispatch implementation is used. Instead SetErrorInfo can be used to return rich error information as described in the following article in the Microsoft Knowledge Base: Q139073 How To Fill EXCEPINFO in IDispatch Implementation Additional query words: override Mfcdisp Mfcdispvcnet ====================================================================== Keywords : kbfile kbSample kbActiveX kbAutomation kbCOMt kbMFC kbVC400 kbVC500 kbVC600 MSGRAPH kbGrpDSMFCATL Technology : kbVCsearch kbAudDeveloper kbOLESearch kbVC32bitSearch kbVCNET Version : :3.51,4.0,5.0,6.0 ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 2002.