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