defs.h@ 7944

Last change on this file since 7944 was 6976, checked in by vboxsync, 17 years ago
Main/Glue: Added macro SUCCEEED_WARNING(rc).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.2 KB

Line
1	/** @file
2	* MS COM / XPCOM Abstraction Layer:
3	* Common definitions
4	*/
5
6	/*
7	* Copyright (C) 2006-2007 innotek GmbH
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*
17	* The contents of this file may alternatively be used under the terms
18	* of the Common Development and Distribution License Version 1.0
19	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20	* VirtualBox OSE distribution, in which case the provisions of the
21	* CDDL are applicable instead of those of the GPL.
22	*
23	* You may elect to license modified versions of this file under the
24	* terms and conditions of either the GPL or the CDDL or both.
25	*/
26
27	#ifndef ___VBox_com_defs_h
28	#define ___VBox_com_defs_h
29
30	/*
31	* Include iprt/types.h now to make sure iprt get to stdint.h first,
32	* otherwise a system/xpcom header might beat us and we'll be without
33	* the macros that are optional in C++.
34	*/
35	#include <iprt/types.h>
36
37	#if !defined (VBOX_WITH_XPCOM)
38
39	#if defined (RT_OS_WINDOWS)
40
41	// Windows COM
42	/////////////////////////////////////////////////////////////////////////////
43
44	#include <objbase.h>
45	#ifndef VBOX_COM_NO_ATL
46	#include <atlbase.h>
47	#endif
48
49	#define NS_DECL_ISUPPORTS
50	#define NS_IMPL_ISUPPORTS1_CI(a, b)
51
52	/* these are XPCOM only, one for every interface implemented */
53	#define NS_DECL_ISUPPORTS
54	#define NS_DECL_IVIRTUALBOX
55	#define NS_DECL_IMACHINECOLLECTION
56	#define NS_DECL_IMACHINE
57
58	/** Returns @c true if @a rc represents a warning result code */
59	#define SUCCEEDED_WARNING(rc) (SUCCEEDED (rc) && (rc) != S_OK)
60
61	/* input pointer argument to method */
62	#define INPTR
63
64	/* makes the name of the getter interface function (n must be capitalized) */
65	#define COMGETTER(n) get_##n
66	/* makes the name of the setter interface function (n must be capitalized) */
67	#define COMSETTER(n) put_##n
68
69	/* a type for an input GUID parameter in the interface method declaration */
70	#define GUIDPARAM GUID
71	/* a type for an output GUID parameter in the interface method declaration */
72	#define GUIDPARAMOUT GUID*
73
74	/**
75	* Declares an input safearray parameter in the COM method implementation. Also
76	* used to declare the COM attribute setter parameter. Corresponds to either of
77	* the following XIDL definitions:
78	* <pre>
79	* <param name="arg" ... dir="in" safearray="yes"/>
80	* ...
81	* <attribute name="arg" ... safearray="yes"/>
82	* </pre>
83	*
84	* The method implementation should use the com::SafeArray helper class to work
85	* with parameters declared using this define.
86	*
87	* @param aType Array element type.
88	* @param aArg Parameter/attribute name.
89	*/
90	#define ComSafeArrayIn(aType, aArg) SAFEARRAY **aArg
91
92	/**
93	* Expands to @true if the given input safearray parameter is a "null pointer"
94	* which makes it impossible to use it for reading safearray data.
95	*/
96	#define ComSafeArrayInIsNull(aArg) (aArg == NULL)
97
98	/**
99	* Wraps the given parameter name to generate an expression that is suitable for
100	* passing the parameter to functions that take input safearray parameters
101	* declared using the ComSafeArrayIn marco.
102	*
103	* @param aArg Parameter name to wrap. The given parameter must be declared
104	* within the calling function using the ComSafeArrayIn macro.
105	*/
106	#define ComSafeArrayInArg(aArg) aArg
107
108	/**
109	* Declares an output safearray parameter in the COM method implementation. Also
110	* used to declare the COM attribute getter parameter. Corresponds to either of
111	* the following XIDL definitions:
112	* <pre>
113	* <param name="arg" ... dir="out" safearray="yes"/>
114	* <param name="arg" ... dir="return" safearray="yes"/>
115	* ...
116	* <attribute name="arg" ... safearray="yes"/>
117	* </pre>
118	*
119	* The method implementation should use the com::SafeArray helper class to work
120	* with parameters declared using this define.
121	*
122	* @param aType Array element type.
123	* @param aArg Parameter/attribute name.
124	*/
125	#define ComSafeArrayOut(aType, aArg) SAFEARRAY **aArg
126
127	/**
128	* Expands to @true if the given output safearray parameter is a "null pointer"
129	* which makes it impossible to use it for returning a safearray.
130	*/
131	#define ComSafeArrayOutIsNull(aArg) (aArg == NULL)
132
133	/**
134	* Wraps the given parameter name to generate an expression that is suitable for
135	* passing the parameter to functions that take output safearray parameters
136	* declared using the ComSafeArrayOut marco.
137	*
138	* @param aArg Parameter name to wrap. The given parameter must be declared
139	* within the calling function using the ComSafeArrayOut macro.
140	*/
141	#define ComSafeArrayOutArg(aArg) aArg
142
143	/**
144	* Returns the const reference to the IID (i.e., \|const GUID &\|) of the given
145	* interface.
146	*
147	* @param i interface class
148	*/
149	#define COM_IIDOF(I) _ATL_IIDOF (I)
150
151	#else /* defined (RT_OS_WINDOWS) */
152
153	#error "VBOX_WITH_XPCOM must be defined on a platform other than Windows!"
154
155	#endif /* defined (RT_OS_WINDOWS) */
156
157	#else /* !defined (VBOX_WITH_XPCOM) */
158
159	// XPCOM
160	/////////////////////////////////////////////////////////////////////////////
161
162	#if defined (RT_OS_OS2)
163
164	/* Make sure OS/2 Toolkit headers are pulled in to have
165	* BOOL/ULONG/etc. typedefs already defined in order to be able to redefine
166	* them using #define. */
167	#define INCL_BASE
168	#define INCL_PM
169	#include <os2.h>
170
171	/* OS/2 Toolkit defines TRUE and FALSE */
172	#undef FALSE
173	#undef TRUE
174
175	#endif /* defined (RT_OS_OS2) */
176
177	#if defined (RT_OS_DARWIN)
178	/* CFBase.h defines these*/
179	# undef FALSE
180	# undef TRUE
181	#endif /* RT_OS_DARWIN */
182
183	#include <nsID.h>
184
185	#define ATL_NO_VTABLE
186	#define DECLARE_CLASSFACTORY(a)
187	#define DECLARE_CLASSFACTORY_SINGLETON(a)
188	#define DECLARE_REGISTRY_RESOURCEID(a)
189	#define DECLARE_NOT_AGGREGATABLE(a)
190	#define DECLARE_PROTECT_FINAL_CONSTRUCT(a)
191	#define BEGIN_COM_MAP(a)
192	#define COM_INTERFACE_ENTRY(a)
193	#define COM_INTERFACE_ENTRY2(a,b)
194	#define END_COM_MAP(a)
195
196	#define HRESULT nsresult
197	#define SUCCEEDED NS_SUCCEEDED
198	#define FAILED NS_FAILED
199
200	#define SUCCEEDED_WARNING(rc) (NS_SUCCEEDED (rc) && (rc) != NS_OK)
201
202	#define IUnknown nsISupports
203
204	#define BOOL PRBool
205	#define BYTE PRUint8
206	#define SHORT PRInt16
207	#define USHORT PRUint16
208	#define LONG PRInt32
209	#define ULONG PRUint32
210	#define LONG64 PRInt64
211	#define ULONG64 PRUint64
212
213	#define BSTR PRUnichar *
214	#define LPBSTR BSTR *
215	#define OLECHAR wchar_t
216
217	#define FALSE PR_FALSE
218	#define TRUE PR_TRUE
219
220	/* makes the name of the getter interface function (n must be capitalized) */
221	#define COMGETTER(n) Get##n
222	/* makes the name of the setter interface function (n must be capitalized) */
223	#define COMSETTER(n) Set##n
224
225	/* a type to define a raw GUID variable (better to use the Guid class) */
226	#define GUID nsID
227	/* a type for an input GUID parameter in the interface method declaration */
228	#define GUIDPARAM nsID &
229	/* a type for an output GUID parameter in the interface method declaration */
230	#define GUIDPARAMOUT nsID **
231
232	/* safearray input parameter macros */
233	#define ComSafeArrayIn(aType, aArg) PRUint32 aArg##Size, aType *aArg
234	#define ComSafeArrayInIsNull(aArg) (aArg == NULL)
235	#define ComSafeArrayInArg(aArg) aArg##Size, aArg
236
237	/* safearray output parameter macros */
238	#define ComSafeArrayOut(aType, aArg) PRUint32 aArg##Size, aType *aArg
239	#define ComSafeArrayOutIsNull(aArg) (aArg == NULL)
240	#define ComSafeArrayOutArg(aArg) aArg##Size, aArg
241
242	/* CLSID and IID for compatibility with Win32 */
243	typedef nsCID CLSID;
244	typedef nsIID IID;
245
246	/* OLE error codes */
247	#define S_OK NS_OK
248	#define E_UNEXPECTED NS_ERROR_UNEXPECTED
249	#define E_NOTIMPL NS_ERROR_NOT_IMPLEMENTED
250	#define E_OUTOFMEMORY NS_ERROR_OUT_OF_MEMORY
251	#define E_INVALIDARG NS_ERROR_INVALID_ARG
252	#define E_NOINTERFACE NS_ERROR_NO_INTERFACE
253	#define E_POINTER NS_ERROR_NULL_POINTER
254	#define E_ABORT NS_ERROR_ABORT
255	#define E_FAIL NS_ERROR_FAILURE
256	/* Note: a better analog for E_ACCESSDENIED would probably be
257	* NS_ERROR_NOT_AVAILABLE, but we want binary compatibility for now. */
258	#define E_ACCESSDENIED ((nsresult) 0x80070005L)
259
260	#define STDMETHOD(a) NS_IMETHOD a
261	#define STDMETHODIMP NS_IMETHODIMP
262
263	#define COM_IIDOF(I) NS_GET_IID (I)
264
265	/* two very simple ATL emulator classes to provide
266	* FinalConstruct()/FinalRelease() functionality on Linux */
267
268	class CComObjectRootEx
269	{
270	public:
271	HRESULT FinalConstruct() { return S_OK; }
272	void FinalRelease() {}
273	};
274
275	template <class Base> class CComObject : public Base
276	{
277	public:
278	virtual ~CComObject() { this->FinalRelease(); }
279	};
280
281	/* input pointer argument to method */
282	#define INPTR const
283
284	/* helper functions */
285	extern "C"
286	{
287	BSTR SysAllocString (const OLECHAR* sz);
288	BSTR SysAllocStringByteLen (char *psz, unsigned int len);
289	BSTR SysAllocStringLen (const OLECHAR *pch, unsigned int cch);
290	void SysFreeString (BSTR bstr);
291	int SysReAllocString (BSTR pbstr, const OLECHAR psz);
292	int SysReAllocStringLen (BSTR pbstr, const OLECHAR psz, unsigned int cch);
293	unsigned int SysStringByteLen (BSTR bstr);
294	unsigned int SysStringLen (BSTR bstr);
295	}
296
297	/**
298	* 'Constructor' for the component class.
299	* This constructor, as opposed to NS_GENERIC_FACTORY_CONSTRUCTOR,
300	* assumes that the component class is derived from the CComObjectRootEx<>
301	* template, so it calls FinalConstruct() right after object creation
302	* and ensures that FinalRelease() will be called right before destruction.
303	* The result from FinalConstruct() is returned to the caller.
304	*/
305	#define NS_GENERIC_FACTORY_CONSTRUCTOR_WITH_RC(_InstanceClass) \
306	static NS_IMETHODIMP \
307	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
308	void **aResult) \
309	{ \
310	nsresult rv; \
311	\
312	*aResult = NULL; \
313	if (NULL != aOuter) { \
314	rv = NS_ERROR_NO_AGGREGATION; \
315	return rv; \
316	} \
317	\
318	CComObject <_InstanceClass> *inst = new CComObject <_InstanceClass>(); \
319	if (NULL == inst) { \
320	rv = NS_ERROR_OUT_OF_MEMORY; \
321	return rv; \
322	} \
323	\
324	NS_ADDREF(inst); /* protect FinalConstruct() */ \
325	rv = inst->FinalConstruct(); \
326	if (NS_SUCCEEDED(rv)) \
327	rv = inst->QueryInterface(aIID, aResult); \
328	NS_RELEASE(inst); \
329	\
330	return rv; \
331	}
332
333	/**
334	* 'Constructor' that uses an existing getter function that gets a singleton.
335	* The getter function must have the following prototype:
336	* nsresult _GetterProc (_InstanceClass **inst)
337	* This constructor, as opposed to NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR,
338	* lets the getter function return a result code that is passed back to the
339	* caller that tries to instantiate the object.
340	* NOTE: assumes that getter does an AddRef - so additional AddRef is not done.
341	*/
342	#define NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR_WITH_RC(_InstanceClass, _GetterProc) \
343	static NS_IMETHODIMP \
344	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
345	void **aResult) \
346	{ \
347	nsresult rv; \
348	\
349	_InstanceClass * inst; \
350	\
351	*aResult = NULL; \
352	if (NULL != aOuter) { \
353	rv = NS_ERROR_NO_AGGREGATION; \
354	return rv; \
355	} \
356	\
357	rv = _GetterProc(&inst); \
358	if (NS_FAILED(rv)) \
359	return rv; \
360	\
361	/* sanity check */ \
362	if (NULL == inst) \
363	return NS_ERROR_OUT_OF_MEMORY; \
364	\
365	/* NS_ADDREF(inst); */ \
366	if (NS_SUCCEEDED(rv)) { \
367	rv = inst->QueryInterface(aIID, aResult); \
368	} \
369	NS_RELEASE(inst); \
370	\
371	return rv; \
372	}
373
374	#endif /* !defined (VBOX_WITH_XPCOM) */
375
376	/**
377	* Declares a whar_t string literal from the argument.
378	* Necessary to overcome MSC / GCC differences.
379	* @param s expression to stringify
380	*/
381	#if defined (_MSC_VER)
382	# define WSTR_LITERAL(s) L#s
383	#elif defined (__GNUC__)
384	# define WSTR_LITERAL(s) L""#s
385	#else
386	# error "Unsupported compiler!"
387	#endif
388
389	namespace com
390	{
391
392	/**
393	* "Last worst" result type.
394	*
395	* Variables of this class are used instead of HRESULT variables when it is
396	* desirable to memorize the "last worst" result code instead of the last
397	* assigned one. In other words, an assignment operation to a variable of this
398	* class will succeed only if the result code to assign has the same or worse
399	* severity. The following table demonstrate this (the first column lists the
400	* previous result code stored in the variable, the first row lists the new
401	* result code being assigned, 'A' means the assignment will take place):
402	*
403	* {{{
404	* FAILED > S_OK S_OK
405	* FAILED A - -
406	* > S_OK A A -
407	* S_OK A A -
408	*
409	* }}}
410	*/
411	class LWResult
412	{
413
414	public:
415
416	/**
417	* Constructs a new variable. Note that by default this constructor sets the
418	* result code to E_FAIL to make sure a failure is returned to the caller if
419	* the variable is never assigned another value (which is considered as the
420	* improper use of this class).
421	*/
422	LWResult (HRESULT aRC = E_FAIL) : mRC (aRC) {}
423
424	LWResult &operator= (HRESULT aRC)
425	{
426	if (FAILED (aRC) \|\|
427	(SUCCEEDED (mRC) && aRC != S_OK))
428	mRC = aRC;
429
430	return *this;
431	}
432
433	operator HRESULT() const { return mRC; }
434
435	HRESULT *operator&() { return &mRC; }
436
437	private:
438
439	HRESULT mRC;
440	};
441
442	} /* namespace com */
443
444	#endif /* ___VBox_com_defs_h */
445

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/VBox/com/defs.h@ 7944

Download in other formats: