include/wx/msw/ole/oleutils.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        oleutils.h
   3 // Purpose:     OLE helper routines, OLE debugging support &c
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     19.02.1998
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef   _WX_OLEUTILS_H
  13 #define   _WX_OLEUTILS_H
  14
  15 #ifdef __GNUG__
  16 #pragma interface "oleutils.h"
  17 #endif
  18
  19 #include "wx/defs.h"
  20 #ifdef wxUSE_NORLANDER_HEADERS
  21 #include <ole2.h>
  22 #endif
  23 // ============================================================================
  24 // General purpose functions and macros
  25 // ============================================================================
  26
  27 // ----------------------------------------------------------------------------
  28 // misc helper functions/macros
  29 // ----------------------------------------------------------------------------
  30
  31 // release the interface pointer (if !NULL)
  32 inline void ReleaseInterface(IUnknown *pIUnk)
  33 {
  34   if ( pIUnk != NULL )
  35     pIUnk->Release();
  36 }
  37
  38 // release the interface pointer (if !NULL) and make it NULL
  39 #define   RELEASE_AND_NULL(p)   if ( (p) != NULL ) { p->Release(); p = NULL; };
  40
  41 // return TRUE if the iid is in the array
  42 bool IsIidFromList(REFIID riid, const IID *aIids[], size_t nCount);
  43
  44 // ============================================================================
  45 // IUnknown implementation helpers
  46 // ============================================================================
  47
  48 /*
  49    The most dumb implementation of IUnknown methods. We don't support
  50    aggregation nor containment, but for 99% of cases this simple
  51    implementation is quite enough.
  52
  53    Usage is trivial: here is all you should have
  54    1) DECLARE_IUNKNOWN_METHOS in your (IUnknown derived!) class declaration
  55    2) BEGIN/END_IID_TABLE with ADD_IID in between for all interfaces you
  56       support (at least all for which you intent to return 'this' from QI,
  57       i.e. you should derive from IFoo if you have ADD_IID(Foo)) somewhere else
  58    3) IMPLEMENT_IUNKNOWN_METHOS somewhere also
  59
  60    These macros are quite simple: AddRef and Release are trivial and QI does
  61    lookup in a static member array of IIDs and returns 'this' if it founds
  62    the requested interface in it or E_NOINTERFACE if not.
  63  */
  64
  65 // declare the methods and the member variable containing reference count
  66 // you must also define the ms_aIids array somewhere with BEGIN_IID_TABLE
  67 // and friends (see below)
  68 #define   DECLARE_IUNKNOWN_METHODS                                            \
  69   public:                                                                     \
  70     STDMETHODIMP          QueryInterface(REFIID, void **);                    \
  71     STDMETHODIMP_(ULONG)  AddRef();                                           \
  72     STDMETHODIMP_(ULONG)  Release();                                          \
  73   private:                                                                    \
  74     static  const IID    *ms_aIids[];                                         \
  75     ULONG                 m_cRef
  76
  77 // macros for declaring supported interfaces
  78 // NB: you should write ADD_INTERFACE(Foo) and not ADD_INTERFACE(IID_IFoo)!
  79 #define BEGIN_IID_TABLE(cname)  const IID *cname::ms_aIids[] = {
  80 #define ADD_IID(iid)                                             &IID_I##iid,
  81 #define END_IID_TABLE                                          }
  82
  83 // implementation is as straightforward as possible
  84 // Parameter:  classname - the name of the class
  85 #define   IMPLEMENT_IUNKNOWN_METHODS(classname)                               \
  86   STDMETHODIMP classname::QueryInterface(REFIID riid, void **ppv)             \
  87   {                                                                           \
  88     wxLogQueryInterface(#classname, riid);                                    \
  89                                                                               \
  90     if ( IsIidFromList(riid, ms_aIids, WXSIZEOF(ms_aIids)) ) {                  \
  91       *ppv = this;                                                            \
  92       AddRef();                                                               \
  93                                                                               \
  94       return S_OK;                                                            \
  95     }                                                                         \
  96     else {                                                                    \
  97       *ppv = NULL;                                                            \
  98                                                                               \
  99       return (HRESULT) E_NOINTERFACE;                                                   \
 100     }                                                                         \
 101   }                                                                           \
 102                                                                               \
 103   STDMETHODIMP_(ULONG) classname::AddRef()                                    \
 104   {                                                                           \
 105     wxLogAddRef(#classname, m_cRef);                                          \
 106                                                                               \
 107     return ++m_cRef;                                                          \
 108   }                                                                           \
 109                                                                               \
 110   STDMETHODIMP_(ULONG) classname::Release()                                   \
 111   {                                                                           \
 112     wxLogRelease(#classname, m_cRef);                                         \
 113                                                                               \
 114     if ( --m_cRef == 0 ) {                                                    \
 115       delete this;                                                            \
 116       return 0;                                                               \
 117     }                                                                         \
 118     else                                                                      \
 119       return m_cRef;                                                          \
 120   }
 121
 122 // ============================================================================
 123 // Debugging support
 124 // ============================================================================
 125
 126 // VZ: I don't know it's not done for compilers other than VC++ but I leave it
 127 //     as is. Please note, though, that tracing OLE interface calls may be
 128 //     incredibly useful when debugging OLE programs.
 129 #if defined(__WXDEBUG__) && defined(__VISUALC__) && (__VISUALC__ >= 1000)
 130 // ----------------------------------------------------------------------------
 131 // All OLE specific log functions have DebugTrace level (as LogTrace)
 132 // ----------------------------------------------------------------------------
 133
 134 // tries to translate riid into a symbolic name, if possible
 135 void wxLogQueryInterface(const char *szInterface, REFIID riid);
 136
 137 // these functions print out the new value of reference counter
 138 void wxLogAddRef (const char *szInterface, ULONG cRef);
 139 void wxLogRelease(const char *szInterface, ULONG cRef);
 140
 141 #else   //!WXDEBUG
 142   #define   wxLogQueryInterface(szInterface, riid)
 143   #define   wxLogAddRef(szInterface, cRef)
 144   #define   wxLogRelease(szInterface, cRef)
 145 #endif  //WXDEBUG
 146
 147 #endif  //_WX_OLEUTILS_H
 148