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