defs.h@ 13648

Last change on this file since 13648 was 13580, checked in by vboxsync, 16 years ago
Ported s2 branch (r37120:38456).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 20.5 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	#include <atlcom.h>
74	#endif
75
76	#define NS_DECL_ISUPPORTS
77	#define NS_IMPL_ISUPPORTS1_CI(a, b)
78
79	/* these are XPCOM only, one for every interface implemented */
80	#define NS_DECL_ISUPPORTS
81	#define NS_DECL_IVIRTUALBOX
82	#define NS_DECL_IMACHINECOLLECTION
83	#define NS_DECL_IMACHINE
84
85	/** Returns @c true if @a rc represents a warning result code */
86	#define SUCCEEDED_WARNING(rc) (SUCCEEDED (rc) && (rc) != S_OK)
87
88	/** Input pointer argument prefix in the interface method declaration. */
89	#define INPTR
90
91	/** Makes the name of the getter interface function (n must be capitalized). */
92	#define COMGETTER(n) get_##n
93	/** Makes the name of the setter interface function (n must be capitalized). */
94	#define COMSETTER(n) put_##n
95
96	/** Type for an input GUID parameter in the interface method declaration. */
97	#define GUIDPARAM GUID
98	/** Type for an output GUID parameter in the interface method declaration. */
99	#define GUIDPARAMOUT GUID*
100
101	/**
102	* Declares an input safearray parameter in the COM method implementation. Also
103	* used to declare the COM attribute setter parameter. Corresponds to either of
104	* the following XIDL definitions:
105	* <pre>
106	* <param name="arg" ... dir="in" safearray="yes"/>
107	* ...
108	* <attribute name="arg" ... safearray="yes"/>
109	* </pre>
110	*
111	* The method implementation should use the com::SafeArray helper class to work
112	* with parameters declared using this define.
113	*
114	* @param aType Array element type.
115	* @param aArg Parameter/attribute name.
116	*/
117	#define ComSafeArrayIn(aType, aArg) SAFEARRAY **aArg
118
119	/**
120	* Expands to @true if the given input safearray parameter is a "null pointer"
121	* which makes it impossible to use it for reading safearray data.
122	*/
123	#define ComSafeArrayInIsNull(aArg) ((aArg) == NULL \|\| *(aArg) == NULL)
124
125	/**
126	* Wraps the given parameter name to generate an expression that is suitable for
127	* passing the parameter to functions that take input safearray parameters
128	* declared using the ComSafeArrayIn marco.
129	*
130	* @param aArg Parameter name to wrap. The given parameter must be declared
131	* within the calling function using the ComSafeArrayIn macro.
132	*/
133	#define ComSafeArrayInArg(aArg) aArg
134
135	/**
136	* Declares an output safearray parameter in the COM method implementation. Also
137	* used to declare the COM attribute getter parameter. Corresponds to either of
138	* the following XIDL definitions:
139	* <pre>
140	* <param name="arg" ... dir="out" safearray="yes"/>
141	* <param name="arg" ... dir="return" safearray="yes"/>
142	* ...
143	* <attribute name="arg" ... safearray="yes"/>
144	* </pre>
145	*
146	* The method implementation should use the com::SafeArray helper class to work
147	* with parameters declared using this define.
148	*
149	* @param aType Array element type.
150	* @param aArg Parameter/attribute name.
151	*/
152	#define ComSafeArrayOut(aType, aArg) SAFEARRAY **aArg
153
154	/**
155	* Expands to @true if the given output safearray parameter is a "null pointer"
156	* which makes it impossible to use it for returning a safearray.
157	*/
158	#define ComSafeArrayOutIsNull(aArg) ((aArg) == NULL)
159
160	/**
161	* Wraps the given parameter name to generate an expression that is suitable for
162	* passing the parameter to functions that take output safearray parameters
163	* declared using the ComSafeArrayOut marco.
164	*
165	* @param aArg Parameter name to wrap. The given parameter must be declared
166	* within the calling function using the ComSafeArrayOut macro.
167	*/
168	#define ComSafeArrayOutArg(aArg) aArg
169
170	/**
171	* Version of ComSafeArrayIn for GUID.
172	* @param aArg Parameter name to wrap.
173	*/
174	#define ComSafeGUIDArrayIn(aArg) SAFEARRAY **aArg
175
176	/**
177	* Version of ComSafeArrayInIsNull for GUID.
178	* @param aArg Parameter name to wrap.
179	*/
180	#define ComSafeGUIDArrayInIsNull(aArg) ComSafeArrayInIsNull (aArg)
181
182	/**
183	* Version of ComSafeArrayInArg for GUID.
184	* @param aArg Parameter name to wrap.
185	*/
186	#define ComSafeGUIDArrayInArg(aArg) ComSafeArrayInArg (aArg)
187
188	/**
189	* Version of ComSafeArrayOut for GUID.
190	* @param aArg Parameter name to wrap.
191	*/
192	#define ComSafeGUIDArrayOut(aArg) SAFEARRAY **aArg
193
194	/**
195	* Version of ComSafeArrayOutIsNull for GUID.
196	* @param aArg Parameter name to wrap.
197	*/
198	#define ComSafeGUIDArrayOutIsNull(aArg) ComSafeArrayOutIsNull (aArg)
199
200	/**
201	* Version of ComSafeArrayOutArg for GUID.
202	* @param aArg Parameter name to wrap.
203	*/
204	#define ComSafeGUIDArrayOutArg(aArg) ComSafeArrayOutArg (aArg)
205
206	/**
207	* Returns the const reference to the IID (i.e., \|const GUID &\|) of the given
208	* interface.
209	*
210	* @param i interface class
211	*/
212	#define COM_IIDOF(I) _ATL_IIDOF (I)
213
214	#else /* defined (RT_OS_WINDOWS) */
215
216	#error "VBOX_WITH_XPCOM must be defined on a platform other than Windows!"
217
218	#endif /* defined (RT_OS_WINDOWS) */
219
220	#else /* !defined (VBOX_WITH_XPCOM) */
221
222	// XPCOM
223	/////////////////////////////////////////////////////////////////////////////
224
225	#if defined (RT_OS_DARWIN) \|\| (defined (QT_VERSION) && (QT_VERSION >= 0x040000))
226	/* CFBase.h defines these &
227	* qglobal.h from Qt4 defines these */
228	# undef FALSE
229	# undef TRUE
230	#endif /* RT_OS_DARWIN \|\| QT_VERSION */
231
232	#include <nsID.h>
233
234	#define ATL_NO_VTABLE
235	#define DECLARE_CLASSFACTORY(a)
236	#define DECLARE_CLASSFACTORY_SINGLETON(a)
237	#define DECLARE_REGISTRY_RESOURCEID(a)
238	#define DECLARE_NOT_AGGREGATABLE(a)
239	#define DECLARE_PROTECT_FINAL_CONSTRUCT(a)
240	#define BEGIN_COM_MAP(a)
241	#define COM_INTERFACE_ENTRY(a)
242	#define COM_INTERFACE_ENTRY2(a,b)
243	#define END_COM_MAP(a)
244
245	#define HRESULT nsresult
246	#define SUCCEEDED NS_SUCCEEDED
247	#define FAILED NS_FAILED
248
249	#define SUCCEEDED_WARNING(rc) (NS_SUCCEEDED (rc) && (rc) != NS_OK)
250
251	#define IUnknown nsISupports
252
253	#define BOOL PRBool
254	#define BYTE PRUint8
255	#define SHORT PRInt16
256	#define USHORT PRUint16
257	#define LONG PRInt32
258	#define ULONG PRUint32
259	#define LONG64 PRInt64
260	#define ULONG64 PRUint64
261
262	#define BSTR PRUnichar *
263	#define LPBSTR BSTR *
264	#define OLECHAR wchar_t
265
266	#define FALSE PR_FALSE
267	#define TRUE PR_TRUE
268
269	/** Input pointer argument prefix in the interface method declaration. */
270	#define INPTR const
271
272	/** Makes the name of the getter interface function (n must be capitalized). */
273	#define COMGETTER(n) Get##n
274	/** Makes the name of the setter interface function (n must be capitalized). */
275	#define COMSETTER(n) Set##n
276
277	/**
278	* Type to define a raw GUID variable (for members use the com::Guid class
279	* instead).
280	*/
281	#define GUID nsID
282	/** Type for an input GUID parameter in the interface method declaration. */
283	#define GUIDPARAM nsID &
284	/** Type for an output GUID parameter in the interface method declaration. */
285	#define GUIDPARAMOUT nsID **
286
287	/* safearray input parameter macros */
288	#define ComSafeArrayIn(aType, aArg) PRUint32 aArg##Size, aType *aArg
289	#define ComSafeArrayInIsNull(aArg) ((aArg) == NULL)
290	#define ComSafeArrayInArg(aArg) aArg##Size, aArg
291
292	/* safearray output parameter macros */
293	#define ComSafeArrayOut(aType, aArg) PRUint32 aArg##Size, aType *aArg
294	#define ComSafeArrayOutIsNull(aArg) ((aArg) == NULL)
295	#define ComSafeArrayOutArg(aArg) aArg##Size, aArg
296
297	/* safearray input parameter macros for GUID */
298	#define ComSafeGUIDArrayIn(aArg) PRUint32 aArg##Size, const nsID **aArg
299	#define ComSafeGUIDArrayInIsNull(aArg) ComSafeArrayInIsNull (aArg)
300	#define ComSafeGUIDArrayInArg(aArg) ComSafeArrayInArg (aArg)
301
302	/* safearray output parameter macros for GUID */
303	#define ComSafeGUIDArrayOut(aArg) PRUint32 aArg##Size, nsID **aArg
304	#define ComSafeGUIDArrayOutIsNull(aArg) ComSafeArrayOutIsNull (aArg)
305	#define ComSafeGUIDArrayOutArg(aArg) ComSafeArrayOutArg (aArg)
306
307	/* CLSID and IID for compatibility with Win32 */
308	typedef nsCID CLSID;
309	typedef nsIID IID;
310
311	/* OLE error codes */
312	#define S_OK ((nsresult) NS_OK)
313	#define E_UNEXPECTED NS_ERROR_UNEXPECTED
314	#define E_NOTIMPL NS_ERROR_NOT_IMPLEMENTED
315	#define E_OUTOFMEMORY NS_ERROR_OUT_OF_MEMORY
316	#define E_INVALIDARG NS_ERROR_INVALID_ARG
317	#define E_NOINTERFACE NS_ERROR_NO_INTERFACE
318	#define E_POINTER NS_ERROR_NULL_POINTER
319	#define E_ABORT NS_ERROR_ABORT
320	#define E_FAIL NS_ERROR_FAILURE
321	/* Note: a better analog for E_ACCESSDENIED would probably be
322	* NS_ERROR_NOT_AVAILABLE, but we want binary compatibility for now. */
323	#define E_ACCESSDENIED ((nsresult) 0x80070005L)
324
325	#define STDMETHOD(a) NS_IMETHOD a
326	#define STDMETHODIMP NS_IMETHODIMP
327
328	#define COM_IIDOF(I) NS_GET_IID (I)
329
330	/* two very simple ATL emulator classes to provide
331	* FinalConstruct()/FinalRelease() functionality on Linux */
332
333	class CComObjectRootEx
334	{
335	public:
336	HRESULT FinalConstruct() { return S_OK; }
337	void FinalRelease() {}
338	};
339
340	template <class Base> class CComObject : public Base
341	{
342	public:
343	virtual ~CComObject() { this->FinalRelease(); }
344	};
345
346	/* helper functions */
347	extern "C"
348	{
349	BSTR SysAllocString (const OLECHAR* sz);
350	BSTR SysAllocStringByteLen (char *psz, unsigned int len);
351	BSTR SysAllocStringLen (const OLECHAR *pch, unsigned int cch);
352	void SysFreeString (BSTR bstr);
353	int SysReAllocString (BSTR pbstr, const OLECHAR psz);
354	int SysReAllocStringLen (BSTR pbstr, const OLECHAR psz, unsigned int cch);
355	unsigned int SysStringByteLen (BSTR bstr);
356	unsigned int SysStringLen (BSTR bstr);
357	}
358
359	/**
360	* 'Constructor' for the component class.
361	* This constructor, as opposed to NS_GENERIC_FACTORY_CONSTRUCTOR,
362	* assumes that the component class is derived from the CComObjectRootEx<>
363	* template, so it calls FinalConstruct() right after object creation
364	* and ensures that FinalRelease() will be called right before destruction.
365	* The result from FinalConstruct() is returned to the caller.
366	*/
367	#define NS_GENERIC_FACTORY_CONSTRUCTOR_WITH_RC(_InstanceClass) \
368	static NS_IMETHODIMP \
369	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
370	void **aResult) \
371	{ \
372	nsresult rv; \
373	\
374	*aResult = NULL; \
375	if (NULL != aOuter) { \
376	rv = NS_ERROR_NO_AGGREGATION; \
377	return rv; \
378	} \
379	\
380	CComObject <_InstanceClass> *inst = new CComObject <_InstanceClass>(); \
381	if (NULL == inst) { \
382	rv = NS_ERROR_OUT_OF_MEMORY; \
383	return rv; \
384	} \
385	\
386	NS_ADDREF(inst); /* protect FinalConstruct() */ \
387	rv = inst->FinalConstruct(); \
388	if (NS_SUCCEEDED(rv)) \
389	rv = inst->QueryInterface(aIID, aResult); \
390	NS_RELEASE(inst); \
391	\
392	return rv; \
393	}
394
395	/**
396	* 'Constructor' that uses an existing getter function that gets a singleton.
397	* The getter function must have the following prototype:
398	* nsresult _GetterProc (_InstanceClass **inst)
399	* This constructor, as opposed to NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR,
400	* lets the getter function return a result code that is passed back to the
401	* caller that tries to instantiate the object.
402	* NOTE: assumes that getter does an AddRef - so additional AddRef is not done.
403	*/
404	#define NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR_WITH_RC(_InstanceClass, _GetterProc) \
405	static NS_IMETHODIMP \
406	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
407	void **aResult) \
408	{ \
409	nsresult rv; \
410	\
411	_InstanceClass * inst; \
412	\
413	*aResult = NULL; \
414	if (NULL != aOuter) { \
415	rv = NS_ERROR_NO_AGGREGATION; \
416	return rv; \
417	} \
418	\
419	rv = _GetterProc(&inst); \
420	if (NS_FAILED(rv)) \
421	return rv; \
422	\
423	/* sanity check */ \
424	if (NULL == inst) \
425	return NS_ERROR_OUT_OF_MEMORY; \
426	\
427	/* NS_ADDREF(inst); */ \
428	if (NS_SUCCEEDED(rv)) { \
429	rv = inst->QueryInterface(aIID, aResult); \
430	} \
431	NS_RELEASE(inst); \
432	\
433	return rv; \
434	}
435
436	#endif /* !defined (VBOX_WITH_XPCOM) */
437
438	/**
439	* Declares a whar_t string literal from the argument.
440	* Necessary to overcome MSC / GCC differences.
441	* @param s expression to stringify
442	*/
443	#if defined (_MSC_VER)
444	# define WSTR_LITERAL(s) L#s
445	#elif defined (__GNUC__)
446	# define WSTR_LITERAL(s) L""#s
447	#else
448	# error "Unsupported compiler!"
449	#endif
450
451	namespace com
452	{
453
454	/**
455	* "First worst" result type.
456	*
457	* Variables of this class are used instead of HRESULT variables when it is
458	* desirable to memorize the "first worst" result code instead of the last
459	* assigned one. In other words, an assignment operation to a variable of this
460	* class will succeed only if the result code to assign has worse severity. The
461	* following table demonstrate this (the first column lists the previous result
462	* code stored in the variable, the first row lists the new result code being
463	* assigned, 'A' means the assignment will take place, '> S_OK' means a warning
464	* result code):
465	*
466	* {{{
467	* FAILED > S_OK S_OK
468	* FAILED - - -
469	* > S_OK A - -
470	* S_OK A A -
471	*
472	* }}}
473	*
474	* On practice, you will need to use a FWResult variable when you call some COM
475	* method B after another COM method A fails and want to return the result code
476	* of A even if B also fails, but want to return the failed result code of B if
477	* A issues a warning or succeeds.
478	*/
479	class FWResult
480	{
481
482	public:
483
484	/**
485	* Constructs a new variable. Note that by default this constructor sets the
486	* result code to E_FAIL to make sure a failure is returned to the caller if
487	* the variable is never assigned another value (which is considered as the
488	* improper use of this class).
489	*/
490	FWResult (HRESULT aRC = E_FAIL) : mRC (aRC) {}
491
492	FWResult &operator= (HRESULT aRC)
493	{
494	if ((FAILED (aRC) && !FAILED (mRC)) \|\|
495	(mRC == S_OK && aRC != S_OK))
496	mRC = aRC;
497
498	return *this;
499	}
500
501	operator HRESULT() const { return mRC; }
502
503	HRESULT *operator&() { return &mRC; }
504
505	private:
506
507	HRESULT mRC;
508	};
509
510	/**
511	* "Last worst" result type.
512	*
513	* Variables of this class are used instead of HRESULT variables when it is
514	* desirable to memorize the "last worst" result code instead of the last
515	* assigned one. In other words, an assignment operation to a variable of this
516	* class will succeed only if the result code to assign has the same or worse
517	* severity. The following table demonstrate this (the first column lists the
518	* previous result code stored in the variable, the first row lists the new
519	* assigned, 'A' means the assignment will take place, '> S_OK' means a warning
520	* result code):
521	*
522	* {{{
523	* FAILED > S_OK S_OK
524	* FAILED A - -
525	* > S_OK A A -
526	* S_OK A A -
527	*
528	* }}}
529	*
530	* On practice, you will need to use a LWResult variable when you call some COM
531	* method B after COM method A fails and want to return the result code of B
532	* if B also fails, but still want to return the failed result code of A if B
533	* issues a warning or succeeds.
534	*/
535	class LWResult
536	{
537
538	public:
539
540	/**
541	* Constructs a new variable. Note that by default this constructor sets the
542	* result code to E_FAIL to make sure a failure is returned to the caller if
543	* the variable is never assigned another value (which is considered as the
544	* improper use of this class).
545	*/
546	LWResult (HRESULT aRC = E_FAIL) : mRC (aRC) {}
547
548	LWResult &operator= (HRESULT aRC)
549	{
550	if (FAILED (aRC) \|\|
551	(SUCCEEDED (mRC) && aRC != S_OK))
552	mRC = aRC;
553
554	return *this;
555	}
556
557	operator HRESULT() const { return mRC; }
558
559	HRESULT *operator&() { return &mRC; }
560
561	private:
562
563	HRESULT mRC;
564	};
565
566	} /* namespace com */
567
568	#endif /* ___VBox_com_defs_h */
569

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

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

Download in other formats: