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