defs.h@ 93115

Last change on this file since 93115 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 21.8 KB

Line
1	/** @file
2	* MS COM / XPCOM Abstraction Layer - Common Definitions.
3	*/
4
5	/*
6	* Copyright (C) 2006-2022 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_INCLUDED_com_defs_h
27	#define VBOX_INCLUDED_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 S_FALSE ((nsresult)1)
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	/* helper functions */
397	extern "C"
398	{
399	BSTR SysAllocString(const OLECHAR *sz);
400	BSTR SysAllocStringByteLen(char const *psz, unsigned int len);
401	BSTR SysAllocStringLen(const OLECHAR *pch, unsigned int cch);
402	void SysFreeString(BSTR bstr);
403	int SysReAllocString(BSTR pbstr, const OLECHAR psz);
404	int SysReAllocStringLen(BSTR pbstr, const OLECHAR psz, unsigned int cch);
405	unsigned int SysStringByteLen(BSTR bstr);
406	unsigned int SysStringLen(BSTR bstr);
407	}
408
409	#ifndef VBOX_COM_NO_ATL
410
411	namespace ATL
412	{
413
414	#define ATL_NO_VTABLE
415	#define DECLARE_CLASSFACTORY(a)
416	#define DECLARE_CLASSFACTORY_SINGLETON(a)
417	#define DECLARE_REGISTRY_RESOURCEID(a)
418	#define DECLARE_NOT_AGGREGATABLE(a)
419	#define DECLARE_PROTECT_FINAL_CONSTRUCT()
420	#define BEGIN_COM_MAP(a)
421	#define COM_INTERFACE_ENTRY(a)
422	#define COM_INTERFACE_ENTRY2(a,b)
423	#define END_COM_MAP() NS_DECL_ISUPPORTS
424	#define COM_INTERFACE_ENTRY_AGGREGATE(a,b)
425
426	/* A few very simple ATL emulator classes to provide
427	* FinalConstruct()/FinalRelease() functionality with XPCOM. */
428
429	class CComMultiThreadModel
430	{
431	};
432
433	template <class DummyThreadModel> class CComObjectRootEx
434	{
435	public:
436	HRESULT FinalConstruct()
437	{
438	return S_OK;
439	}
440	void FinalRelease()
441	{
442	}
443	};
444
445	template <class Base> class CComObject : public Base
446	{
447	public:
448	virtual ~CComObject() { this->FinalRelease(); }
449	};
450
451	} /* namespace ATL */
452
453
454	/**
455	* 'Constructor' for the component class.
456	* This constructor, as opposed to NS_GENERIC_FACTORY_CONSTRUCTOR,
457	* assumes that the component class is derived from the CComObjectRootEx<>
458	* template, so it calls FinalConstruct() right after object creation
459	* and ensures that FinalRelease() will be called right before destruction.
460	* The result from FinalConstruct() is returned to the caller.
461	*/
462	#define NS_GENERIC_FACTORY_CONSTRUCTOR_WITH_RC(_InstanceClass) \
463	static NS_IMETHODIMP \
464	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
465	void **aResult) \
466	{ \
467	nsresult rv; \
468	\
469	*aResult = NULL; \
470	if (NULL != aOuter) { \
471	rv = NS_ERROR_NO_AGGREGATION; \
472	return rv; \
473	} \
474	\
475	ATL::CComObject<_InstanceClass> *inst = new ATL::CComObject<_InstanceClass>(); \
476	if (NULL == inst) { \
477	rv = NS_ERROR_OUT_OF_MEMORY; \
478	return rv; \
479	} \
480	\
481	NS_ADDREF(inst); /* protect FinalConstruct() */ \
482	rv = inst->FinalConstruct(); \
483	if (NS_SUCCEEDED(rv)) \
484	rv = inst->QueryInterface(aIID, aResult); \
485	NS_RELEASE(inst); \
486	\
487	return rv; \
488	}
489
490	/**
491	* 'Constructor' that uses an existing getter function that gets a singleton.
492	* The getter function must have the following prototype:
493	* nsresult _GetterProc(_InstanceClass **inst)
494	* This constructor, as opposed to NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR,
495	* lets the getter function return a result code that is passed back to the
496	* caller that tries to instantiate the object.
497	* NOTE: assumes that getter does an AddRef - so additional AddRef is not done.
498	*/
499	#define NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR_WITH_RC(_InstanceClass, _GetterProc) \
500	static NS_IMETHODIMP \
501	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
502	void **aResult) \
503	{ \
504	nsresult rv; \
505	\
506	_InstanceClass inst = NULL; / initialized to shut up gcc */ \
507	\
508	*aResult = NULL; \
509	if (NULL != aOuter) { \
510	rv = NS_ERROR_NO_AGGREGATION; \
511	return rv; \
512	} \
513	\
514	rv = _GetterProc(&inst); \
515	if (NS_FAILED(rv)) \
516	return rv; \
517	\
518	/* sanity check */ \
519	if (NULL == inst) \
520	return NS_ERROR_OUT_OF_MEMORY; \
521	\
522	/* NS_ADDREF(inst); */ \
523	if (NS_SUCCEEDED(rv)) { \
524	rv = inst->QueryInterface(aIID, aResult); \
525	} \
526	NS_RELEASE(inst); \
527	\
528	return rv; \
529	}
530
531	#endif /* !VBOX_COM_NO_ATL */
532
533	#endif /* !defined(VBOX_WITH_XPCOM) */
534
535	/**
536	* Declares a wchar_t string literal from the argument.
537	* Necessary to overcome MSC / GCC differences.
538	* @param s expression to stringify
539	*/
540	#if defined(_MSC_VER)
541	# define WSTR_LITERAL(s) L#s
542	#elif defined(__GNUC__)
543	# define WSTR_LITERAL(s) L""#s
544	#else
545	# error "Unsupported compiler!"
546	#endif
547
548	namespace com
549	{
550
551	#ifndef VBOX_COM_NO_ATL
552
553	// use this macro to implement scriptable interfaces
554	#ifdef RT_OS_WINDOWS
555	#define VBOX_SCRIPTABLE_IMPL(iface) \
556	public ATL::IDispatchImpl<iface, &IID_##iface, &LIBID_VirtualBox, \
557	kTypeLibraryMajorVersion, kTypeLibraryMinorVersion>
558
559	#define VBOX_SCRIPTABLE_DISPATCH_IMPL(iface) \
560	STDMETHOD(QueryInterface)(REFIID riid, void **ppObj) \
561	{ \
562	if (riid == IID_##iface) \
563	{ \
564	ppObj = (iface )this; \
565	AddRef(); \
566	return S_OK; \
567	} \
568	if (riid == IID_IUnknown) \
569	{ \
570	ppObj = (IUnknown )this; \
571	AddRef(); \
572	return S_OK; \
573	} \
574	if (riid == IID_IDispatch) \
575	{ \
576	ppObj = (IDispatch )this; \
577	AddRef(); \
578	return S_OK; \
579	} \
580	*ppObj = NULL; \
581	return E_NOINTERFACE; \
582	}
583	#else
584	#define VBOX_SCRIPTABLE_IMPL(iface) \
585	public iface
586	#define VBOX_SCRIPTABLE_DISPATCH_IMPL(iface)
587	#endif
588
589	#endif /* !VBOX_COM_NO_ATL */
590
591	} /* namespace com */
592
593	/** @} */
594
595	#endif /* !VBOX_INCLUDED_com_defs_h */
596

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

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

Download in other formats: