Examples of Use

C++

The following C++ example demonstrates typical use of the Search custom failure HRESULT values.  Note the use of the "bit mask" in the failure check.  Checking the HRESULT for the FACILITY_ITF notifies the calling application that the interface has prepared the ErrorInfo object itself to communicate the exception.  In most cases, this implies that some logic or operation related directly to the object has failed in some fashion. (e.g. not initializing the object or failure to pass necessary info before invoking a particular method, etc)  This is in contrast to standard Win32 or COM HRESULT values such as E_FAIL or E_UNEXPECTED, which convey little information about the exception source. 

If simply displaying the source and description of the error to a user in say an interactive setting is desired, the bit mask check can be removed, and the information retrieved for the exception, regardless of the source.  The code below is very routine.

HRESULT hR = pISearchObject->SomeMethod( … );
if (FAILED(hR)) {
   ISupportErrorInfo *psei = 0;
   HRESULT hR2 = pISearchObject->QueryInterface( IID_ISupportErrorInfo,
                                                (void**)&psei );
   if( SUCCEEDED(hR2)) {
      hR2 = psei->InterfaceSupportsErrorInfo(IID_ISearchInterface);
      if ( hR2 == S_OK ) {
         IErrorInfo *pei = 0;
         hR2 = GetErrorInfo(0, &pei);
         if ( hR2 == S_OK ) {
            BSTR Source = 0;
            BSTR Description = 0;
            hR2 = pei->GetSource(&Source);
            assert(SUCCEEDED(hR2));
            hR2 = pei->GetDescription(&Description);
            assert(SUCCEEDED(hR2));

            /*  deal with this info, such as MessageBoxW, etc.. */
            SysFreeString(&Source);
            SysFreeString(&Description);
         }
      }
      psei-Release();
   }
   /*  try FormatMessage or something as the error was 
        not designated as interface specific */
   void* pMsgBuf;
   ::FormatMessage(..,..,hR,..,(LPTSTR)pMsgBuf,0,NULL);
}
   

VB/VBScript

In Visual Basic or Visual Basic, Scripting Edition, the Err object is automatically populated with the COM exception information when a COM method invocation returns a failed HRESULT value.  The code is very similar to the C++ code listed above:

Dim MyObject as ISearchAdmin
Set ISearchInterfaces = new SearchAdmin
…
On Error Resume Next
Set SearchServer = ISearchAdmin.SearchServer
… ' code omitted for brevity

If Err.Number <> 0 and  ( (Err.Number And Hex(0x7fff0000)) = Hex(0x00040000) )
   ' take some appropriate action
   '  in this case, we simply display the error info
   Debug.Print Err.Source
   Debug.Pring Err.Description
End If