include/wx/msw/ole/oleutils.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/msw/ole/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 #include "wx/defs.h"
  16
  17 #if wxUSE_OLE
  18
  19 // ole2.h includes windows.h, so include wrapwin.h first
  20 #include "wx/msw/wrapwin.h"
  21 // get IUnknown, REFIID &c
  22 #include <ole2.h>
  23 #include "wx/intl.h"
  24 #include "wx/log.h"
  25
  26 // ============================================================================
  27 // General purpose functions and macros
  28 // ============================================================================
  29
  30 // ----------------------------------------------------------------------------
  31 // initialize/cleanup OLE
  32 // ----------------------------------------------------------------------------
  33
  34 // call OleInitialize() or CoInitialize[Ex]() depending on the platform
  35 //
  36 // return true if ok, false otherwise
  37 inline bool wxOleInitialize()
  38 {
  39     HRESULT
  40 #ifdef __WXWINCE__
  41      hr = ::CoInitializeEx(NULL, COINIT_MULTITHREADED);
  42 #else
  43      hr = ::OleInitialize(NULL);
  44 #endif
  45
  46     // RPC_E_CHANGED_MODE indicates that OLE had been already initialized
  47     // before, albeit with different mode. Don't consider it to be an error as
  48     // we don't actually care ourselves about the mode used so this allows the
  49     // main application to call OleInitialize() on its own before we do if it
  50     // needs non-default mode.
  51     if ( hr != RPC_E_CHANGED_MODE && FAILED(hr) )
  52     {
  53         wxLogError(_("Cannot initialize OLE"));
  54
  55         return false;
  56     }
  57
  58     return true;
  59 }
  60
  61 inline void wxOleUninitialize()
  62 {
  63 #ifdef __WXWINCE__
  64     ::CoUninitialize();
  65 #else
  66     ::OleUninitialize();
  67 #endif
  68 }
  69
  70 // ----------------------------------------------------------------------------
  71 // misc helper functions/macros
  72 // ----------------------------------------------------------------------------
  73
  74 // release the interface pointer (if !NULL)
  75 inline void ReleaseInterface(IUnknown *pIUnk)
  76 {
  77   if ( pIUnk != NULL )
  78     pIUnk->Release();
  79 }
  80
  81 // release the interface pointer (if !NULL) and make it NULL
  82 #define   RELEASE_AND_NULL(p)   if ( (p) != NULL ) { p->Release(); p = NULL; };
  83
  84 // return true if the iid is in the array
  85 extern bool IsIidFromList(REFIID riid, const IID *aIids[], size_t nCount);
  86
  87 // ============================================================================
  88 // IUnknown implementation helpers
  89 // ============================================================================
  90
  91 /*
  92    The most dumb implementation of IUnknown methods. We don't support
  93    aggregation nor containment, but for 99% of cases this simple
  94    implementation is quite enough.
  95
  96    Usage is trivial: here is all you should have
  97    1) DECLARE_IUNKNOWN_METHODS in your (IUnknown derived!) class declaration
  98    2) BEGIN/END_IID_TABLE with ADD_IID in between for all interfaces you
  99       support (at least all for which you intent to return 'this' from QI,
 100       i.e. you should derive from IFoo if you have ADD_IID(Foo)) somewhere else
 101    3) IMPLEMENT_IUNKNOWN_METHODS somewhere also
 102
 103    These macros are quite simple: AddRef and Release are trivial and QI does
 104    lookup in a static member array of IIDs and returns 'this' if it founds
 105    the requested interface in it or E_NOINTERFACE if not.
 106  */
 107
 108 /*
 109   wxAutoULong: this class is used for automatically initalising m_cRef to 0
 110 */
 111 class wxAutoULong
 112 {
 113 public:
 114     wxAutoULong(ULONG value = 0) : m_Value(value) { }
 115
 116     operator ULONG&() { return m_Value; }
 117     ULONG& operator=(ULONG value) { m_Value = value; return m_Value;  }
 118
 119     wxAutoULong& operator++() { ++m_Value; return *this; }
 120     const wxAutoULong operator++( int ) { wxAutoULong temp = *this; ++m_Value; return temp; }
 121
 122     wxAutoULong& operator--() { --m_Value; return *this; }
 123     const wxAutoULong operator--( int ) { wxAutoULong temp = *this; --m_Value; return temp; }
 124
 125 private:
 126     ULONG m_Value;
 127 };
 128
 129 // declare the methods and the member variable containing reference count
 130 // you must also define the ms_aIids array somewhere with BEGIN_IID_TABLE
 131 // and friends (see below)
 132
 133 #define   DECLARE_IUNKNOWN_METHODS                                            \
 134   public:                                                                     \
 135     STDMETHODIMP          QueryInterface(REFIID, void **);                    \
 136     STDMETHODIMP_(ULONG)  AddRef();                                           \
 137     STDMETHODIMP_(ULONG)  Release();                                          \
 138   private:                                                                    \
 139     static  const IID    *ms_aIids[];                                         \
 140     wxAutoULong           m_cRef
 141
 142 // macros for declaring supported interfaces
 143 // NB: you should write ADD_INTERFACE(Foo) and not ADD_INTERFACE(IID_IFoo)!
 144 #define BEGIN_IID_TABLE(cname)  const IID *cname::ms_aIids[] = {
 145 #define ADD_IID(iid)                                             &IID_I##iid,
 146 #define END_IID_TABLE                                          }
 147
 148 // implementation is as straightforward as possible
 149 // Parameter:  classname - the name of the class
 150 #define   IMPLEMENT_IUNKNOWN_METHODS(classname)                               \
 151   STDMETHODIMP classname::QueryInterface(REFIID riid, void **ppv)             \
 152   {                                                                           \
 153     wxLogQueryInterface(wxT(#classname), riid);                               \
 154                                                                               \
 155     if ( IsIidFromList(riid, ms_aIids, WXSIZEOF(ms_aIids)) ) {                \
 156       *ppv = this;                                                            \
 157       AddRef();                                                               \
 158                                                                               \
 159       return S_OK;                                                            \
 160     }                                                                         \
 161     else {                                                                    \
 162       *ppv = NULL;                                                            \
 163                                                                               \
 164       return (HRESULT) E_NOINTERFACE;                                         \
 165     }                                                                         \
 166   }                                                                           \
 167                                                                               \
 168   STDMETHODIMP_(ULONG) classname::AddRef()                                    \
 169   {                                                                           \
 170     wxLogAddRef(wxT(#classname), m_cRef);                                     \
 171                                                                               \
 172     return ++m_cRef;                                                          \
 173   }                                                                           \
 174                                                                               \
 175   STDMETHODIMP_(ULONG) classname::Release()                                   \
 176   {                                                                           \
 177     wxLogRelease(wxT(#classname), m_cRef);                                    \
 178                                                                               \
 179     if ( --m_cRef == wxAutoULong(0) ) {                                                    \
 180       delete this;                                                            \
 181       return 0;                                                               \
 182     }                                                                         \
 183     else                                                                      \
 184       return m_cRef;                                                          \
 185   }
 186
 187 // ============================================================================
 188 // Debugging support
 189 // ============================================================================
 190
 191 // VZ: I don't know it's not done for compilers other than VC++ but I leave it
 192 //     as is. Please note, though, that tracing OLE interface calls may be
 193 //     incredibly useful when debugging OLE programs.
 194 #if defined(__WXDEBUG__) && ( ( defined(__VISUALC__) && (__VISUALC__ >= 1000) ) || defined(__MWERKS__) )
 195 // ----------------------------------------------------------------------------
 196 // All OLE specific log functions have DebugTrace level (as LogTrace)
 197 // ----------------------------------------------------------------------------
 198
 199 // tries to translate riid into a symbolic name, if possible
 200 void wxLogQueryInterface(const wxChar *szInterface, REFIID riid);
 201
 202 // these functions print out the new value of reference counter
 203 void wxLogAddRef (const wxChar *szInterface, ULONG cRef);
 204 void wxLogRelease(const wxChar *szInterface, ULONG cRef);
 205
 206 #else   //!__WXDEBUG__
 207   #define   wxLogQueryInterface(szInterface, riid)
 208   #define   wxLogAddRef(szInterface, cRef)
 209   #define   wxLogRelease(szInterface, cRef)
 210 #endif  //__WXDEBUG__
 211
 212 // wrapper around BSTR type (by Vadim Zeitlin)
 213
 214 class WXDLLIMPEXP_CORE wxBasicString
 215 {
 216 public:
 217     // ctors & dtor
 218     wxBasicString(const wxString& str);
 219     wxBasicString(const wxBasicString& bstr);
 220     ~wxBasicString();
 221
 222     wxBasicString& operator=(const wxBasicString& bstr);
 223
 224     // accessors
 225         // just get the string
 226     operator BSTR() const { return m_bstrBuf; }
 227         // retrieve a copy of our string - caller must SysFreeString() it later!
 228     BSTR Get() const { return SysAllocString(m_bstrBuf); }
 229
 230 private:
 231     // actual string
 232     BSTR m_bstrBuf;
 233 };
 234
 235 #if wxUSE_VARIANT
 236 // Convert variants
 237 class WXDLLIMPEXP_FWD_BASE wxVariant;
 238
 239 WXDLLIMPEXP_CORE bool wxConvertVariantToOle(const wxVariant& variant, VARIANTARG& oleVariant);
 240 WXDLLIMPEXP_CORE bool wxConvertOleToVariant(const VARIANTARG& oleVariant, wxVariant& variant);
 241 #endif // wxUSE_VARIANT
 242
 243 // Convert string to Unicode
 244 WXDLLIMPEXP_CORE BSTR wxConvertStringToOle(const wxString& str);
 245
 246 // Convert string from BSTR to wxString
 247 WXDLLIMPEXP_CORE wxString wxConvertStringFromOle(BSTR bStr);
 248
 249 #else // !wxUSE_OLE
 250
 251 // ----------------------------------------------------------------------------
 252 // stub functions to avoid #if wxUSE_OLE in the main code
 253 // ----------------------------------------------------------------------------
 254
 255 inline bool wxOleInitialize() { return false; }
 256 inline void wxOleUninitialize() { }
 257
 258 #endif // wxUSE_OLE/!wxUSE_OLE
 259
 260 #endif  //_WX_OLEUTILS_H