defs.h@ 61383

Last change on this file since 61383 was 60766, checked in by vboxsync, 9 years ago
Main: XPCOM build fix for previous big change
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 21.4 KB

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

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

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

Download in other formats: