defs.h@ 11856

Last change on this file since 11856 was 11390, checked in by vboxsync, 16 years ago
Changed definition of ComSafeArrayInIsNull to work properly on Windows as well.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.9 KB

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

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

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

Download in other formats: