Wrapper Classes

The following are illustrated in this section
__declspec (property)
Interface Pointers
    CComPtr<>
    _com_ptr_t<>
Strings
    Unicode
    Prerequisites
    BSTR
    _bstr_t
    CComBSTR
Variants
    VARIANT
    _variant_t
    CComVariant
SAFEARRAY
Exceptions

__declspec( property ... )

__declspec(property()) declares a non-static data member as a virtual data member by associating it with public accessor (Get) and mutator (Set) methods.

// CAR.H
class CCar 
{
private:
    int nSpeed;
    int nItems[10];
public:
    CCar(); 
    virtual ~CCar();

    __declspec(property(get=GetSpeed,put=SetSpeed)) int Speed;
    int GetSpeed();
    void SetSpeed( int nNum );

    __declspec(property(get=GetItem,put=SetItem)) int Items[];
    int GetItem( long nIndex);
    void SetItem( long nIndex, long nVal);
};

// CAR.CPP

#include "stdafx.h"
#include "car.h"

/* Using __declspec(property()) improves readability. Consider the following -
CCar     ob;
ob.SetItem( 0, 20);
ob.Items[0] = 20;     // uses __declspec( property() ) */

CCar::CCar() : nSpeed(0) {}

CCar::~CCar() {}

int CCar::GetSpeed()
{
    return nSpeed;
}

void CCar::SetSpeed( int nNum )
{
    nSpeed = nNum;
}

int CCar::GetItem( long nIndex)
{
    return nItems[nIndex];
}
void CCar::SetItem( long nIndex, long nVal)
{
    nItems[nIndex] = nVal;
}

Interface Pointers

• Using raw interface pointers is error-prone because of ease of  upcasting and downcasting. Always use QueryInterface() and COM compiler support classes: _com_ptr_t<>, CComPtr(), and CComQIPtr<>
  
• Upcasting: Casting a derived interface pointer into a base interface pointer (like casting IMyInterface to IUnknown). When an interface inherits from another, the new virtual methods of the derived interface are added at the END of the VTable of the derived interface. Later in the program code, casting this derived interface to its base interface will cause Interface Slicing, i.e.,  removing the functions pointers of the derived interface that were added at  the end of the VTable.
  
• Downcasting: Casting a pointer of a base interface to a pointer to a derived interface. Technically it can be done only IF 
      1. The object is in-process
      2. The base interface is implemented by slicing off the derived interface members.
  
  In general, as a client, we don't know if either of these conditions apply. Therefore, do not perform downcasting. Always use QueryInterface() !
  
• Creating an object without using its type library: This code shows how to create and a COM object without using any of MIDL-generated files or even importing the type libraries. The object was defined in Basic ATL Object. We could have used the '.h' and '_i.c' files generated from compiling the IDL file. However, this is an alternate method of assigning a uuid to the CoClass and the Interface, and using __uuidof() to get the associated GUID when creating the object. Note that in general to create the object, we must declare the interface's ABC class. To make things easier, we can use __declspec((uuid()) to associate an IID that can be later retrieved using __uuidof()
  

#include "stdafx.h"
#include <comdef.h>     // Brings in IDispatch definition

struct __declspec(uuid("aeca53e3-f3a6-11d3-8eb4-000000000000")) Object1;
struct __declspec(uuid("9d5ace00-f934-11d3-8ebc-000000000000")) IEngine : IDispatch {};
struct __declspec(uuid("aeca53e2-f3a6-11d3-8eb4-000000000000")) IObject1 : IDispatch
{
    virtual HRESULT __stdcall get_Number ( long * pVal ) = 0;
    virtual HRESULT __stdcall put_Number ( long pVal ) = 0;
    virtual HRESULT __stdcall raw_SomeFunc ( long nNumber ) = 0;
    virtual HRESULT __stdcall raw_GetEngine ( struct IEngine ** ppEngine ) = 0;
};

void RawInterfacePointers()
{ 
    HRESULT hr;
    IObject1 *pItf = NULL;
    IUnknown *pUnk = NULL;

    // Create the 'Object1' COM object
    hr = CoCreateInstance
            ( 
            __uuidof(Object1), // aeca53e3-f3a6-11d3-8eb4-000000000000
            NULL,
            CLSCTX_ALL,
            __uuidof( IObject1), // aeca53e2-f3a6-11d3-8eb4-000000000000
            reinterpret_cast<void**>(&pItf)
            );

    // Call some functions on the newly created object
    hr = pItf->raw_SomeFunc( 10 );

    /* This cast slices off IObject1 methods. Do not do this! Note that pUnk 
    will get the same pointer value as pItf (casting a pointer to another does 
    not change the pointer value */
    pUnk = static_cast<IUnknown*>(pItf);

    /* Although the two pUnk and pUnk2 interfaces are equal, we should only 
    retrieve IUnknown from QueryInterface(). On the same note, to compare 
    if two interface point to the same object, QueryInterface() for IUnknown
    pointer and compare the two resulting pointers. Never compare two 
    IUnknown's for object identity if they were obtained from a cast */
    IUnknown *pUnk2 = NULL;
    pItf->QueryInterface( __uuidof(IUnknown), (void**)&pUnk2);

    // Clean up
    pItf->Release();
    pUnk2->Release();
}

• Creating an object using its type library: #import directive tells the preprocessor to read the type library information
  from the given file and generate C++ language bindings. #import generates the code in a namespace with the same name used in the type library's 'library' statement:
      library GENERICLib
      {
          [ ... ]
      coclass Object1 { ... }
      }
  
  When using the type library's smart pointers, the object MUST be released before CoUninitialize() is called.
  
• The type library (generated by MIDL) can be imported in a couple of ways:
  

  #import "Generic.tlb" raw_interfaces_only     // removes all wrapper methods
  #import "Generic.tlb" no_namesapce            // removes the library namespace
  #import "Generic.tlb" inject_statement(" any statement ") 
  #import "Generic.tlb" exclude(), rename() 

  
  The type library can be bound to its ATL server as a resource. We would only have to distribute one module (the server), and clients using the server can import its type library by '#import'ing the DLL itself.
  

#import "Generic.tlb" no_namespace 

void CreateObjectWithTypeLib()
{ 
    long     nNum = 10;
    HRESULT  hr;

    /* Standard way to create an object and retrieve a pointer to it. To remember 
    what to supply as argument, recall that retrieving an interface pointer 
    requires the CLSID of its coclass. Therefore, pass the CLSID. */
    IObject1Ptr p( __uuidof(Object1) );

    /* Two ways to access the same METHOD */
    hr = p->SomeFunc( nNum );     // high-level method that wraps COM errors
    hr = p->raw_SomeFunc( nNum ); // raw interface method 

    /* Three ways to access the same PROPERTY */
    hr   = p->get_Number( &nNum); // raw interface method
    nNum = p->GetNumber();        // high-level method that wraps COM errors
    nNum = p->Number;             // virtual member variable using __declspec(property())

    /* Using __uuidof() */
    CLSID clsidObject = __uuidof( Object1) ;  // Using the CoClass class
    IID iidID1        = __uuidof( IObject1 ); // Using the interface class
    IID iidID2        = __uuidof( p );        // Using interface instance

    /* GetEngine() retrieves an interface pointer via an [out] param, which 
    implies that AddRef() has been called from within GetEngine(). The 
    implementation of GetEngine() has the following code (from the .tli) -
        inline IEnginePtr IObject1::GetEngine ( )
        {
            struct IEngine * _result;
            HRESULT _hr = raw_GetEngine(&_result);
            if (FAILED(_hr)) _com_issue_errorex(_hr, this, __uuidof(this));
            return IEnginePtr(_result, false);
        }

    IEnginePtr is created with a call to the constructor that will NOT call
    AddRef(). When execution moves to the next line (the end of GetEngine), the 
    temp object is destroyed and its destructor calls Release() soaking up the 
    extra reference count from the assignment operator. (the assignment operator
    is called BEFORE the temp object is destroyed). Therefore, when pEngine is 
    destroyed, the Release() will be matched by the AddRef() from GetEngine()
    */
    IEnginePtr pEngine;
    pEngine = p->GetEngine();

    /* We can release pEngine by letting it go out of scope OR by calling its
    Release() function */
    pEngine.Release();         // NEVER: pEngine->Release(); NO NO NO
}

CComPtr<> & CComQIPtr

• CComPtr<> & CComQIPtr<> are two smart pointer classes defined in <atlbase.h> that do not use C++ exception handling and are therefore most suited for use in server-side code.
  
• CComPtr<> is used to create a smart pointer based on an interface type 
      CComPtr<IMyInterface> pItf( pRaw );
• CComQIPtr<> takes an interface and the IID of that interface. If the smart pointer is initialized with some interface, CComQIPtr<> can use its IID to QI for the original interface -
      CComQIPtr< ICar, &IID_ICar > spItf( pUnk );
  
  Here the constructor for CComQIPtr<> calls QueryInterface() of pUnk and uses IID_ICar to obtains the ICar pointer. The ICar pointer is stored in 'spItf' smart pointer. Note that instead of pUnk we could have specified ANY interface implemented on this object since this interface can be upcasted to IUnknown and then QId() for ICar.
  
• _com_ptr_t<> constructor allows to create an object with the given interface
      IObject1Ptr p( __uuidof( Object1 ) ); // object created by constructor
      p->SomeMethod();                      // and methods can be invoked
  
  However, CComPtr<> and CComQIPtr<> do not do that. Instead we have to create the object explicitly and then use the raw pointer as a constructor parameter.
  
• Access to the wrapped interface pointer is through operator->(), but unlike _com_ptr_t<>, CComPtr<> & CComQIPtr<> do not return the interface pointer, but they return a pointer to _NoAddRefReleaseOnCComPtr<>.  Consider this code
  
       CComQIPtr<IObject1, &__uuidof(IObject1)> sp1;
      sp1.CoCreateInstance( __uuidof(Object1) );
      sp1->put_Number( 10 );
  
      sp1.Release();  // OK
      sp1->Release(); // Will not compile because it is a private method!
  
  _NoAddRefReleaseOnCComPtr<> makes Release() and AddRef() private members when invoked using operator->() : NEVER CALL Release() ON THE SMART POINTER BECAUSE IT MEANS YOU ARE RELIEVING THE SMART POINTER FROM  MANAGING REFERENCE COUNTS!
  

// Object1 object
struct __declspec(uuid("aeca53e3-f3a6-11d3-8eb4-000000000000")) Object1;

// IEngine Interface
struct __declspec(uuid("9d5ace00-f934-11d3-8ebc-000000000000")) IEngine : IDispatch
{};

// IObject1 Interface
struct __declspec(uuid("aeca53e2-f3a6-11d3-8eb4-000000000000")) IObject1 : IDispatch
{
    virtual HRESULT __stdcall get_Number ( long * pVal ) = 0;
    virtual HRESULT __stdcall put_Number ( long pVal ) = 0;
    virtual HRESULT __stdcall raw_SomeFunc ( long nNumber ) = 0;
    virtual HRESULT __stdcall raw_GetEngine ( struct IEngine ** ppEngine ) = 0;
};

void CreateObjectCComPtr()
{
    long nNum;

    {
        CComQIPtr<IObject1, &__uuidof(IObject1)> sp1;     // REF COUNT = 1
        sp1.CoCreateInstance( __uuidof(Object1) );
        sp1->put_Number( 10 );
        sp1->get_Number( &nNum );

        /* Calling Release() is required if you want to reuse the smart 
        pointer. Note that ~CComQIPtr<> is called and it will release the 
        wrapped pointer if it is not already release
            sp1.Release();      // Optional. Can do without.
            sp1->Release();     // Will not compile. See note above
        */

        /* Some manipulations. 
        Note that the last statement calls the constructor explicitly. Just 
        like -
        CString str1 = CString("hello");     // OR same as
        CString str1( CString ("hello") );

        In essence, the right side of the last statement acts just like a 
        casting operator for interfaces - it converts the given interface
        pointer to the required type using CComQIPtr<> which will do a QI()
        based on the supplied type. Note that the second argument for 
        CComQIPtr<> defaults to __uuidof(T)

        'CComPtr<IObject1> sp2 = CComQIPtr<IObject1>(pUnk)'  calls these 
        functions:
        CComQIPtr::CComQIPtr(IUnknown* lp)  // get IObject1 interface from pUnk
        CComQIPtr::operator T*()            // conversion operator - returns raw ptr
        CComPtr( T * )                      // sp2 is initialied with the raw ptr
        CComQIPtr::~CComQIPtr()             // destroy temp object

        Consider this example to illustrate the conversion function
        class Money
        {
        public:
            Money();
            operator double() { return _amount; }
        private:
            double _amount;
        };

        Money Account;
        double CachOnHand = Account;    // calls operator double() to perform a
                                        // conversion from type Account to type double.
        */
        IUnknown *pUnk = NULL;
        sp1.QueryInterface( &pUnk );         // AddRef()d. Must release! REF COUNT = 2
        CComPtr<IObject1> sp2 = CComQIPtr<IObject1>(pUnk); // REF COUNT = 3

        /* This should help explain the previous code snippet 
        'IObject1 *pOb1 = CComQIPtr<IObject1>(pUnk)' calls these functions:
            CComQIPtr::CComQIPtr(IUnknown* lp) // get IObject1 interface from pUnk
            CComQIPtr::operator T*()           // conversion operator - returns raw ptr 
            CComQIPtr::~CComQIPtr()            // destroy temp object
        */
        IObject1 *pOb1 = CComQIPtr<IObject1>(pUnk); // Ref count not AddRef()ed
        pUnk->Release(); // REF COUNT = 2

        // Other methods - IsEqualObject()
        bool bSame = sp2.IsEqualObject( sp1 );
    
        // Other methods - CopyTo() - calls AddRef()
        IObject1 *pOb2;
        sp2.CopyTo( &pOb2 ); // AddRef() called because a copy is make

        // .. Use pOb2
        pOb2->Release(); // release it because it's not a smart pointer.

    } // smart pointer release
}

_com_ptr_t<>

•  _com_ptr_t<> is a  generic smart pointer that enforces COM reference counting rules. If defines a copy constructor, an assignment operator, methods to create instances of an object, and methods to cast one interface pointer to another.
  
• _com_IIID<> is a  template that encapsulates the IID and its interface.
  
• com_ptr_t<> should be used in client code but not in server code since they use C++ exception handling and these increase code size considerably.
  
• In a .TLH file generated when a type library is #imported, _COM_SMARTPTR_TYPEDEF(IObject1, __uuidof(IObject1)) macro defines a smart pointer of type _com_ptr_t<> called IObject1Ptr
  
• _com_IIID<> is undocumented, but to help explain it, consider these template definitions -
  

  template<class _IIID>
  class _com_ptr_t<> { ... };
  
  template<class _Interface, const IID* _IID>
  class _com_IIID { ... };
  
  _com_IIID< IObject1, & __uuidof(IObject1) > comIIID;
  _com_ptr_t< comIIID >;

• A smart pointer in COM encapsulates an interface pointer. That interface pointer is either NULL (i.e., no object is valid), or else it is valid and therefore, a pointer to an interface on an existing object. With smart pointers there are three ways to create an object -
  •  Use CoCreateInstance() and then use the appropriate constructor to initialize the smart pointer with the raw interface, or attach the raw interface pointer using Attach() ( Attach() has an overloaded version which takes a bool to indicate if AddRef() should be called.)
    
  • Using _com_ptr_t<>::CreateInstance()
    

    IObject1Ptr p;
    p->CreateInstance( CLSID_Object1 );

  • Using the appropriate _com_ptr_t<> constructor
    

    IObject1Ptr p( _uuidof( Object1 ) );

Note that in methods 2 and 3, CoCreateInstance() is called, rather then  CoCreateInstanceEx(). Remote objects must be created with method 1 only.

• _com_ptr_t<> has all sorts of operators -
  • We can compare two smart pointers to see it they belong to the same object
  • We can pass the address of a smart pointer to functions taking an [out] param. like QueryInterface()
  • Operators <,>,<=,>= exits to allows us to use the smart pointer in STL. These operators work by calling _CompareUnknown() which get the IUnknown for the two smart pointers being compared and doing the comparison on these IUnknowns (We can use vector<>, deque<>, and map<> directly with _com_ptr_t<> object, but no with list<>, and set<> because these last two need to hold the address of the item they contain (a smart pointer) and the  address in this case corresponds to the raw interface pointer.) This restriction is resolved using adapter class.
    
• You can release a com_ptr_t<> smart pointer EITHER by letting it go out of scope or by calling its Release() member function, but NEVER by calling the Release() through operator->() :
  

  IEnginePtr p( __uuidof(Object1));
  p->SomeMethod;
  p.Release(); // This stmt optional but NEVER use p->Release()

• _com_ptr_t<> has a constructor of the following signature -
  

  _com_ptr_t<Interface *pInterface, bool fAddRef) throw()

  
  This constructor takes an interface pointer of the same type of the smart pointer. It used to initialize the smart pointer with an interface pointer without calling AddRef() on it. This is required when we have an interface method that returns another interface pointer as an [out] parameter.
  

// Used to create IObject1 with CoCreateInstance()
struct __declspec(uuid("aeca53e3-f3a6-11d3-8eb4-000000000000")) Object1;
struct __declspec(uuid("9d5ace00-f934-11d3-8ebc-000000000000")) IEngine : IDispatch
{ };
struct __declspec(uuid("aeca53e2-f3a6-11d3-8eb4-000000000000")) IObject1 : IDispatch
{
    virtual HRESULT __stdcall get_Number ( long * pVal ) = 0;
    virtual HRESULT __stdcall put_Number ( long pVal ) = 0;
    virtual HRESULT __stdcall raw_SomeFunc ( long nNumber ) = 0;
    virtual HRESULT __stdcall raw_GetEngine ( struct IEngine ** ppEngine ) = 0;
};

// Used to create IObject1 with smart pointers
//#import "Generic.tlb" no_namespace 


void CreateObjectComPtrT()
{
    /* Create an object using CoCreateInstance() and attach it to a smart
    pointer. Note how _com_ptr_t<> needs to take _com_IIID<> as its template
    argument. Also note how _com_IIID<> takes the address of the interface IID */
    {
        HRESULT hr;
        IObject1 *pItf = NULL;

        // Create an object
        hr = CoCreateInstance
            ( 
            __uuidof(Object1), // aeca53e3-f3a6-11d3-8eb4-000000000000
            NULL,
            CLSCTX_ALL,
            __uuidof( IObject1), // aeca53e2-f3a6-11d3-8eb4-000000000000
            reinterpret_cast<void**>(&pItf)
            );

        // Initialize smart pointer to NULL. 
        _com_ptr_t< _com_IIID<IObject1, & __uuidof(IObject1)> > sp1(NULL);
        sp1.Attach( pItf );

    } // smart pointer released here

    /* This segment illustrates creating an object using method 2*/
    {
        // This takes care of creating IObject1Ptr. No need to use #import
        _COM_SMARTPTR_TYPEDEF(IObject1, __uuidof(IObject1));
        IObject1Ptr p1;
        p1.CreateInstance( __uuidof(Object1) );

        /* Assignment operator can be used to assign homogenous or heterogeneous
        pointers. In the code below, the assignment operator= will do a QI() for
        the required interface type (IObject1) if p2 was not of type IObject1 */
        IObject1Ptr p2;
        p2 = p1; // Calls AddRef() on p2 since we are making a copy
        // No need to call AddRef() ourselves

    } // smart pointers released here
}

Strings

PREREQUISITES

• ANSI characters use a byte (8 bits) for each character. UNICODE uses a short (16 bits) for each character. COM uses UNICODE.
  
• In UNICODE, the upper byte is NULL. A string "hello" is represented in ANSI and UNICODE as follows
      ANSI         - h e l l o
      UNICODE - 0 h 0 e 0 l 0 l 0 o
  
• To use ANSI strings, define _MBCS in the project settings. To use UNICODE strings, define _UNICODE in the project settings. Any _T("") delimited strings will map to the approprite type.
  
• string functions - strlen, wcslen, _tcslen, lstrlen() :
  • strlen    Takes ANSI characters - (const char*)
  • wcslen        Takes UNICODE characters - (const w char*)
  • _tcslen      Maps to  strlen if _MBCS is defined, or to wcslen if UNICODE  is defined.
  • lstrlen      Generic macro version that takes LPCTSTR. 
    
• We cannot use single-byte string functions on UNICODE strings - Passing a UNICODE string to strlen() returns a length of 1 because of the upper NULL  byte in the first character. For UNICODE always use 'wcs' functions, i.e.,  wcslen, wcscpy, etc..
  
• Always use the TCHAR support for strings - _T(""), LPTSTR, LPCTSTR
  
• Always remember the following typedefs and defines -

  typedef short         wchar_t;
  typedef char          CHAR;
  typedef wchar_t       WCHAR
  typedef WCHAR         OLECHAR
  typedef OLECHAR       *LPOLESTR;
  typedef const OLECHAR LPCOLESTR;
  #define OLESTR(str)   L##str;

UNICODE

• UNICODE strings are arrays of wchar_t. COM uses OLECHAR and  LPOLECHAR. Automation uses BSTR. The following explains all these three and  when to use.
  
• See Example1 in DemoString() below for OLESTR & LPOLESTR
  
• Marshalling strings: As a rule, a proxy needs to know EXACTLY how many bytes of data have to be marshalled to another apartment/process/machine. For a data of type long, the marshaller knows it has to transmit 4 bytes. But what about strings?
  • Solution 1 : Specify that the string is a fixed length

    PassAsString1( [in] OLECHAR str[256] );     // cannot pass more than 256 !

     
  • Solution 2: Use separate param to indicate length of string

    PassAsString2( [in] long Len, [in, size_is(Len)] LPOLESTR str); 

     
  • Solution 3: From 2, it is obvious that length must always be specified. MIDL has the [string] property that tells marchaller code to get the string's size

    PassAsString3( [in, string] LPOLESTR str);

Conclusion: The marshaller layer must always know how many bytes to trasnsmit. The BSTR data type works exactly in this way: A BSTR is actually an OLECHAR* and can be treated as such when programming. However, when a BSTR is marshalled it is marshalled as a wireBSTR which is a BSTR and its associated length.

BSTR

• A BSTR is a length-prefixed string and any code that creates/returns a BSTR must ensure that the length exists, therefore:
  •  Treat a BSTR as a const OLECHAR* which is the same as LPCOLESTR
  • Because of the length-prefix, do NOT cast a WCHAR to a BSTR.
  • Use SysAllocString(), and SysFreeString() to allocate BSTRs
  • Since BSTRs are LPCOLESTR, to manipulate a BSTR copy to an OLECHAR*,manipulate it, then recopy into a BSTR using SysReAllocString()
  • The length prefixed to a BSTR is the NUMBER OF BYTES and is retrieved with SysStringByteLen(), whereas SysStringLen() returns the number of characters.
  • The string length (number of bytes) is maintained in a long just before the  start address, and the string always has an EXTRA null character after the last character. The string length does NOT include this EXTRA null character.
  • An empty BSTR is a pointer to a zero-length string. It has a single NULL char to the right of the address, and a long integer containing zero to the left.
  • A NULL BSTR is null pointer pointing to nothing.
    

// Forward declaration
BSTR TransformBSTR( BSTR bstrIn );

void DemoStrings()
{
    /* Example 1
    Most COM functions use LPOLESTR and OLECHAR for strings. COM functions 
    that return strings to the caller are allocated by the calle and freed 
    by the caller. COM functions that receive strings must be allocated by 
    caller and freedby caller.

    RULE - Functions taking a pointer to a pointer
    Passing a pointer to a pointer is the same as passing the address of the
    pointer. This is used when we wish to change the value of the pointer 
    stored inside the variable (which is of type pointer). Typical situation
    is passing a string pointer to have the called functions allocated a
    string. See below -

    StringFromCLSID takes an address of a pointer. Think of it as follows -
    lpString is a variable (a box) with uninitialized content and since it's a 
    pointer, the uninitialized content is an invalid memory address. The 
    variable's address it sent and we get back the variable containing a valid 
    memory address; a pointer to a string. 
    */
    LPOLESTR     lpString;
    const CLSID cls = {0xAECA53E3,0xF3A6,0x11D3,{0x8E,0xB4,0x00,0x00,0x00,0x00,0x00,0x00}};
    HRESULT hr = StringFromCLSID( cls, &lpString );
    CoTaskMemFree( lpString );

    // Defining literal strings
    WCHAR wsz[]  = OLESTR("going in");
    WCHAR wsz2[] = L"in in";

    /* Any function that creates/returns a BSTR must ensure that the length is 
    prefixed, else you can treate a BSTR as an 'const OLECHAR*' or LPCOLESTR 
    which mean we can read from it but not write to it. Note that SysAllocString()
    takes an OLECHAR* which use a NULL character to indicate end of string. To get
    around having a null in the string to be allocated, use SysAllocStringLen() */
    BSTR bstr         = SysAllocString( L"A BSTR \0 String");  // allocates "A BSTR "
    OLECHAR * oleStr1 = (LPOLESTR) bstr;               // Casting is not important
    OLECHAR * oleStr2 = bstr;                          // Casting can be ignored
    int nLen          = wcslen( oleStr1 );
    SysFreeString( bstr );

    /*Manipulating a BSTR: COPY into an LPOLESTR buffer, manipulate, then recopy
    into the BSTR again */
    // BSTR bstr1 = SysAllocString( "hello there"); // ERROR. Must have an OLESTR
    BSTR bstr1 = SysAllocString( L"hello there" ); // Get BSTR
    //
    OLECHAR *pStr = new OLECHAR[64];               // Copy
    wcscpy( pStr, bstr1);                          // Do not use: OLECHAR *pStr = bstr1;
    //
    wcscat( pStr, L"Mr. Diranieh");                // Manipulate
    //
    SysReAllocString( &bstr1, pStr);               // Re-assign
    //
    SysFreeString( bstr1 );                         // Free memory
    delete pStr;

    /* Using SysAllocStringLen() */
    // bstr2 contains "Te". Char length = 2, Byte length = 4
    BSTR bstr2 = SysAllocStringLen( L"Text", 2);
    SysFreeString( bstr2 );

    // bstr3 contains "Text" followed by \0 and a a junk char - a total of 
    six char and then the EXTRA terminating null character.
    BSTR bstr3 = SysAllocStringLen( L"Text", 6); 
    SysFreeString( bstr3 );

    /* Rule 7 (see below) - Must create a BSTR in order to return it */
    BSTR bstr5 = TransformBSTR( bstr3 );
    SysFreeString( bstr5 );

    /* NULL and empty BSTRs. However, BOTH have a length of zero */
    BSTR bstr6 = SysAllocString( L"" );
    BSTR bstr7 = SysAllocString( NULL );
    int nLen6  = SysStringLen( bstr6 );
    int nLen7  = SysStringLen( bstr7 );
    SysFreeString( bstr6 );
}

// Rule 7 (see below) Must create a BSTR in order to return it (cannot return 
// the input param)
BSTR TransformBSTR( BSTR bstrIn )
{
    BSTR bstr = SysAllocString( bstrIn );
    return bstr;
}

EIGHT RULES OF BSTR

1. Always use the Sys functions to allocate/destroy/measure BSTRs
2. Since BSTRs may contain embedded NULLs, use SysStringLen() to determine the excat length ( _tcslen() on a BSTR will report only up to the first NULL character.)
3. Since BSTR is an OLECHAR*, we can only change the pointer using SysReAllocString() and SysReAllocStringLen() functions.
4. When passing a BSTR by value to a function, the CALLER owns the BSTR (in terms of destruction) -
5. You own any BSTR passed to you by reference as an in/out parameter -
       void ModifyThidBSTR( BSTR *pBSTR );
6. You must create any BSTR passed to you by reference as an out parameter
       void TakeNothingAndGiveMeAString( BSTR * pbstrOut );
7. You must create a BSTR in order to return it . When a function takes a BSTR also return a BSTR, you cannot take the passed BSTR and return it. Instead create a new BSTR and return it
   

   BSTR TransformThisString( BSTR bstrIn )
   {
       BSTR bstr = SysAllocString( bstrIn );
       bstr.ToUpper();
       return bstr;
   }

    
8. A null pointer is the same as an empty string to a BSTR. In C++ a NULL pointer is an invalid pointer and cannot obtain a length on it. A NULL BSTR and an empty BSTR both have the length of zero 

BSTR bstr6 = SysAllocString( L"" );
BSTR bstr7 = SysAllocString( NULL );
ASSRT( SysStringLen( bstr6 ) == SysStringLen( bstr7 ) ) // length = 0

_bstr_t

• A  _bstr_t is a compiler COM support class used to manage BSTRs performing memory allocation/freeing of buffers as well as conversions. A _bstr_t has many constructors (see examples below).
  
• The guts of _bstr_t is a private class called Data_t. This class holds a pointer to a wchar_t which points to the actual BSTR.
• Use _bstr_t wherever a BSTR is used:
  • Any method that takes a BSTR can take a _bstr_t by implictly calling _bstr_t::opertor wchar_t*()
  • Any method that returns a BSTR can be used to construct a _bstr_t by implicitly using _bstr_t::_bstr_t(const wchar_t* s)
    

// Forward declaration
void PassBSTR( BSTR bstr);

void Demo_bstr_t()
{
    /* A _bstr_t constructor can take a UNICODE string. Normal form */
    _bstr_t bstr1( L"This is bstr1" );

    /* A _bstr_t constructor can take an ANSI string. Multibyte to UNICODE
    is performed before calling SysAllocString() */
    _bstr_t bstr2( "This is bstr2" );
    
    /* A _bstr_t constructor can take a BSTR. The supplied BSTR can be attached
    (_bstr_t wraps it), or a totally new copy of the BSTR can be created 
    In both cases, SysFreeString() is managed by _bstr_t */
    BSTR bstr = SysAllocString( L"This is BSTR" );
    _bstr_t bstr3( bstr, false );
    _bstr_t bstr4( bstr, true );

    /* Illustrates ref count on _bstr_t 
    At end of 2nd line, both bstrs point to the same string. The copy constructor
    of the bstr6 increments the ref count. However, in the third line, the ref 
    count is decremented and a new BSTR is assigned. Use F11 to watch the _bstr_t 
    code for each of the steps below to verify the use of the ref count */
    _bstr_t bstr5( L"This is bstr5" );
    _bstr_t bstr6 = bstr5;
    bstr5 = L"Still bstr5"; 

    /* To print the contents of a _bstr_t use operator char*() */
    printf("string is %s", (LPSTR)bstr4); // same as (char*)bstr5

    /* Using operator+=( const _bstr_t &). 
    Since we are supplying an OLESTR and operator+=() takes a 'const _bstr_t &', 
    we must create a temp object using _bstr_t::_bstr_t(const wchar_t *) conversion
    constructor. The temp object is later destroyed */
    {
        _bstr_t bstr7 = L"This is";
        bstr7 += L"bstr7";
    }

    /* Passing _bstr_t to COM functions. Consider the following
        p->SetString( bstr6 ); 
        ...
        inline HRESULT IObject1::SetString ( _bstr_t bstrString ) 
        {
            HRESULT _hr = raw_SetString(bstrString);
        ..
        }
    First, the copy constructor is called since we're passing by value. SetString()
    expects a BSTR but we're passing a _bstr_t. This will cause operator wchar_t*()
    to be invoked in order to convert _bstr_t to BSTR */
    IObject1Ptr p( __uuidof(Object1) );
    p->SetString( bstr6 );
    _bstr_t bstr8 = p->GetString();

    /* Use _bstr_t wherever BSTR is used */
    // The following calls _bstr_t::_bstr_t(const wchar_t* s)
        _bstr_t bstr9 = SysAllocString( L"This is a bstr" );
    // The following calls _bstr_t::operator wchar_t*()
        PassBSTR( bstr9 );
}
void PassBSTR( BSTR bstr)
{
    // Do something with with the bstr
    return;
}

CComBSTR

• CComBSTR is a thin ATL wrapper for BSTRs. It differs from _bstr_t in  that _bstr_t has operators that return ANSI strings -  _bstr_t::operator char*(). Use CComBSTR anywhere a BSTR is used.
  
• bstr_t has a conversion operator to get an ANSI string from a _bstr_t. CComBSTR does not! Instead we need to access the BSTR buffer directly using CComBSTR::operator BSTR() and convert it to ANSI. Luckily, ATL conversion macros do just that. To use these conversion macros, USES_CONVERSION must be declared at the beginning of the functions where these macros are used. ANSI to UNICODE and UNICODE to ANSI strings are converted using these macros which wrap MultiByteToWideChar() and WideCharToMultiByte().
  

// Forward declaration
void PassSomeBSTR( BSTR bstr );

void Demo_CComBSTR()
{
    USES_CONVERSION;

    // CComBSTR() constructors handle UNICODE and ANSI strings
    CComBSTR bstr1( L"UNICODE String" );
    CComBSTR bstr2( "ANSI String" );     // Uses A2WBSTR() to convert ANSI to UNICODE

    // There is no operator+(). Use CComBSTR::Append()
    CComBSTR bstr3( L"CComBSTR3" );
    bstr3.Append( " With Append" );

    // AppendBSTR() is used to append only a BSTR
    CComBSTR bstr4( L"CComBSTR4" );
    BSTR bstr = SysAllocString( L" IS A BSTR" );
    bstr4.AppendBSTR( bstr );

    // Use CComBSTR anywhere a BSTR is used
    CComBSTR bstr5 = SysAllocString( L"BSTR5" ); // CComBSTR::CComBSTR( LPCOLESTR )
    PassSomeBSTR( bstr5 );                       // CComBSTR::CComBSTR operator BSTR()

    /* Using Attach/Detach() : Use Attach() if you have an existing BSTR and 
    you want to wrap with a CComBSTR. Use Detach() to retrieve the wrapped BSTR */
    {
        CComBSTR bstr6;
        BSTR     bstrBSTR1 = SysAllocString( L"Another BSTR" );
        bstr6.Attach( bstrBSTR1 );
        BSTR bstrBSTR2 = bstr6.Detach();     // set bstr6.m_strto NULL
        SysFreeString( bstrBSTR2 );          // who else is gonna call it?
    } // bstr6 destructor calls SysFreeString(m_str) on a NULL m_str

    /* ATL conversion macros - Uses when we need to convert between ANSI and 
    UNICODE strings. */
    LPSTR lpszString     = "This is a T string";
    LPOLESTR lpoleString = A2OLE( lpszString );
    BSTR bstrString      = A2BSTR( lpszString ); // must call SysFreeString();
    SysFreeString( bstrString );
}

void PassSomeBSTR( BSTR bstr )
{
    CComBSTR bstr1;
    bstr1 = bstr; // CComBSTR& operator=(LPCOLESTR pSrc)
    return;
}

Variants

VARIANT

• A VARIANT holds data, and the type of the data. Because the Universal marshalers support VARIANTS they can always be marshaled across apartment/processes/machine boundaries without difficulties.
  
• Basic steps to work with VARIANTS are:
  • Initialize a variant with VariantInit().
  • Assign the data and the data type.
  • Use the variant.
  • Clear the variant with VariantClear(). This ensures that the data item is freed, so for a BSTR it calls SysFreeString(), and for a pointer it calls Release().
    
• VT_BYREF indicates to the marshaler that it should treat data in the variant as a POINTER and therefore, marshal the data that the pointer points to, and not the pointer itself. VT_BYREF is mainly used with methods that return VARIANTS as [out] parameters.
  
• A VARIANT size is 16 bytes: the vartype and the three reserved fields in the VARIANT structure are 8 bytes long. The other 8 bytes is  the size of the union, which is the size of its largest member (double, currency, and date.)
  
• Interfaces and Variant functions: VariantClear() calls Release() on the interface pointer. VaraintCopy() calls AddRef() on the interface pointer.
  

void DemoVariants()
{
    /* Using a variant - always initialize it first then clear it when finished */    
    VARIANT     var1;
    VariantInit( &var1 );            // Initialize
    var1.vt    = VT_INT;            
    var1.iVal  = 10;
    int nSize  = sizeof( var1 );     // size = 16 bytes. Parenthesis required.
    nSize      = sizeof VARIANT;     // size = 16 bytes. Parenthesis not required
    VariantClear( &var1 );

    /* For variants of type VT_BSTR, call VariantClear() to free the string */
    BSTR bstr = SysAllocString( L"My BSTR" );
    VARIANT var2;
    VariantInit( &var2 );
    var2.vt = VT_BSTR;               // or: V_VT( &var2 ) = VT_BSTR
    var2.bstrVal = bstr;             // or: V_BSTR( &var2 ) = bstr;
    VariantClear( &var2 );           // Calls SysFreeString()

    /* VT_BYREF is used to store pointers to the associated data type */
    BSTR bstr2 = SysAllocString( L"BSTR2" );
    VARIANT var3;
    VariantInit( &var3 );
    var3.vt       = VT_BSTR | VT_BYREF;
    var3.pbstrVal = &bstr2;
    VariantClear( &var3 );          // Calls SysFreeString()

    /* Changing variant types. Use the VarT1FromT2 functions. The following 
    retrieves the integer value into a long value */
    long     lVal;
    VARIANT  var4;
    VariantInit( &var4 ); 
    var4.vt     = VT_I2;
    var4.iVal   = 10;
    // Extract a long from a variant containing a short
    VarI4FromI2( var4.iVal, &lVal );     // lVal contains 10
    // Use a short to assign data to variable of type long
    lVal        = lVal + 100;
    VarI2FromI4( lVal, &var4.iVal );
    VariantClear( &var4 );

    /* Changing variant types. The following gets the system time and stores it
    in a variant. We then change the variant from type DATE to type BSTR */
    SYSTEMTIME    sysTime;
    double        date;
    VARIANT       var5;
    VariantInit( &var5 );
    //
    GetSystemTime( &sysTime );
    SystemTimeToVariantTime( &sysTime, &date );
    //
    var5.vt     = VT_DATE;
    var5.date   = date;
    HRESULT hr  = VariantChangeType( &var5, &var5, VARIANT_NOVALUEPROP, VT_BSTR);
    //
    VariantClear( &var5 );

    /* Accomplishing the same DATE to BSTR conversion using VarBstrFromDate */
    SYSTEMTIME    sysTime2;
    double        date2;
    VARIANT       var6;
    VariantInit( &var6 );
    //
    GetSystemTime( &sysTime2 );
    SystemTimeToVariantTime( &sysTime2, &date2 );
    //
    BSTR     bstrDate;
    LCID lcid = GetUserDefaultLCID();
    VarBstrFromDate( date2, lcid, 0, &bstrDate );
    //
    var6.vt      = VT_BSTR;
    var6.bstrVal = bstrDate;
    //
    VariantClear( &var6 );
}    

_variant_t

• _variant_t is a compiler COM support class that wraps a VARIANT. It derives publicly from tagVARIANT. Therefore, to get a pointer to  a VARIANT, just upcast a _variant_t pointer to VARIANT.
• Wherever we use a VARIANT, we can use a _variant_t 

void Demo_variant_t()
{
    {
        // ANSI is converted to BSTR (A2BSTR)
        _variant_t vart1( "ANSI String"); 
    } // VariantClear(this) is called here

    {
        _bstr_t bstrVart2;
        _variant_t vart2( L"UNICODE String" );  // Calls SysAllocString() directly
        bstrVart2 = (_bstr_t) vart2;            // _variant_t::operator _bstr_t()
    }

    {
        /* This sequence show how to attach a variant, use it, and then detach
        it and clear it */
        _variant_t  vart;
        //
        VARIANT var;
        VariantInit( &var );
        var.vt   = VT_I2;
        var.iVal = 10;
        //
        vart.Attach( var );     // VARIANT var is now wrapped by _variant_t
                                // VARIANT var is also cleared and set to VT_EMPTY
        // Start using the attached VARIANT
        vart.ChangeType( VT_I4 ); 
        //
        var = vart.Detach();  // Set var back to what it originally was 
        VariantClear( &var ); // Now clear 'var' since it's no longer wrapped
    }
}

CComVariant<>

• CComVariant derives publicly from VARIANT. If differs from _variant_t in that it has no conversion operator to access the VARIANT data directly (these are the Extractors functions; ie, the conversion functions  defined with operator() keyword.)
  
  

void DemoCComVariant()
{
    /* Basic usage. It will convert the ANSI string to BSTR using ATL conversio
    macro - A2COLE() and assign vt = VT_BSTR.
    To access
    */
    {
        CComVariant var1( "ANSI" );
        int nVT     = var1.vt;
        BSTR bstr   = var1.bstrVal;
    } // the bstr is freed when ~CComVariant is called.

    // Basic usage as above but with a UNICODE string
    {
         CComVariant var2( L"UNICODE" );
        BSTR bstr2 = var2.bstrVal;
    }

    /* Illustrating attaching/detaching a variant
    When attaching, the contents of the source (attached) variant are copied 
    into the target variant (the CComVaraint) and the source is set to VT_EMPTY.
    The opposite happens when detaching - CComVaraint contents are copied into 
    the VARIANT using memcpy(), and the CComVariant is set to VT_EMPTY. */
    {
        CComVariant var3; // Set to VT_EMPTY
        VARIANT var;
        // Create a variant
        VariantInit( &var );
        var.vt   = VT_I2;
        var.iVal = 10;
        // Attach variant and use it
        // contents of var are copied into var3 using memcpy(). var3 is set to 
        // VT_EMPTY
        var3.Attach( &var ); 
        int iValue = var3.iVal;
        // Detach variant and clear it
        // contents of var3 are copied into var using memcpy(). var is set
        // to VT_EMPTY
        var3.Detach( &var ); 
        VariantClear( &var );
    }

    /* CComVaraint::Copy copies the varinat using VariantCopy(). The original 
    VARIANT must still be freed since it was not attached */
    {
        CComVariant var4; // Set to VT_EMPTY
        VARIANT var;
        // Create a variant
        VariantInit( &var );
        var.vt   = VT_I2;
        var.iVal = 10;
        // Copy the variant into a CComVariant
        var4.Copy( &var );
        // Clear VARIANT since it was copied NOT attached
        VariantClear( &var ); 
    }

    /* CComVariant::operator () functions */
    {
        CComVariant var1;
        var1 = 20;

        CComVariant var2;
        var2 = SysAllocString( L"UNICODE" );

        CComVariant var3;
        var3 = CComBSTR( "ANSI" );

        // Incorrect way of converting BSTR to LPSTR. Use conversion macros
        BSTR bstr2 = SysAllocString( L"UNICODE" );
        char* lpString = (char*) bstr2;
    }
}

SafeArrays

• Passing arrays between processes requires special processing. C/C++ can use pointers to access arrays used by COM, but VB and Java cannot pointer to access arrays used by COM (recall COM is language neutral). Therefore, to make arrays available across process, machine and OS boundaries, we need to use SAFEARRAYs. Further, in order to enable the COM interface methods to return arrays that can be used by VBScript in ASP, we need to use SAFEARRAYs
  
• SAFEARRAY have no wrappers in ATL. To use SAFEARRAY in ATL either use the raw functions or add MFC support and use COleSafeArray class.
  
• SAFEARRAY is a struct used to define the array of data -
  

  typedef struct tagSA 
  {
      USHORT cDims;         // Number of dimensions
      USHORT fFeatures;     // array attributes used by safearray routines
      ULONG cbElements;     // Aize of a single element in the array
      ULONG cLocks;         // Lock count. Cannot access data when cLocks = 0.
      PVOID pvData;         // Actual array data
      SAFEARRAYBOUND rgsaBound[1];  // Number of elements in each dimension
  }
  
  // Elements in each dimension are defined by SAFEARRAYBOUND -
  typedef struct tagSAFEARRAYBOUND
  {
      ULONG cElements;      // Number of elements in a dimension
      LONG lLBound;         // lower bound index (for C++ it is 0)
  }

• Safe arrays are created with SafeArrayCreate(). Sequene of safe array creation and usage -
  SafeArrayCreate()
      SafeArrayAccessData()
      ...
      SafeArrayUnAccessData() 
  SafeArrayDestroy()
  
• Safe arrays can hold data of type VARAINTS. Most useful in passing C-style structures between client and COM.
  
• How do you sepcify in IDL that a COM method uses safearrays?
      HRESULT Names( [out, retval] SAFEARRAY(BSTR) *paNames );
      HRESULT IDs( [out, retval] SAFEARRAY(long) *paIDs );
  
• SAFEARRAYs in COM objects - To pass an array to/from an interface method, construct a VARIANT that contains a SAFEARRAY:
  • Getting a safe array from a COM interface method -
    

    GetArray( VARIANT *pVar )
    {
        // Create a safe array and populate it with data
        pSa = SafeArrayCreate(...)
        ...
    
        // Set variant to be an array of some type, say BSTRs and then set the 
        // variant array data to point to the safe array
        VariantInit( pVar );
        pVar->vt     = VT_ARRAY | VT_BSTR;
        pVar->parray = pSA;
    }

  •  Sending a safe array into a COM interface method -
    

    SetArray( VARIANT var )
    {
        // Ensure variant is an array
        ASSERT( var.vt & VT_ARRAY == 0 );
    
        // Get safe array out of the VARAIANT
        SAFEARRAY *pSA = var.parray;
    
        // Access the safe array and use its data
        SafeArrayAccessData( pSA, ... );
        ...
    }

    On the client side, for the SetArray() method we populate the [in] VARAINT using same exact procdures in GetArray(). For the GetArray() method, we  retrieve data from the variant using same steps iin SetArray().
    
    

void DemoSafeArray()
{
    /* Create a one dimensional safearray */
    {
        // Set dimension information. Two dimensions
        SAFEARRAYBOUND saBound[1];
        saBound[0].cElements = 10;  // 10 elements in first dimension
        saBound[0].lLbound = 0;     // lower bound of 0

        // Create safearray
        SAFEARRAY *pSA;
        pSA = SafeArrayCreate( VT_I4,     // data type held in safearray is 'long'
                               1,         // 1 dimension
                               saBound ); // data about the only dimension

        // Access the safearray by retrieving a pointer to the data
        HRESULT hr;
        long *plData;
        hr = SafeArrayAccessData( pSA, (void**)&plData );

        // Use the data
        for (int i = 0; i < 10; i++)
        {
            plData[i] = i;
        }

        // UnAccess the safearray
        hr = SafeArrayUnaccessData( pSA );

        // Destroy safe array
        SafeArrayDestroy( pSA );
    }


    /* Create a two dimensional safearray */
    {
        // Set dimension information. Two dimensions
        SAFEARRAYBOUND saBound[2];
        saBound[0].cElements = 5;     // 5 elements in first dimension
        saBound[0].lLbound = 0;       // lower bound of 0
        saBound[1].cElements = 5;     // 5 elements in second dimension
        saBound[1].lLbound = 0;       // lower bound of 0

        // Create safearray
        SAFEARRAY *pSA;
        pSA = SafeArrayCreate( VT_I4,     // data type held in safearray is 'long'
                               2,         // 2 dimensions
                               saBound ); // data about the 2 dimension

        // Use the data - first dimension
        long l2DData[5][5] = {
                {1,2,3,4,5},
                {6,7,8,9,10},
                {11,12,13,14,15},
                {16,17,18,19,20},
                {21,22,23,24,25} 
            };

        long ix[2];
        long lData;

        // Set / Get first row first column
        ix[0] = 0;
        ix[1] = 0;
        lData = l2DData[0][0];
        SafeArrayPutElement( pSA, ix, (void*)&lData );
        //
        lData = 0;
        SafeArrayGetElement( pSA, ix, &lData);

        // Set / Get fifth row third colums
        ix[0] = 4;
        ix[1] = 2;
        lData = l2DData[4][2];
        SafeArrayPutElement( pSA, ix, (void*)&lData );
        //
        lData = 0;
        SafeArrayGetElement( pSA, ix, &lData );

        // Another way to access a particular element in the SAFEARRAY. ix[] 
        // indicates the index of the data to be accessed. The data is copied 
        // to pData;
        long *pData;
        SafeArrayLock( pSA );
        SafeArrayPtrOfIndex( pSA, ix, (void**)&pData );
        lData = *pData;
        SafeArrayUnlock( pSA );

        // Get dimensions using SafeArrayX() functions
        long lBound, uBound;
        SafeArrayGetLBound( pSA, 1, &lBound );
        SafeArrayGetUBound( pSA, 1, &uBound );

        // Destroy safe array
        SafeArrayDestroy( pSA );
    }
}

Exceptions

• Exceptions and errors in COM objects can be handled in three ways. These are listed in order of use:
  • EXCEPTIONS : Allow you to catch any errors generated by an interface method.
  • HRESULTS : Return error codes to the client.
  • RICH ERROR HANDLING : Same puprose as HRESULTS but far more powerful since it returns full error descriptions.

HRESULT

• An HERSULT is a status code -
  
      3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
      1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
      +---+-+-+-----------------------+-------------------------------+
      |Sev|C|R| Facility | Code |
      +---+-+-+-----------------------+-------------------------------+
  
  where
  
  Sev - is the severity code
      00 - Success
      01 - Informational
      10 - Warning
      11 - Error
  
  C - is the Customer code flag
  R - is a reserved bit
  Facility - is the facility code
  Code - is the facility's status code
  
• To test for success/failure (value of Sev), use SUCCEEDED(hr) / FAILED(hr)
  
• The faiclity of HRESULT determine who generated the error (the method itself,COM run time, etc.) Use HRESULT_FACILITY() to get the faciltiy code.
  
• To return a WIN32 error code from an interface method, convert it into an HRESULT using HRESULT_FROM_WIN32() macro.
  
• To get the error description form an HRESULT, convert the lower 4 bytes into base 10 and look up the number in winerror.h:
      hr = 0x800706ba --> 06ba = 1722
      From winerror.h: #define RPC_S_SERVER_UNAVAILABLE 1722L
  

RICH ERROR HANDLING

• An 'error object' is a COM object that can be created by any COM object that supports the error object
  
• Usage: 
  • Server - COM interfaces must support ISupportErrorInfo interface to produce error object :
    

    ICreateErrorInfo * pCEI;
    CreateErrorInfo( &pCEI );
    pCEI->SetDescription( "The error description ");
    //
    IErrorInfo *pEI;
    pCEI->QueryInterface( _uuidof(IErrorInfo), (void**)&pEI );
    SetErrorInfo( 0, pEI );
    //
    pEI->Release();
    pCEI->Release();
    

• Client - A client that receives an error hersult form one of the interfaces, calls ISupportErrorInfo::InterfaceSupportErrorInfo() and if it returns S_OK, the client should call GetErrorInfo() to get a full description of the error.
  

EXCEPTIONS

• Exceptions are generated by COM objects cannot be CAUGHT from across process or  apartment boundaries. Throwing C++ exceptions form COM objects is NOT allowed unless error are never allowed to leave the object methods. 
  
• Exceptions in Server and Client:
  • Server : Exceptions can be used. Ensure that all errors are returned as HRESULTs. Error objects can be optionally created.
    
  • Client : Hide HRESULTs by converting them into exception. This is already done by #import wrapper methods which throw a _com_error if HRESULT is an error.
    
• com_error is an exception class used by the compiler COM support classes. This exception is thrown using _com_issue_error() or _com_issue_errorex()
      _com_issue_error( hr );
      _com_issue_errorex( hr, this, __uuidof(this) ); // this is the interface ptr
  
  _com_issue_error() does not support error info, where as _com_issue_errorex() does: it queries the supplied interface pointer (this) for ISupportErrorInfo  and gets the error info from it. Then it throws a _com_error:
      _com_error e(hr, pErrorInfo);
      throw(e);
  
• Always catch an  exception in the client code by reference 
  catch( const _com_error & e)
  {
      LPTSTR strError = e.ErrorMessage();
  }
  
• The above is used in client code and applies if we're using smart pointers generated from #import. If we need to use COM runtime functions, check for hr and issue error accordingly
  
  hr = GetRunningObjectTable(...)
  if (FAILED(hr))
  {
      com_issue_error(hr); // Same as: _com_error e(hr, NULL); 
      throw(e);
  }
  

void DemoErrors()
{
    // Play with HRESULT
    HRESULT hr = 0x800706ba;                  // simulate an error
    long lFacility = HRESULT_FACILITY( hr );  // used to determine who made the error
    long lCode = HRESULT_CODE( hr );          // used to get err description
    if (FAILED(hr) ) // testing for failure.
    {
        hr = 0x00000000;
    }

    // TO DO: code to get an error object form an interface method.
}