defs.h@ 58128

Last change on this file since 58128 was 58110, checked in by vboxsync, 9 years ago
include,misc: Doxygen grouping adjustments, collecting all the VMM bits under one parent group, ditto for the COM library.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 21.6 KB

Line
1	/** @file
2	* MS COM / XPCOM Abstraction Layer - Common Definitions.
3	*/
4
5	/*
6	* Copyright (C) 2006-2015 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___VBox_com_defs_h
27	#define ___VBox_com_defs_h
28
29	/* Make sure all the stdint.h macros are included - must come first! */
30	#ifndef __STDC_LIMIT_MACROS
31	# define __STDC_LIMIT_MACROS
32	#endif
33	#ifndef __STDC_CONSTANT_MACROS
34	# define __STDC_CONSTANT_MACROS
35	#endif
36
37	#if defined (RT_OS_OS2)
38
39	# if defined(RT_MAX) && RT_MAX != 22
40	# undef RT_MAX
41	# define REDEFINE_RT_MAX
42	# endif
43	# undef RT_MAX
44
45	/* Make sure OS/2 Toolkit headers are pulled in to have BOOL/ULONG/etc. typedefs
46	* already defined in order to be able to redefine them using #define. */
47	# define INCL_BASE
48	# define INCL_PM
49	# include <os2.h>
50
51	/* OS/2 Toolkit defines TRUE and FALSE */
52	# undef FALSE
53	# undef TRUE
54
55	/* */
56	# undef RT_MAX
57	# ifdef REDEFINE_RT_MAX
58	# define RT_MAX(Value1, Value2) ( (Value1) >= (Value2) ? (Value1) : (Value2) )
59	# endif
60
61	#endif /* defined(RT_OS_OS2) */
62
63	/* Include iprt/types.h (which also includes iprt/types.h) now to make sure iprt
64	* gets to stdint.h first, otherwise a system/xpcom header might beat us and
65	* we'll be without the macros that are optional in C++. */
66	#include <iprt/types.h>
67
68
69
70	/** @defgroup grp_com_defs Common Definitions
71	* @ingroup grp_com
72	* @{
73	*/
74
75	#if !defined(VBOX_WITH_XPCOM)
76
77	#if defined(RT_OS_WINDOWS)
78
79	// Windows COM
80	/////////////////////////////////////////////////////////////////////////////
81
82	#include <objbase.h>
83	#ifndef VBOX_COM_NO_ATL
84	# define _ATL_FREE_THREADED
85
86	# include <atlbase.h>
87	#include <atlcom.h>
88	#endif
89
90	#define NS_DECL_ISUPPORTS
91	#define NS_IMPL_ISUPPORTS1_CI(a, b)
92
93	/* these are XPCOM only, one for every interface implemented */
94	#define NS_DECL_ISUPPORTS
95
96	/** Returns @c true if @a rc represents a warning result code */
97	#define SUCCEEDED_WARNING(rc) (SUCCEEDED(rc) && (rc) != S_OK)
98
99	/** Tests is a COM result code indicates that the process implementing the
100	* interface is dead.
101	*
102	* COM status codes:
103	* 0x800706ba - RPC_S_SERVER_UNAVAILABLE. Killed before call was made.
104	* 0x800706be - RPC_S_CALL_FAILED. Killed after call was made.
105	* 0x800706bf - RPC_S_CALL_FAILED_DNE. Not observed, but should be
106	* matter of timing.
107	* 0x80010108 - RPC_E_DISCONNECTED. Observed deregistering
108	* python event listener.
109	* 0x800706b5 - RPC_S_UNKNOWN_IF. Observed deregistering python
110	* event listener
111	*/
112	#define FAILED_DEAD_INTERFACE(rc) \
113	( (rc) == HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) \
114	\|\| (rc) == HRESULT_FROM_WIN32(RPC_S_CALL_FAILED) \
115	\|\| (rc) == HRESULT_FROM_WIN32(RPC_S_CALL_FAILED_DNE) \
116	\|\| (rc) == RPC_E_DISCONNECTED \
117	)
118
119	/** Immutable BSTR string */
120	typedef const OLECHAR *CBSTR;
121
122	/** Input BSTR argument of interface method declaration. */
123	#define IN_BSTR BSTR
124
125	/** Input GUID argument of interface method declaration. */
126	#define IN_GUID GUID
127	/** Output GUID argument of interface method declaration. */
128	#define OUT_GUID GUID*
129
130	/** Makes the name of the getter interface function (n must be capitalized). */
131	#define COMGETTER(n) get_##n
132	/** Makes the name of the setter interface function (n must be capitalized). */
133	#define COMSETTER(n) put_##n
134
135	/**
136	* Declares an input safearray parameter in the COM method implementation. Also
137	* used to declare the COM attribute setter parameter. Corresponds to either of
138	* the following XIDL definitions:
139	* <pre>
140	* <param name="arg" ... dir="in" 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 ComSafeArrayIn(aType, aArg) SAFEARRAY *aArg
152
153	/**
154	* Expands to @c true if the given input safearray parameter is a "null pointer"
155	* which makes it impossible to use it for reading safearray data.
156	*/
157	#define ComSafeArrayInIsNull(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 input safearray parameters
162	* declared using the ComSafeArrayIn macro.
163	*
164	* @param aArg Parameter name to wrap. The given parameter must be declared
165	* within the calling function using the ComSafeArrayIn macro.
166	*/
167	#define ComSafeArrayInArg(aArg) aArg
168
169	/**
170	* Declares an output safearray parameter in the COM method implementation. Also
171	* used to declare the COM attribute getter parameter. Corresponds to either of
172	* the following XIDL definitions:
173	* <pre>
174	* <param name="arg" ... dir="out" safearray="yes"/>
175	* <param name="arg" ... dir="return" safearray="yes"/>
176	* ...
177	* <attribute name="arg" ... safearray="yes"/>
178	* </pre>
179	*
180	* The method implementation should use the com::SafeArray helper class to work
181	* with parameters declared using this define.
182	*
183	* @param aType Array element type.
184	* @param aArg Parameter/attribute name.
185	*/
186	#define ComSafeArrayOut(aType, aArg) SAFEARRAY **aArg
187
188	/**
189	* Expands to @c true if the given output safearray parameter is a "null
190	* pointer" which makes it impossible to use it for returning a safearray.
191	*/
192	#define ComSafeArrayOutIsNull(aArg) ((aArg) == NULL)
193
194	/**
195	* Wraps the given parameter name to generate an expression that is suitable for
196	* passing the parameter to functions that take output safearray parameters
197	* declared using the ComSafeArrayOut marco.
198	*
199	* @param aArg Parameter name to wrap. The given parameter must be declared
200	* within the calling function using the ComSafeArrayOut macro.
201	*/
202	#define ComSafeArrayOutArg(aArg) aArg
203
204	/**
205	* Version of ComSafeArrayIn for GUID.
206	* @param aArg Parameter name to wrap.
207	*/
208	#define ComSafeGUIDArrayIn(aArg) SAFEARRAY *aArg
209
210	/**
211	* Version of ComSafeArrayInIsNull for GUID.
212	* @param aArg Parameter name to wrap.
213	*/
214	#define ComSafeGUIDArrayInIsNull(aArg) ComSafeArrayInIsNull(aArg)
215
216	/**
217	* Version of ComSafeArrayInArg for GUID.
218	* @param aArg Parameter name to wrap.
219	*/
220	#define ComSafeGUIDArrayInArg(aArg) ComSafeArrayInArg(aArg)
221
222	/**
223	* Version of ComSafeArrayOut for GUID.
224	* @param aArg Parameter name to wrap.
225	*/
226	#define ComSafeGUIDArrayOut(aArg) SAFEARRAY **aArg
227
228	/**
229	* Version of ComSafeArrayOutIsNull for GUID.
230	* @param aArg Parameter name to wrap.
231	*/
232	#define ComSafeGUIDArrayOutIsNull(aArg) ComSafeArrayOutIsNull(aArg)
233
234	/**
235	* Version of ComSafeArrayOutArg for GUID.
236	* @param aArg Parameter name to wrap.
237	*/
238	#define ComSafeGUIDArrayOutArg(aArg) ComSafeArrayOutArg(aArg)
239
240	/**
241	* Gets size of safearray parameter.
242	* @param aArg Parameter name.
243	*/
244	#define ComSafeArraySize(aArg) ((aArg) == NULL ? 0 : (aArg)->rgsabound[0].cElements)
245
246	/**
247	* Returns the const reference to the IID (i.e., \|const GUID &\|) of the given
248	* interface.
249	*
250	* @param I interface class
251	*/
252	#define COM_IIDOF(I) _ATL_IIDOF(I)
253
254	/**
255	* For using interfaces before including the interface definitions. This will
256	* deal with XPCOM using 'class' and COM using 'struct' when defining
257	* interfaces.
258	*
259	* @param I interface name.
260	*/
261	#define COM_STRUCT_OR_CLASS(I) struct I
262
263	#else /* defined(RT_OS_WINDOWS) */
264
265	#error "VBOX_WITH_XPCOM must be defined on a platform other than Windows!"
266
267	#endif /* defined(RT_OS_WINDOWS) */
268
269	#else /* !defined(VBOX_WITH_XPCOM) */
270
271	// XPCOM
272	/////////////////////////////////////////////////////////////////////////////
273
274	#if defined(RT_OS_DARWIN) \|\| (defined(QT_VERSION) && (QT_VERSION >= 0x040000))
275	/* CFBase.h defines these &
276	* qglobal.h from Qt4 defines these */
277	# undef FALSE
278	# undef TRUE
279	#endif /* RT_OS_DARWIN \|\| QT_VERSION */
280
281	#include <nsID.h>
282
283	#define ATL_NO_VTABLE
284	#define DECLARE_CLASSFACTORY(a)
285	#define DECLARE_CLASSFACTORY_SINGLETON(a)
286	#define DECLARE_REGISTRY_RESOURCEID(a)
287	#define DECLARE_NOT_AGGREGATABLE(a)
288	#define DECLARE_PROTECT_FINAL_CONSTRUCT()
289	#define BEGIN_COM_MAP(a)
290	#define COM_INTERFACE_ENTRY(a)
291	#define COM_INTERFACE_ENTRY2(a,b)
292	#define END_COM_MAP() NS_DECL_ISUPPORTS
293	#define COM_INTERFACE_ENTRY_AGGREGATE(a,b)
294
295	#define HRESULT nsresult
296	#define SUCCEEDED NS_SUCCEEDED
297	#define FAILED NS_FAILED
298
299	#define SUCCEEDED_WARNING(rc) (NS_SUCCEEDED(rc) && (rc) != NS_OK)
300
301	#define FAILED_DEAD_INTERFACE(rc) ( (rc) == NS_ERROR_ABORT \
302	\|\| (rc) == NS_ERROR_CALL_FAILED \
303	)
304
305	#define IUnknown nsISupports
306
307	#define BOOL PRBool
308	#define BYTE PRUint8
309	#define SHORT PRInt16
310	#define USHORT PRUint16
311	#define LONG PRInt32
312	#define ULONG PRUint32
313	#define LONG64 PRInt64
314	#define ULONG64 PRUint64
315	/* XPCOM has only 64bit floats */
316	#define FLOAT PRFloat64
317	#define DOUBLE PRFloat64
318
319	#define FALSE PR_FALSE
320	#define TRUE PR_TRUE
321
322	#define OLECHAR wchar_t
323
324	/* note: typedef to semantically match BSTR on Win32 */
325	typedef PRUnichar *BSTR;
326	typedef const PRUnichar *CBSTR;
327	typedef BSTR *LPBSTR;
328
329	/** Input BSTR argument the interface method declaration. */
330	#define IN_BSTR CBSTR
331
332	/**
333	* Type to define a raw GUID variable (for members use the com::Guid class
334	* instead).
335	*/
336	#define GUID nsID
337	/** Input GUID argument the interface method declaration. */
338	#define IN_GUID const nsID &
339	/** Output GUID argument the interface method declaration. */
340	#define OUT_GUID nsID **
341
342	/** Makes the name of the getter interface function (n must be capitalized). */
343	#define COMGETTER(n) Get##n
344	/** Makes the name of the setter interface function (n must be capitalized). */
345	#define COMSETTER(n) Set##n
346
347	/* safearray input parameter macros */
348	#define ComSafeArrayIn(aType, aArg) PRUint32 aArg##Size, aType *aArg
349	#define ComSafeArrayInIsNull(aArg) ((aArg) == NULL)
350	#define ComSafeArrayInArg(aArg) aArg##Size, aArg
351
352	/* safearray output parameter macros */
353	#define ComSafeArrayOut(aType, aArg) PRUint32 aArg##Size, aType *aArg
354	#define ComSafeArrayOutIsNull(aArg) ((aArg) == NULL)
355	#define ComSafeArrayOutArg(aArg) aArg##Size, aArg
356
357	/* safearray input parameter macros for GUID */
358	#define ComSafeGUIDArrayIn(aArg) PRUint32 aArg##Size, const nsID **aArg
359	#define ComSafeGUIDArrayInIsNull(aArg) ComSafeArrayInIsNull(aArg)
360	#define ComSafeGUIDArrayInArg(aArg) ComSafeArrayInArg(aArg)
361
362	/* safearray output parameter macros for GUID */
363	#define ComSafeGUIDArrayOut(aArg) PRUint32 aArg##Size, nsID **aArg
364	#define ComSafeGUIDArrayOutIsNull(aArg) ComSafeArrayOutIsNull(aArg)
365	#define ComSafeGUIDArrayOutArg(aArg) ComSafeArrayOutArg(aArg)
366
367	/* safearray size */
368	#define ComSafeArraySize(aArg) ((aArg) == NULL ? 0 : (aArg##Size))
369
370	/* CLSID and IID for compatibility with Win32 */
371	typedef nsCID CLSID;
372	typedef nsIID IID;
373
374	/* OLE error codes */
375	#define S_OK ((nsresult)NS_OK)
376	#define E_UNEXPECTED NS_ERROR_UNEXPECTED
377	#define E_NOTIMPL NS_ERROR_NOT_IMPLEMENTED
378	#define E_OUTOFMEMORY NS_ERROR_OUT_OF_MEMORY
379	#define E_INVALIDARG NS_ERROR_INVALID_ARG
380	#define E_NOINTERFACE NS_ERROR_NO_INTERFACE
381	#define E_POINTER NS_ERROR_NULL_POINTER
382	#define E_ABORT NS_ERROR_ABORT
383	#define E_FAIL NS_ERROR_FAILURE
384	/* Note: a better analog for E_ACCESSDENIED would probably be
385	* NS_ERROR_NOT_AVAILABLE, but we want binary compatibility for now. */
386	#define E_ACCESSDENIED ((nsresult)0x80070005L)
387
388	#define STDMETHOD(a) NS_IMETHOD a
389	#define STDMETHODIMP NS_IMETHODIMP
390	#define STDMETHOD_(ret, meth) NS_IMETHOD_(ret) meth
391
392	#define COM_IIDOF(I) NS_GET_IID(I)
393
394	#define COM_STRUCT_OR_CLASS(I) class I
395
396	/* A few very simple ATL emulator classes to provide
397	* FinalConstruct()/FinalRelease() functionality on Linux. */
398
399	class CComMultiThreadModel
400	{
401	};
402
403	template <class Base> class CComObjectRootEx : public Base
404	{
405	public:
406	HRESULT FinalConstruct() { return S_OK; }
407	void FinalRelease() {}
408	};
409
410	template <class Base> class CComObject : public Base
411	{
412	public:
413	virtual ~CComObject() { this->FinalRelease(); }
414	};
415
416	/* helper functions */
417	extern "C"
418	{
419	BSTR SysAllocString(const OLECHAR* sz);
420	BSTR SysAllocStringByteLen(char *psz, unsigned int len);
421	BSTR SysAllocStringLen(const OLECHAR *pch, unsigned int cch);
422	void SysFreeString(BSTR bstr);
423	int SysReAllocString(BSTR pbstr, const OLECHAR psz);
424	int SysReAllocStringLen(BSTR pbstr, const OLECHAR psz, unsigned int cch);
425	unsigned int SysStringByteLen(BSTR bstr);
426	unsigned int SysStringLen(BSTR bstr);
427	}
428
429	/**
430	* 'Constructor' for the component class.
431	* This constructor, as opposed to NS_GENERIC_FACTORY_CONSTRUCTOR,
432	* assumes that the component class is derived from the CComObjectRootEx<>
433	* template, so it calls FinalConstruct() right after object creation
434	* and ensures that FinalRelease() will be called right before destruction.
435	* The result from FinalConstruct() is returned to the caller.
436	*/
437	#define NS_GENERIC_FACTORY_CONSTRUCTOR_WITH_RC(_InstanceClass) \
438	static NS_IMETHODIMP \
439	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
440	void **aResult) \
441	{ \
442	nsresult rv; \
443	\
444	*aResult = NULL; \
445	if (NULL != aOuter) { \
446	rv = NS_ERROR_NO_AGGREGATION; \
447	return rv; \
448	} \
449	\
450	CComObject <_InstanceClass> *inst = new CComObject <_InstanceClass>(); \
451	if (NULL == inst) { \
452	rv = NS_ERROR_OUT_OF_MEMORY; \
453	return rv; \
454	} \
455	\
456	NS_ADDREF(inst); /* protect FinalConstruct() */ \
457	rv = inst->FinalConstruct(); \
458	if (NS_SUCCEEDED(rv)) \
459	rv = inst->QueryInterface(aIID, aResult); \
460	NS_RELEASE(inst); \
461	\
462	return rv; \
463	}
464
465	/**
466	* 'Constructor' that uses an existing getter function that gets a singleton.
467	* The getter function must have the following prototype:
468	* nsresult _GetterProc(_InstanceClass **inst)
469	* This constructor, as opposed to NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR,
470	* lets the getter function return a result code that is passed back to the
471	* caller that tries to instantiate the object.
472	* NOTE: assumes that getter does an AddRef - so additional AddRef is not done.
473	*/
474	#define NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR_WITH_RC(_InstanceClass, _GetterProc) \
475	static NS_IMETHODIMP \
476	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
477	void **aResult) \
478	{ \
479	nsresult rv; \
480	\
481	_InstanceClass * inst = NULL; /* initialized to shut up gcc */ \
482	\
483	*aResult = NULL; \
484	if (NULL != aOuter) { \
485	rv = NS_ERROR_NO_AGGREGATION; \
486	return rv; \
487	} \
488	\
489	rv = _GetterProc(&inst); \
490	if (NS_FAILED(rv)) \
491	return rv; \
492	\
493	/* sanity check */ \
494	if (NULL == inst) \
495	return NS_ERROR_OUT_OF_MEMORY; \
496	\
497	/* NS_ADDREF(inst); */ \
498	if (NS_SUCCEEDED(rv)) { \
499	rv = inst->QueryInterface(aIID, aResult); \
500	} \
501	NS_RELEASE(inst); \
502	\
503	return rv; \
504	}
505
506	#endif /* !defined(VBOX_WITH_XPCOM) */
507
508	/**
509	* Declares a wchar_t string literal from the argument.
510	* Necessary to overcome MSC / GCC differences.
511	* @param s expression to stringify
512	*/
513	#if defined(_MSC_VER)
514	# define WSTR_LITERAL(s) L#s
515	#elif defined(__GNUC__)
516	# define WSTR_LITERAL(s) L""#s
517	#else
518	# error "Unsupported compiler!"
519	#endif
520
521	namespace com
522	{
523
524	// use this macro to implement scriptable interfaces
525	#ifdef RT_OS_WINDOWS
526	#define VBOX_SCRIPTABLE_IMPL(iface) \
527	public IDispatchImpl<iface, &IID_##iface, &LIBID_VirtualBox, \
528	kTypeLibraryMajorVersion, kTypeLibraryMinorVersion>
529
530	#define VBOX_SCRIPTABLE_DISPATCH_IMPL(iface) \
531	STDMETHOD(QueryInterface)(REFIID riid , void **ppObj) \
532	{ \
533	if (riid == IID_##iface) \
534	{ \
535	ppObj = (iface)this; \
536	AddRef(); \
537	return S_OK; \
538	} \
539	if (riid == IID_IUnknown) \
540	{ \
541	ppObj = (IUnknown)this; \
542	AddRef(); \
543	return S_OK; \
544	} \
545	if (riid == IID_IDispatch) \
546	{ \
547	ppObj = (IDispatch)this; \
548	AddRef(); \
549	return S_OK; \
550	} \
551	*ppObj = NULL; \
552	return E_NOINTERFACE; \
553	}
554
555
556	#define VBOX_DEFAULT_INTERFACE_ENTRIES(iface) \
557	COM_INTERFACE_ENTRY(ISupportErrorInfo) \
558	COM_INTERFACE_ENTRY(iface) \
559	COM_INTERFACE_ENTRY2(IDispatch,iface) \
560	COM_INTERFACE_ENTRY_AGGREGATE(IID_IMarshal, m_pUnkMarshaler.p)
561	#else
562	#define VBOX_SCRIPTABLE_IMPL(iface) \
563	public iface
564	#define VBOX_SCRIPTABLE_DISPATCH_IMPL(iface)
565	#define VBOX_DEFAULT_INTERFACE_ENTRIES(iface)
566	#endif
567
568
569	} /* namespace com */
570
571	/** @} */
572
573	#endif /* !___VBox_com_defs_h */
574

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

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

Download in other formats: