DispInvoke will fill the EXCEPINFO parameter of IDispatch::Invoke if the
property or method implementation returns a failure HRESULT and uses
SetErrorInfo() to provide rich error information.
An automation client that uses late-binding or id-binding to an automation
server will use IDispatch::Invoke to invoke the server's property or
method. Such a client will typically pass an EXCEPINFO structure as a
parameter to IDispatch::Invoke to obtain rich error information on failure.
The server will fill the EXCEPINFO structure on failure. A typical
IDispatch::Invoke implementation in the server calls DispInvoke. Then
DispInvoke calls the appropriate property or method implementation.
Consequently, the property or method implementation doesn't have access to
the EXCEPINFO parameter of IDispatch::Invoke to provide rich error
information on failure.
The solution is to return a failure HRESULT from the property or method
implementation and use SetErrorInfo in the property or method
implementation. DispInvoke will check if the property or method returned a
failure HRESULT. If so, it will fill the EXCEPINFO parameter using the
information that the property or method provided with SetErrorInfo.
DispInvoke will not fill out the EXCEPINFO parameter if the return type
of the property or method is not HRESULT. Therefore, this method is best
suited for a dual interface, which requires HRESULT to be the return
type for its methods and properties. Note that an id-binding or late-
binding client will see the type of the parameter with the retval
attibute as the return type.
For example, in the following code, the server implements IDispatch::Invoke
in CServer::Invoke by using DispInvoke. If the client passes the DISPID of
the Test method, DispInvoke will call CServer::Test - whose address is
provided in the vtbl that is the first parameter of DispInvoke. Note that
CServer::Test does not have direct access to the EXCEPINFO parameter.
DispInvoke will fill the EXCEPINFO parameter using the information that
CServer::Test provides using SetErrorInfo - if Test returns a failure
HRESULT.
STDMETHODIMP
CServer::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);
}
STDMETHODIMP
CServer::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 that
HRESULT, it could write the rich error information to a variable that is
accessible by the IDispatch::Invoke implementation. The IDispatch::Invoke
implementation would copy this information to the EXCEPINFO parameter.
Thread local storage of EXCEPINFO information should be used in a
mutithreaded implementation. On the other hand, SetErrorInfo will work in a
multithreaded environment and thread local storage is not required.
Microsoft recommends the use of dual interfaces in which SetErrorInfo can
be used to fill the EXCEPINFO structure.
NOTE: Documention of SetErrorInfo and related interfaces can be found in
Chapter 10 of the OLE Programmer's Reference, Volume 2, second edition. For
information on how to obtain the second edition of this book, please see
the following article in the Microsoft Knowledge Base:
124385 SAMPLE: OLE Automation '94 Documentation and Samples
