[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

#ifdef __GNUG__
#pragma interface "oleutils.h"
#endif

#include "wx/defs.h"
#ifdef wxUSE_NORLANDER_HEADERS
#include <ole2.h>
#endif
// ============================================================================
// 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
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_METHOS 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_METHOS 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.
 */

// 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[];                                         \
    ULONG                 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 == 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)
// ----------------------------------------------------------------------------
// 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

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