defs.h@ 69107

Last change on this file since 69107 was 69107, checked in by vboxsync, 7 years ago
include/VBox/: (C) year
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
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	#ifdef RT_OS_WINDOWS
78
79	// Windows COM
80	/////////////////////////////////////////////////////////////////////////////
81
82	# include <iprt/win/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	* Apply RT_NOREF_PV to a safearray parameter.
247	* @param aArg Parameter name.
248	*/
249	#define ComSafeArrayNoRef(aArg) RT_NOREF_PV(aArg)
250
251	/**
252	* Returns the const reference to the IID (i.e., \|const GUID &\|) of the given
253	* interface.
254	*
255	* @param I interface class
256	*/
257	#define COM_IIDOF(I) __uuidof(I)
258
259	/**
260	* For using interfaces before including the interface definitions. This will
261	* deal with XPCOM using 'class' and COM using 'struct' when defining
262	* interfaces.
263	*
264	* @param I interface name.
265	*/
266	#define COM_STRUCT_OR_CLASS(I) struct I
267
268	#else /* defined(RT_OS_WINDOWS) */
269
270	#error "VBOX_WITH_XPCOM must be defined on a platform other than Windows!"
271
272	#endif /* defined(RT_OS_WINDOWS) */
273
274	#else /* !defined(VBOX_WITH_XPCOM) */
275
276	// XPCOM
277	/////////////////////////////////////////////////////////////////////////////
278
279	#if defined(RT_OS_DARWIN) \|\| (defined(QT_VERSION) && (QT_VERSION >= 0x040000))
280	/* CFBase.h defines these &
281	* qglobal.h from Qt4 defines these */
282	# undef FALSE
283	# undef TRUE
284	#endif /* RT_OS_DARWIN \|\| QT_VERSION */
285
286	#include <nsID.h>
287
288	#define HRESULT nsresult
289	#define SUCCEEDED NS_SUCCEEDED
290	#define FAILED NS_FAILED
291
292	#define SUCCEEDED_WARNING(rc) (NS_SUCCEEDED(rc) && (rc) != NS_OK)
293
294	#define FAILED_DEAD_INTERFACE(rc) ( (rc) == NS_ERROR_ABORT \
295	\|\| (rc) == NS_ERROR_CALL_FAILED \
296	)
297
298	#define IUnknown nsISupports
299
300	#define BOOL PRBool
301	#define BYTE PRUint8
302	#define SHORT PRInt16
303	#define USHORT PRUint16
304	#define LONG PRInt32
305	#define ULONG PRUint32
306	#define LONG64 PRInt64
307	#define ULONG64 PRUint64
308	/* XPCOM has only 64bit floats */
309	#define FLOAT PRFloat64
310	#define DOUBLE PRFloat64
311
312	#define FALSE PR_FALSE
313	#define TRUE PR_TRUE
314
315	#define OLECHAR wchar_t
316
317	/* note: typedef to semantically match BSTR on Win32 */
318	typedef PRUnichar *BSTR;
319	typedef const PRUnichar *CBSTR;
320	typedef BSTR *LPBSTR;
321
322	/** Input BSTR argument the interface method declaration. */
323	#define IN_BSTR CBSTR
324
325	/**
326	* Type to define a raw GUID variable (for members use the com::Guid class
327	* instead).
328	*/
329	#define GUID nsID
330	/** Input GUID argument the interface method declaration. */
331	#define IN_GUID const nsID &
332	/** Output GUID argument the interface method declaration. */
333	#define OUT_GUID nsID **
334
335	/** Makes the name of the getter interface function (n must be capitalized). */
336	#define COMGETTER(n) Get##n
337	/** Makes the name of the setter interface function (n must be capitalized). */
338	#define COMSETTER(n) Set##n
339
340	/* safearray input parameter macros */
341	#define ComSafeArrayIn(aType, aArg) PRUint32 aArg##Size, aType *aArg
342	#define ComSafeArrayInIsNull(aArg) ((aArg) == NULL)
343	#define ComSafeArrayInArg(aArg) aArg##Size, aArg
344
345	/* safearray output parameter macros */
346	#define ComSafeArrayOut(aType, aArg) PRUint32 aArg##Size, aType *aArg
347	#define ComSafeArrayOutIsNull(aArg) ((aArg) == NULL)
348	#define ComSafeArrayOutArg(aArg) aArg##Size, aArg
349
350	/* safearray input parameter macros for GUID */
351	#define ComSafeGUIDArrayIn(aArg) PRUint32 aArg##Size, const nsID **aArg
352	#define ComSafeGUIDArrayInIsNull(aArg) ComSafeArrayInIsNull(aArg)
353	#define ComSafeGUIDArrayInArg(aArg) ComSafeArrayInArg(aArg)
354
355	/* safearray output parameter macros for GUID */
356	#define ComSafeGUIDArrayOut(aArg) PRUint32 aArg##Size, nsID **aArg
357	#define ComSafeGUIDArrayOutIsNull(aArg) ComSafeArrayOutIsNull(aArg)
358	#define ComSafeGUIDArrayOutArg(aArg) ComSafeArrayOutArg(aArg)
359
360	/** safearray size */
361	#define ComSafeArraySize(aArg) ((aArg) == NULL ? 0 : (aArg##Size))
362
363	/** NOREF a COM safe array argument. */
364	#define ComSafeArrayNoRef(aArg) RT_NOREF2(aArg, aArg##Size)
365
366	/* CLSID and IID for compatibility with Win32 */
367	typedef nsCID CLSID;
368	typedef nsIID IID;
369
370	/* OLE error codes */
371	#define S_OK ((nsresult)NS_OK)
372	#define E_UNEXPECTED NS_ERROR_UNEXPECTED
373	#define E_NOTIMPL NS_ERROR_NOT_IMPLEMENTED
374	#define E_OUTOFMEMORY NS_ERROR_OUT_OF_MEMORY
375	#define E_INVALIDARG NS_ERROR_INVALID_ARG
376	#define E_NOINTERFACE NS_ERROR_NO_INTERFACE
377	#define E_POINTER NS_ERROR_NULL_POINTER
378	#define E_ABORT NS_ERROR_ABORT
379	#define E_FAIL NS_ERROR_FAILURE
380	/* Note: a better analog for E_ACCESSDENIED would probably be
381	* NS_ERROR_NOT_AVAILABLE, but we want binary compatibility for now. */
382	#define E_ACCESSDENIED ((nsresult)0x80070005L)
383
384	#define STDMETHOD(a) NS_IMETHOD a
385	#define STDMETHODIMP NS_IMETHODIMP
386	#define STDMETHOD_(ret, meth) NS_IMETHOD_(ret) meth
387
388	#define COM_IIDOF(I) NS_GET_IID(I)
389
390	#define COM_STRUCT_OR_CLASS(I) class I
391
392	/* helper functions */
393	extern "C"
394	{
395	BSTR SysAllocString(const OLECHAR *sz);
396	BSTR SysAllocStringByteLen(char *psz, unsigned int len);
397	BSTR SysAllocStringLen(const OLECHAR *pch, unsigned int cch);
398	void SysFreeString(BSTR bstr);
399	int SysReAllocString(BSTR pbstr, const OLECHAR psz);
400	int SysReAllocStringLen(BSTR pbstr, const OLECHAR psz, unsigned int cch);
401	unsigned int SysStringByteLen(BSTR bstr);
402	unsigned int SysStringLen(BSTR bstr);
403	}
404
405	#ifndef VBOX_COM_NO_ATL
406
407	namespace ATL
408	{
409
410	#define ATL_NO_VTABLE
411	#define DECLARE_CLASSFACTORY(a)
412	#define DECLARE_CLASSFACTORY_SINGLETON(a)
413	#define DECLARE_REGISTRY_RESOURCEID(a)
414	#define DECLARE_NOT_AGGREGATABLE(a)
415	#define DECLARE_PROTECT_FINAL_CONSTRUCT()
416	#define BEGIN_COM_MAP(a)
417	#define COM_INTERFACE_ENTRY(a)
418	#define COM_INTERFACE_ENTRY2(a,b)
419	#define END_COM_MAP() NS_DECL_ISUPPORTS
420	#define COM_INTERFACE_ENTRY_AGGREGATE(a,b)
421
422	/* A few very simple ATL emulator classes to provide
423	* FinalConstruct()/FinalRelease() functionality with XPCOM. */
424
425	class CComMultiThreadModel
426	{
427	};
428
429	template <class DummyThreadModel> class CComObjectRootEx
430	{
431	public:
432	HRESULT FinalConstruct()
433	{
434	return S_OK;
435	}
436	void FinalRelease()
437	{
438	}
439	};
440
441	template <class Base> class CComObject : public Base
442	{
443	public:
444	virtual ~CComObject() { this->FinalRelease(); }
445	};
446
447	} /* namespace ATL */
448
449
450	/**
451	* 'Constructor' for the component class.
452	* This constructor, as opposed to NS_GENERIC_FACTORY_CONSTRUCTOR,
453	* assumes that the component class is derived from the CComObjectRootEx<>
454	* template, so it calls FinalConstruct() right after object creation
455	* and ensures that FinalRelease() will be called right before destruction.
456	* The result from FinalConstruct() is returned to the caller.
457	*/
458	#define NS_GENERIC_FACTORY_CONSTRUCTOR_WITH_RC(_InstanceClass) \
459	static NS_IMETHODIMP \
460	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
461	void **aResult) \
462	{ \
463	nsresult rv; \
464	\
465	*aResult = NULL; \
466	if (NULL != aOuter) { \
467	rv = NS_ERROR_NO_AGGREGATION; \
468	return rv; \
469	} \
470	\
471	ATL::CComObject<_InstanceClass> *inst = new ATL::CComObject<_InstanceClass>(); \
472	if (NULL == inst) { \
473	rv = NS_ERROR_OUT_OF_MEMORY; \
474	return rv; \
475	} \
476	\
477	NS_ADDREF(inst); /* protect FinalConstruct() */ \
478	rv = inst->FinalConstruct(); \
479	if (NS_SUCCEEDED(rv)) \
480	rv = inst->QueryInterface(aIID, aResult); \
481	NS_RELEASE(inst); \
482	\
483	return rv; \
484	}
485
486	/**
487	* 'Constructor' that uses an existing getter function that gets a singleton.
488	* The getter function must have the following prototype:
489	* nsresult _GetterProc(_InstanceClass **inst)
490	* This constructor, as opposed to NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR,
491	* lets the getter function return a result code that is passed back to the
492	* caller that tries to instantiate the object.
493	* NOTE: assumes that getter does an AddRef - so additional AddRef is not done.
494	*/
495	#define NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR_WITH_RC(_InstanceClass, _GetterProc) \
496	static NS_IMETHODIMP \
497	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
498	void **aResult) \
499	{ \
500	nsresult rv; \
501	\
502	_InstanceClass inst = NULL; / initialized to shut up gcc */ \
503	\
504	*aResult = NULL; \
505	if (NULL != aOuter) { \
506	rv = NS_ERROR_NO_AGGREGATION; \
507	return rv; \
508	} \
509	\
510	rv = _GetterProc(&inst); \
511	if (NS_FAILED(rv)) \
512	return rv; \
513	\
514	/* sanity check */ \
515	if (NULL == inst) \
516	return NS_ERROR_OUT_OF_MEMORY; \
517	\
518	/* NS_ADDREF(inst); */ \
519	if (NS_SUCCEEDED(rv)) { \
520	rv = inst->QueryInterface(aIID, aResult); \
521	} \
522	NS_RELEASE(inst); \
523	\
524	return rv; \
525	}
526
527	#endif /* !VBOX_COM_NO_ATL */
528
529	#endif /* !defined(VBOX_WITH_XPCOM) */
530
531	/**
532	* Declares a wchar_t string literal from the argument.
533	* Necessary to overcome MSC / GCC differences.
534	* @param s expression to stringify
535	*/
536	#if defined(_MSC_VER)
537	# define WSTR_LITERAL(s) L#s
538	#elif defined(__GNUC__)
539	# define WSTR_LITERAL(s) L""#s
540	#else
541	# error "Unsupported compiler!"
542	#endif
543
544	namespace com
545	{
546
547	#ifndef VBOX_COM_NO_ATL
548
549	// use this macro to implement scriptable interfaces
550	#ifdef RT_OS_WINDOWS
551	#define VBOX_SCRIPTABLE_IMPL(iface) \
552	public ATL::IDispatchImpl<iface, &IID_##iface, &LIBID_VirtualBox, \
553	kTypeLibraryMajorVersion, kTypeLibraryMinorVersion>
554
555	#define VBOX_SCRIPTABLE_DISPATCH_IMPL(iface) \
556	STDMETHOD(QueryInterface)(REFIID riid, void **ppObj) \
557	{ \
558	if (riid == IID_##iface) \
559	{ \
560	ppObj = (iface )this; \
561	AddRef(); \
562	return S_OK; \
563	} \
564	if (riid == IID_IUnknown) \
565	{ \
566	ppObj = (IUnknown )this; \
567	AddRef(); \
568	return S_OK; \
569	} \
570	if (riid == IID_IDispatch) \
571	{ \
572	ppObj = (IDispatch )this; \
573	AddRef(); \
574	return S_OK; \
575	} \
576	*ppObj = NULL; \
577	return E_NOINTERFACE; \
578	}
579	#else
580	#define VBOX_SCRIPTABLE_IMPL(iface) \
581	public iface
582	#define VBOX_SCRIPTABLE_DISPATCH_IMPL(iface)
583	#endif
584
585	#endif /* !VBOX_COM_NO_ATL */
586
587	} /* namespace com */
588
589	/** @} */
590
591	#endif /* !___VBox_com_defs_h */
592

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

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

Download in other formats: