How to Fill EXCEPINFO in IDispatch Implementation

Print

Email

Article translations

Article ID: 139073 - View products that this article applies to.

This article was previously published under Q139073

SUMMARY

DispInvoke will fill the EXCEPINFO parameter of IDispatch::Invoke if theproperty or method implementation returns a failure HRESULT and usesSetErrorInfo() to provide rich error information.

MORE INFORMATION

An automation client that uses late-binding or id-binding to an automationserver will use IDispatch::Invoke to invoke the server's property ormethod. Such a client will typically pass an EXCEPINFO structure as aparameter to IDispatch::Invoke to obtain rich error information on failure.The server will fill the EXCEPINFO structure on failure. A typicalIDispatch::Invoke implementation in the server calls DispInvoke. ThenDispInvoke calls the appropriate property or method implementation.Consequently, the property or method implementation doesn't have access tothe EXCEPINFO parameter of IDispatch::Invoke to provide rich errorinformation on failure.

The solution is to return a failure HRESULT from the property or methodimplementation and use SetErrorInfo in the property or methodimplementation. DispInvoke will check if the property or method returned afailure HRESULT. If so, it will fill the EXCEPINFO parameter using theinformation that the property or method provided with SetErrorInfo.

DispInvoke will not fill out the EXCEPINFO parameter if the return typeof the property or method is not HRESULT. Therefore, this method is bestsuited for a dual interface, which requires HRESULT to be the returntype for its methods and properties. Note that an id-binding or late-binding client will see the type of the parameter with the retvalattibute as the return type.

For example, in the following code, the server implements IDispatch::Invokein CServer::Invoke by using DispInvoke. If the client passes the DISPID ofthe Test method, DispInvoke will call CServer::Test - whose address isprovided in the vtbl that is the first parameter of DispInvoke. Note thatCServer::Test does not have direct access to the EXCEPINFO parameter.DispInvoke will fill the EXCEPINFO parameter using the information thatCServer::Test provides using SetErrorInfo - if Test returns a failureHRESULT.

STDMETHODIMPCServer::Invoke(      DISPID dispidMember,      REFIID riid,      LCID lcid,      WORD wFlags,      DISPPARAMS FAR* pdispparams,      VARIANT FAR* pvarResult,      EXCEPINFO FAR* pexcepinfo,      UINT FAR* puArgErr){    return  DispInvoke(        this, m_ptinfo,        dispidMember, wFlags, pdispparams,        pvarResult, pexcepinfo, puArgErr);}STDMETHODIMPCServer::Test(){    HRESULT hr, hr2;    ICreateErrorInfo FAR* pcerrinfo;    IErrorInfo FAR* perrinfo;    hr = DoProcessing();    if (FAILED(hr)    {        hr2 = CreateErrorInfo(&pcerrinfo);        if (SUCCEEDED(hr2))        {            pcerrinfo->SetGUID(...);            pcerrinfo->SetSource(...);            pcerrinfo->SetDescription(...);            pcerrinfo->SetHelpFile(...);            pcerrinfo->SetHelpContext(...);            hr2 = pcerrinfo->QueryInterface(IID_IErrorInfo,                                   (LPVOID FAR*) &perrinfo);            if (SUCCEEDED(hr2))            {               SetErrorInfo(0, perrinfo);               perrinfo->Release();            }            pcerrinfo->Release();        }        return hr;    }    else return NOERROR;}				

If the property or method implementation has a return type other thatHRESULT, it could write the rich error information to a variable that isaccessible by the IDispatch::Invoke implementation. The IDispatch::Invokeimplementation would copy this information to the EXCEPINFO parameter.Thread local storage of EXCEPINFO information should be used in amutithreaded implementation. On the other hand, SetErrorInfo will work in amultithreaded environment and thread local storage is not required.Microsoft recommends the use of dual interfaces in which SetErrorInfo canbe used to fill the EXCEPINFO structure.

NOTE: Documention of SetErrorInfo and related interfaces can be found inChapter 10 of the OLE Programmer's Reference, Volume 2, second edition. Forinformation on how to obtain the second edition of this book, please seethe following article in the Microsoft Knowledge Base:

124385 SAMPLE: OLE Automation '94 Documentation and Samples

Properties

Article ID: 139073 - Last Review: March 16, 2005 - Revision: 3.3

APPLIES TO

• Microsoft OLE 2.03
• Microsoft OLE 4.0, when used with:
• Microsoft Windows NT 3.51 Service Pack 5
• Microsoft Windows NT 4.0
• Microsoft Windows 95
• the operating system: Microsoft Windows 2000

Keywords:

kbautomation kbcode KB139073