[wxWidgets.git] / include / wx / msw / ole / oleutils.h

///////////////////////////////////////////////////////////////////////////////
// Name:        oleutils.h
// Purpose:     OLE helper routines, OLE debugging support &c
// Author:      Vadim Zeitlin
// Modified by:
// Created:     19.02.1998
// RCS-ID:      $Id$
// Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

#ifndef   _WX_OLEUTILS_H
#define   _WX_OLEUTILS_H

#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
#pragma interface "oleutils.h"
#endif

#include "wx/defs.h"

// get IUnknown, REFIID &c
#include <ole2.h>

// ============================================================================
// General purpose functions and macros
// ============================================================================

// ----------------------------------------------------------------------------
// misc helper functions/macros
// ----------------------------------------------------------------------------

// release the interface pointer (if !NULL)
inline void ReleaseInterface(IUnknown *pIUnk)
{
  if ( pIUnk != NULL )
    pIUnk->Release();
}

// release the interface pointer (if !NULL) and make it NULL
#define   RELEASE_AND_NULL(p)   if ( (p) != NULL ) { p->Release(); p = NULL; };

// return TRUE if the iid is in the array
extern bool IsIidFromList(REFIID riid, const IID *aIids[], size_t nCount);

// ============================================================================
// IUnknown implementation helpers
// ============================================================================

/*
   The most dumb implementation of IUnknown methods. We don't support
   aggregation nor containment, but for 99% of cases this simple
   implementation is quite enough.

   Usage is trivial: here is all you should have
   1) DECLARE_IUNKNOWN_METHODS in your (IUnknown derived!) class declaration
   2) BEGIN/END_IID_TABLE with ADD_IID in between for all interfaces you
      support (at least all for which you intent to return 'this' from QI,
      i.e. you should derive from IFoo if you have ADD_IID(Foo)) somewhere else
   3) IMPLEMENT_IUNKNOWN_METHODS somewhere also

   These macros are quite simple: AddRef and Release are trivial and QI does
   lookup in a static member array of IIDs and returns 'this' if it founds
   the requested interface in it or E_NOINTERFACE if not.
 */

/*
  wxAutoULong: this class is used for automatically initalising m_cRef to 0
*/
class wxAutoULong
{
public:
    wxAutoULong(ULONG value = 0) : m_Value(value) { }

    operator ULONG&() { return m_Value; }
    ULONG& operator=(ULONG value) { m_Value = value; return m_Value;  }
    
    wxAutoULong& operator++() { ++m_Value; return *this; }
    const wxAutoULong operator++( int ) { wxAutoULong temp = *this; ++m_Value; return temp; }

    wxAutoULong& operator--() { --m_Value; return *this; }
    const wxAutoULong operator--( int ) { wxAutoULong temp = *this; --m_Value; return temp; }

private:
    ULONG m_Value;
};

// declare the methods and the member variable containing reference count
// you must also define the ms_aIids array somewhere with BEGIN_IID_TABLE
// and friends (see below)

#define   DECLARE_IUNKNOWN_METHODS                                            \
  public:                                                                     \
    STDMETHODIMP          QueryInterface(REFIID, void **);                    \
    STDMETHODIMP_(ULONG)  AddRef();                                           \
    STDMETHODIMP_(ULONG)  Release();                                          \
  private:                                                                    \
    static  const IID    *ms_aIids[];                                         \
    wxAutoULong           m_cRef

// macros for declaring supported interfaces
// NB: you should write ADD_INTERFACE(Foo) and not ADD_INTERFACE(IID_IFoo)!
#define BEGIN_IID_TABLE(cname)  const IID *cname::ms_aIids[] = {
#define ADD_IID(iid)                                             &IID_I##iid,
#define END_IID_TABLE                                          }

// implementation is as straightforward as possible
// Parameter:  classname - the name of the class
#define   IMPLEMENT_IUNKNOWN_METHODS(classname)                               \
  STDMETHODIMP classname::QueryInterface(REFIID riid, void **ppv)             \
  {                                                                           \
    wxLogQueryInterface(_T(#classname), riid);                                \
                                                                              \
    if ( IsIidFromList(riid, ms_aIids, WXSIZEOF(ms_aIids)) ) {                \
      *ppv = this;                                                            \
      AddRef();                                                               \
                                                                              \
      return S_OK;                                                            \
    }                                                                         \
    else {                                                                    \
      *ppv = NULL;                                                            \
                                                                              \
      return (HRESULT) E_NOINTERFACE;                                         \
    }                                                                         \
  }                                                                           \
                                                                              \
  STDMETHODIMP_(ULONG) classname::AddRef()                                    \
  {                                                                           \
    wxLogAddRef(_T(#classname), m_cRef);                                      \
                                                                              \
    return ++m_cRef;                                                          \
  }                                                                           \
                                                                              \
  STDMETHODIMP_(ULONG) classname::Release()                                   \
  {                                                                           \
    wxLogRelease(_T(#classname), m_cRef);                                     \
                                                                              \
    if ( --m_cRef == wxAutoULong(0) ) {                                                    \
      delete this;                                                            \
      return 0;                                                               \
    }                                                                         \
    else                                                                      \
      return m_cRef;                                                          \
  }

// ============================================================================
// Debugging support
// ============================================================================

// VZ: I don't know it's not done for compilers other than VC++ but I leave it
//     as is. Please note, though, that tracing OLE interface calls may be
//     incredibly useful when debugging OLE programs.
#if defined(__WXDEBUG__) && ( ( defined(__VISUALC__) && (__VISUALC__ >= 1000) ) || defined(__MWERKS__) )
// ----------------------------------------------------------------------------
// All OLE specific log functions have DebugTrace level (as LogTrace)
// ----------------------------------------------------------------------------

// tries to translate riid into a symbolic name, if possible
void wxLogQueryInterface(const wxChar *szInterface, REFIID riid);

// these functions print out the new value of reference counter
void wxLogAddRef (const wxChar *szInterface, ULONG cRef);
void wxLogRelease(const wxChar *szInterface, ULONG cRef);

#else   //!WXDEBUG
  #define   wxLogQueryInterface(szInterface, riid)
  #define   wxLogAddRef(szInterface, cRef)
  #define   wxLogRelease(szInterface, cRef)
#endif  //WXDEBUG

// wrapper around BSTR type (by Vadim Zeitlin)

class WXDLLEXPORT wxBasicString
{
public:
    // ctors & dtor
    wxBasicString(const char *sz);
    wxBasicString(const wxString& str);
    ~wxBasicString();
    
    void Init(const char* sz);
    
    // accessors
    // just get the string
    operator BSTR() const { return m_wzBuf; }
    // retrieve a copy of our string - caller must SysFreeString() it later!
    BSTR Get() const { return SysAllocString(m_wzBuf); }
    
private:
    // @@@ not implemented (but should be)
    wxBasicString(const wxBasicString&);
    wxBasicString& operator=(const wxBasicString&);
    
    OLECHAR *m_wzBuf;     // actual string
};

// Convert variants
class WXDLLEXPORT wxVariant;

bool wxConvertVariantToOle(const wxVariant& variant, VARIANTARG& oleVariant) ;
bool wxConvertOleToVariant(const VARIANTARG& oleVariant, wxVariant& variant) ;

// Convert string to Unicode
BSTR wxConvertStringToOle(const wxString& str);

// Convert string from BSTR to wxString
wxString wxConvertStringFromOle(BSTR bStr);


#endif  //_WX_OLEUTILS_H
Commit	Line	Data
bbf1f0e5 KB	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: oleutils.h
	3	// Purpose: OLE helper routines, OLE debugging support &c
	4	// Author: Vadim Zeitlin
3f4a0c5b	5	// Modified by:
bbf1f0e5 KB	6	// Created: 19.02.1998
	7	// RCS-ID: $Id$
	8	// Copyright: (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
bbcdf8bc	9	// Licence: wxWindows licence
bbf1f0e5 KB	10	///////////////////////////////////////////////////////////////////////////////
bbf1f0e5 KB	11
bbcdf8bc JS	12	#ifndef _WX_OLEUTILS_H
bbcdf8bc JS	13	#define _WX_OLEUTILS_H
bbf1f0e5	14
12028905	15	#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
bbf1f0e5 KB	16	#pragma interface "oleutils.h"
	17	#endif
	18
e5ad6961	19	#include "wx/defs.h"
82df67d9	20
a7b4607f VZ	21	// get IUnknown, REFIID &c
a7b4607f VZ	22	#include <ole2.h>
82df67d9	23
bbf1f0e5 KB	24	// ============================================================================
	25	// General purpose functions and macros
	26	// ============================================================================
	27
	28	// ----------------------------------------------------------------------------
	29	// misc helper functions/macros
	30	// ----------------------------------------------------------------------------
	31
	32	// release the interface pointer (if !NULL)
	33	inline void ReleaseInterface(IUnknown *pIUnk)
	34	{
	35	if ( pIUnk != NULL )
	36	pIUnk->Release();
	37	}
	38
	39	// release the interface pointer (if !NULL) and make it NULL
	40	#define RELEASE_AND_NULL(p) if ( (p) != NULL ) { p->Release(); p = NULL; };
	41
	42	// return TRUE if the iid is in the array
82df67d9	43	extern bool IsIidFromList(REFIID riid, const IID *aIids[], size_t nCount);
bbf1f0e5 KB	44
	45	// ============================================================================
	46	// IUnknown implementation helpers
	47	// ============================================================================
	48
	49	/*
3f4a0c5b	50	The most dumb implementation of IUnknown methods. We don't support
bbf1f0e5 KB	51	aggregation nor containment, but for 99% of cases this simple
	52	implementation is quite enough.
	53
	54	Usage is trivial: here is all you should have
82df67d9	55	1) DECLARE_IUNKNOWN_METHODS in your (IUnknown derived!) class declaration
bbf1f0e5 KB	56	2) BEGIN/END_IID_TABLE with ADD_IID in between for all interfaces you
	57	support (at least all for which you intent to return 'this' from QI,
	58	i.e. you should derive from IFoo if you have ADD_IID(Foo)) somewhere else
82df67d9	59	3) IMPLEMENT_IUNKNOWN_METHODS somewhere also
bbf1f0e5 KB	60
	61	These macros are quite simple: AddRef and Release are trivial and QI does
	62	lookup in a static member array of IIDs and returns 'this' if it founds
	63	the requested interface in it or E_NOINTERFACE if not.
	64	*/
	65
82df67d9 VZ	66	/*
	67	wxAutoULong: this class is used for automatically initalising m_cRef to 0
	68	*/
	69	class wxAutoULong
	70	{
	71	public:
	72	wxAutoULong(ULONG value = 0) : m_Value(value) { }
	73
	74	operator ULONG&() { return m_Value; }
81833075	75	ULONG& operator=(ULONG value) { m_Value = value; return m_Value; }
018f2884 VZ	76
	77	wxAutoULong& operator++() { ++m_Value; return *this; }
	78	const wxAutoULong operator++( int ) { wxAutoULong temp = *this; ++m_Value; return temp; }
	79
	80	wxAutoULong& operator--() { --m_Value; return *this; }
	81	const wxAutoULong operator--( int ) { wxAutoULong temp = *this; --m_Value; return temp; }
82df67d9 VZ	82
	83	private:
	84	ULONG m_Value;
	85	};
	86
bbf1f0e5 KB	87	// declare the methods and the member variable containing reference count
	88	// you must also define the ms_aIids array somewhere with BEGIN_IID_TABLE
	89	// and friends (see below)
82df67d9	90
bbf1f0e5 KB	91	#define DECLARE_IUNKNOWN_METHODS \
	92	public: \
	93	STDMETHODIMP QueryInterface(REFIID, void **); \
	94	STDMETHODIMP_(ULONG) AddRef(); \
	95	STDMETHODIMP_(ULONG) Release(); \
	96	private: \
	97	static const IID *ms_aIids[]; \
82df67d9	98	wxAutoULong m_cRef
bbf1f0e5 KB	99
	100	// macros for declaring supported interfaces
	101	// NB: you should write ADD_INTERFACE(Foo) and not ADD_INTERFACE(IID_IFoo)!
	102	#define BEGIN_IID_TABLE(cname) const IID *cname::ms_aIids[] = {
	103	#define ADD_IID(iid) &IID_I##iid,
	104	#define END_IID_TABLE }
	105
	106	// implementation is as straightforward as possible
	107	// Parameter: classname - the name of the class
	108	#define IMPLEMENT_IUNKNOWN_METHODS(classname) \
	109	STDMETHODIMP classname::QueryInterface(REFIID riid, void **ppv) \
	110	{ \
f6bcfd97	111	wxLogQueryInterface(_T(#classname), riid); \
bbf1f0e5	112	\
f6bcfd97	113	if ( IsIidFromList(riid, ms_aIids, WXSIZEOF(ms_aIids)) ) { \
bbf1f0e5 KB	114	*ppv = this; \
	115	AddRef(); \
	116	\
	117	return S_OK; \
	118	} \
	119	else { \
	120	*ppv = NULL; \
	121	\
f6bcfd97	122	return (HRESULT) E_NOINTERFACE; \
bbf1f0e5 KB	123	} \
	124	} \
	125	\
	126	STDMETHODIMP_(ULONG) classname::AddRef() \
	127	{ \
f6bcfd97	128	wxLogAddRef(_T(#classname), m_cRef); \
bbf1f0e5 KB	129	\
	130	return ++m_cRef; \
	131	} \
	132	\
	133	STDMETHODIMP_(ULONG) classname::Release() \
	134	{ \
f6bcfd97	135	wxLogRelease(_T(#classname), m_cRef); \
bbf1f0e5	136	\
56689e1b	137	if ( --m_cRef == wxAutoULong(0) ) { \
bbf1f0e5 KB	138	delete this; \
	139	return 0; \
	140	} \
	141	else \
	142	return m_cRef; \
	143	}
	144
	145	// ============================================================================
	146	// Debugging support
	147	// ============================================================================
	148
3f4a0c5b VZ	149	// VZ: I don't know it's not done for compilers other than VC++ but I leave it
	150	// as is. Please note, though, that tracing OLE interface calls may be
	151	// incredibly useful when debugging OLE programs.
ba14d986	152	#if defined(__WXDEBUG__) && ( ( defined(__VISUALC__) && (__VISUALC__ >= 1000) ) \|\| defined(__MWERKS__) )
bbf1f0e5 KB	153	// ----------------------------------------------------------------------------
	154	// All OLE specific log functions have DebugTrace level (as LogTrace)
	155	// ----------------------------------------------------------------------------
	156
	157	// tries to translate riid into a symbolic name, if possible
f6bcfd97	158	void wxLogQueryInterface(const wxChar *szInterface, REFIID riid);
bbf1f0e5 KB	159
bbf1f0e5 KB	160	// these functions print out the new value of reference counter
f6bcfd97 BP	161	void wxLogAddRef (const wxChar *szInterface, ULONG cRef);
f6bcfd97 BP	162	void wxLogRelease(const wxChar *szInterface, ULONG cRef);
bbf1f0e5	163
b2aef89b	164	#else //!WXDEBUG
bbf1f0e5 KB	165	#define wxLogQueryInterface(szInterface, riid)
	166	#define wxLogAddRef(szInterface, cRef)
	167	#define wxLogRelease(szInterface, cRef)
b2aef89b	168	#endif //WXDEBUG
bbf1f0e5	169
45a959a3 JS	170	// wrapper around BSTR type (by Vadim Zeitlin)
	171
	172	class WXDLLEXPORT wxBasicString
	173	{
	174	public:
	175	// ctors & dtor
	176	wxBasicString(const char *sz);
	177	wxBasicString(const wxString& str);
	178	~wxBasicString();
	179
	180	void Init(const char* sz);
	181
	182	// accessors
	183	// just get the string
	184	operator BSTR() const { return m_wzBuf; }
	185	// retrieve a copy of our string - caller must SysFreeString() it later!
	186	BSTR Get() const { return SysAllocString(m_wzBuf); }
	187
	188	private:
	189	// @@@ not implemented (but should be)
	190	wxBasicString(const wxBasicString&);
	191	wxBasicString& operator=(const wxBasicString&);
	192
	193	OLECHAR *m_wzBuf; // actual string
	194	};
	195
	196	// Convert variants
	197	class WXDLLEXPORT wxVariant;
	198
	199	bool wxConvertVariantToOle(const wxVariant& variant, VARIANTARG& oleVariant) ;
	200	bool wxConvertOleToVariant(const VARIANTARG& oleVariant, wxVariant& variant) ;
	201
	202	// Convert string to Unicode
	203	BSTR wxConvertStringToOle(const wxString& str);
	204
	205	// Convert string from BSTR to wxString
	206	wxString wxConvertStringFromOle(BSTR bStr);
	207
	208
3f4a0c5b VZ	209	#endif //_WX_OLEUTILS_H
3f4a0c5b VZ	210