defs.h@ 76507

Last change on this file since 76507 was 76507, checked in by vboxsync, 6 years ago
/include: scm --fix-header-guards. bugref:9344
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 21.7 KB

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

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

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

Download in other formats: