defs.h@ 56291

Last change on this file since 56291 was 56291, checked in by vboxsync, 9 years ago
include: Updated (C) year.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 21.5 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	#if !defined(VBOX_WITH_XPCOM)
69
70	#if defined(RT_OS_WINDOWS)
71
72	// Windows COM
73	/////////////////////////////////////////////////////////////////////////////
74
75	#include <objbase.h>
76	#ifndef VBOX_COM_NO_ATL
77	# define _ATL_FREE_THREADED
78
79	# include <atlbase.h>
80	#include <atlcom.h>
81	#endif
82
83	#define NS_DECL_ISUPPORTS
84	#define NS_IMPL_ISUPPORTS1_CI(a, b)
85
86	/* these are XPCOM only, one for every interface implemented */
87	#define NS_DECL_ISUPPORTS
88
89	/** Returns @c true if @a rc represents a warning result code */
90	#define SUCCEEDED_WARNING(rc) (SUCCEEDED(rc) && (rc) != S_OK)
91
92	/** Tests is a COM result code indicates that the process implementing the
93	* interface is dead.
94	*
95	* COM status codes:
96	* 0x800706ba - RPC_S_SERVER_UNAVAILABLE. Killed before call was made.
97	* 0x800706be - RPC_S_CALL_FAILED. Killed after call was made.
98	* 0x800706bf - RPC_S_CALL_FAILED_DNE. Not observed, but should be
99	* matter of timing.
100	* 0x80010108 - RPC_E_DISCONNECTED. Observed deregistering
101	* python event listener.
102	* 0x800706b5 - RPC_S_UNKNOWN_IF. Observed deregistering python
103	* event listener
104	*/
105	#define FAILED_DEAD_INTERFACE(rc) \
106	( (rc) == HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) \
107	\|\| (rc) == HRESULT_FROM_WIN32(RPC_S_CALL_FAILED) \
108	\|\| (rc) == HRESULT_FROM_WIN32(RPC_S_CALL_FAILED_DNE) \
109	\|\| (rc) == RPC_E_DISCONNECTED \
110	)
111
112	/** Immutable BSTR string */
113	typedef const OLECHAR *CBSTR;
114
115	/** Input BSTR argument of interface method declaration. */
116	#define IN_BSTR BSTR
117
118	/** Input GUID argument of interface method declaration. */
119	#define IN_GUID GUID
120	/** Output GUID argument of interface method declaration. */
121	#define OUT_GUID GUID*
122
123	/** Makes the name of the getter interface function (n must be capitalized). */
124	#define COMGETTER(n) get_##n
125	/** Makes the name of the setter interface function (n must be capitalized). */
126	#define COMSETTER(n) put_##n
127
128	/**
129	* Declares an input safearray parameter in the COM method implementation. Also
130	* used to declare the COM attribute setter parameter. Corresponds to either of
131	* the following XIDL definitions:
132	* <pre>
133	* <param name="arg" ... dir="in" safearray="yes"/>
134	* ...
135	* <attribute name="arg" ... safearray="yes"/>
136	* </pre>
137	*
138	* The method implementation should use the com::SafeArray helper class to work
139	* with parameters declared using this define.
140	*
141	* @param aType Array element type.
142	* @param aArg Parameter/attribute name.
143	*/
144	#define ComSafeArrayIn(aType, aArg) SAFEARRAY *aArg
145
146	/**
147	* Expands to @true if the given input safearray parameter is a "null pointer"
148	* which makes it impossible to use it for reading safearray data.
149	*/
150	#define ComSafeArrayInIsNull(aArg) ((aArg) == NULL)
151
152	/**
153	* Wraps the given parameter name to generate an expression that is suitable for
154	* passing the parameter to functions that take input safearray parameters
155	* declared using the ComSafeArrayIn macro.
156	*
157	* @param aArg Parameter name to wrap. The given parameter must be declared
158	* within the calling function using the ComSafeArrayIn macro.
159	*/
160	#define ComSafeArrayInArg(aArg) aArg
161
162	/**
163	* Declares an output safearray parameter in the COM method implementation. Also
164	* used to declare the COM attribute getter parameter. Corresponds to either of
165	* the following XIDL definitions:
166	* <pre>
167	* <param name="arg" ... dir="out" safearray="yes"/>
168	* <param name="arg" ... dir="return" safearray="yes"/>
169	* ...
170	* <attribute name="arg" ... safearray="yes"/>
171	* </pre>
172	*
173	* The method implementation should use the com::SafeArray helper class to work
174	* with parameters declared using this define.
175	*
176	* @param aType Array element type.
177	* @param aArg Parameter/attribute name.
178	*/
179	#define ComSafeArrayOut(aType, aArg) SAFEARRAY **aArg
180
181	/**
182	* Expands to @true if the given output safearray parameter is a "null pointer"
183	* which makes it impossible to use it for returning a safearray.
184	*/
185	#define ComSafeArrayOutIsNull(aArg) ((aArg) == NULL)
186
187	/**
188	* Wraps the given parameter name to generate an expression that is suitable for
189	* passing the parameter to functions that take output safearray parameters
190	* declared using the ComSafeArrayOut marco.
191	*
192	* @param aArg Parameter name to wrap. The given parameter must be declared
193	* within the calling function using the ComSafeArrayOut macro.
194	*/
195	#define ComSafeArrayOutArg(aArg) aArg
196
197	/**
198	* Version of ComSafeArrayIn for GUID.
199	* @param aArg Parameter name to wrap.
200	*/
201	#define ComSafeGUIDArrayIn(aArg) SAFEARRAY *aArg
202
203	/**
204	* Version of ComSafeArrayInIsNull for GUID.
205	* @param aArg Parameter name to wrap.
206	*/
207	#define ComSafeGUIDArrayInIsNull(aArg) ComSafeArrayInIsNull(aArg)
208
209	/**
210	* Version of ComSafeArrayInArg for GUID.
211	* @param aArg Parameter name to wrap.
212	*/
213	#define ComSafeGUIDArrayInArg(aArg) ComSafeArrayInArg(aArg)
214
215	/**
216	* Version of ComSafeArrayOut for GUID.
217	* @param aArg Parameter name to wrap.
218	*/
219	#define ComSafeGUIDArrayOut(aArg) SAFEARRAY **aArg
220
221	/**
222	* Version of ComSafeArrayOutIsNull for GUID.
223	* @param aArg Parameter name to wrap.
224	*/
225	#define ComSafeGUIDArrayOutIsNull(aArg) ComSafeArrayOutIsNull(aArg)
226
227	/**
228	* Version of ComSafeArrayOutArg for GUID.
229	* @param aArg Parameter name to wrap.
230	*/
231	#define ComSafeGUIDArrayOutArg(aArg) ComSafeArrayOutArg(aArg)
232
233	/**
234	* Gets size of safearray parameter.
235	* @param aArg Parameter name.
236	*/
237	#define ComSafeArraySize(aArg) ((aArg) == NULL ? 0 : (aArg)->rgsabound[0].cElements)
238
239	/**
240	* Returns the const reference to the IID (i.e., \|const GUID &\|) of the given
241	* interface.
242	*
243	* @param i interface class
244	*/
245	#define COM_IIDOF(I) _ATL_IIDOF(I)
246
247	/**
248	* For using interfaces before including the interface definitions. This will
249	* deal with XPCOM using 'class' and COM using 'struct' when defining
250	* interfaces.
251	*
252	* @param I interface name.
253	*/
254	#define COM_STRUCT_OR_CLASS(I) struct I
255
256	#else /* defined(RT_OS_WINDOWS) */
257
258	#error "VBOX_WITH_XPCOM must be defined on a platform other than Windows!"
259
260	#endif /* defined(RT_OS_WINDOWS) */
261
262	#else /* !defined(VBOX_WITH_XPCOM) */
263
264	// XPCOM
265	/////////////////////////////////////////////////////////////////////////////
266
267	#if defined(RT_OS_DARWIN) \|\| (defined(QT_VERSION) && (QT_VERSION >= 0x040000))
268	/* CFBase.h defines these &
269	* qglobal.h from Qt4 defines these */
270	# undef FALSE
271	# undef TRUE
272	#endif /* RT_OS_DARWIN \|\| QT_VERSION */
273
274	#include <nsID.h>
275
276	#define ATL_NO_VTABLE
277	#define DECLARE_CLASSFACTORY(a)
278	#define DECLARE_CLASSFACTORY_SINGLETON(a)
279	#define DECLARE_REGISTRY_RESOURCEID(a)
280	#define DECLARE_NOT_AGGREGATABLE(a)
281	#define DECLARE_PROTECT_FINAL_CONSTRUCT()
282	#define BEGIN_COM_MAP(a)
283	#define COM_INTERFACE_ENTRY(a)
284	#define COM_INTERFACE_ENTRY2(a,b)
285	#define END_COM_MAP() NS_DECL_ISUPPORTS
286	#define COM_INTERFACE_ENTRY_AGGREGATE(a,b)
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	/* CLSID and IID for compatibility with Win32 */
364	typedef nsCID CLSID;
365	typedef nsIID IID;
366
367	/* OLE error codes */
368	#define S_OK ((nsresult)NS_OK)
369	#define E_UNEXPECTED NS_ERROR_UNEXPECTED
370	#define E_NOTIMPL NS_ERROR_NOT_IMPLEMENTED
371	#define E_OUTOFMEMORY NS_ERROR_OUT_OF_MEMORY
372	#define E_INVALIDARG NS_ERROR_INVALID_ARG
373	#define E_NOINTERFACE NS_ERROR_NO_INTERFACE
374	#define E_POINTER NS_ERROR_NULL_POINTER
375	#define E_ABORT NS_ERROR_ABORT
376	#define E_FAIL NS_ERROR_FAILURE
377	/* Note: a better analog for E_ACCESSDENIED would probably be
378	* NS_ERROR_NOT_AVAILABLE, but we want binary compatibility for now. */
379	#define E_ACCESSDENIED ((nsresult)0x80070005L)
380
381	#define STDMETHOD(a) NS_IMETHOD a
382	#define STDMETHODIMP NS_IMETHODIMP
383	#define STDMETHOD_(ret, meth) NS_IMETHOD_(ret) meth
384
385	#define COM_IIDOF(I) NS_GET_IID(I)
386
387	#define COM_STRUCT_OR_CLASS(I) class I
388
389	/* A few very simple ATL emulator classes to provide
390	* FinalConstruct()/FinalRelease() functionality on Linux. */
391
392	class CComMultiThreadModel
393	{
394	};
395
396	template <class Base> class CComObjectRootEx : public Base
397	{
398	public:
399	HRESULT FinalConstruct() { return S_OK; }
400	void FinalRelease() {}
401	};
402
403	template <class Base> class CComObject : public Base
404	{
405	public:
406	virtual ~CComObject() { this->FinalRelease(); }
407	};
408
409	/* helper functions */
410	extern "C"
411	{
412	BSTR SysAllocString(const OLECHAR* sz);
413	BSTR SysAllocStringByteLen(char *psz, unsigned int len);
414	BSTR SysAllocStringLen(const OLECHAR *pch, unsigned int cch);
415	void SysFreeString(BSTR bstr);
416	int SysReAllocString(BSTR pbstr, const OLECHAR psz);
417	int SysReAllocStringLen(BSTR pbstr, const OLECHAR psz, unsigned int cch);
418	unsigned int SysStringByteLen(BSTR bstr);
419	unsigned int SysStringLen(BSTR bstr);
420	}
421
422	/**
423	* 'Constructor' for the component class.
424	* This constructor, as opposed to NS_GENERIC_FACTORY_CONSTRUCTOR,
425	* assumes that the component class is derived from the CComObjectRootEx<>
426	* template, so it calls FinalConstruct() right after object creation
427	* and ensures that FinalRelease() will be called right before destruction.
428	* The result from FinalConstruct() is returned to the caller.
429	*/
430	#define NS_GENERIC_FACTORY_CONSTRUCTOR_WITH_RC(_InstanceClass) \
431	static NS_IMETHODIMP \
432	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
433	void **aResult) \
434	{ \
435	nsresult rv; \
436	\
437	*aResult = NULL; \
438	if (NULL != aOuter) { \
439	rv = NS_ERROR_NO_AGGREGATION; \
440	return rv; \
441	} \
442	\
443	CComObject <_InstanceClass> *inst = new CComObject <_InstanceClass>(); \
444	if (NULL == inst) { \
445	rv = NS_ERROR_OUT_OF_MEMORY; \
446	return rv; \
447	} \
448	\
449	NS_ADDREF(inst); /* protect FinalConstruct() */ \
450	rv = inst->FinalConstruct(); \
451	if (NS_SUCCEEDED(rv)) \
452	rv = inst->QueryInterface(aIID, aResult); \
453	NS_RELEASE(inst); \
454	\
455	return rv; \
456	}
457
458	/**
459	* 'Constructor' that uses an existing getter function that gets a singleton.
460	* The getter function must have the following prototype:
461	* nsresult _GetterProc(_InstanceClass **inst)
462	* This constructor, as opposed to NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR,
463	* lets the getter function return a result code that is passed back to the
464	* caller that tries to instantiate the object.
465	* NOTE: assumes that getter does an AddRef - so additional AddRef is not done.
466	*/
467	#define NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR_WITH_RC(_InstanceClass, _GetterProc) \
468	static NS_IMETHODIMP \
469	_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
470	void **aResult) \
471	{ \
472	nsresult rv; \
473	\
474	_InstanceClass * inst = NULL; /* initialized to shut up gcc */ \
475	\
476	*aResult = NULL; \
477	if (NULL != aOuter) { \
478	rv = NS_ERROR_NO_AGGREGATION; \
479	return rv; \
480	} \
481	\
482	rv = _GetterProc(&inst); \
483	if (NS_FAILED(rv)) \
484	return rv; \
485	\
486	/* sanity check */ \
487	if (NULL == inst) \
488	return NS_ERROR_OUT_OF_MEMORY; \
489	\
490	/* NS_ADDREF(inst); */ \
491	if (NS_SUCCEEDED(rv)) { \
492	rv = inst->QueryInterface(aIID, aResult); \
493	} \
494	NS_RELEASE(inst); \
495	\
496	return rv; \
497	}
498
499	#endif /* !defined(VBOX_WITH_XPCOM) */
500
501	/**
502	* Declares a wchar_t string literal from the argument.
503	* Necessary to overcome MSC / GCC differences.
504	* @param s expression to stringify
505	*/
506	#if defined(_MSC_VER)
507	# define WSTR_LITERAL(s) L#s
508	#elif defined(__GNUC__)
509	# define WSTR_LITERAL(s) L""#s
510	#else
511	# error "Unsupported compiler!"
512	#endif
513
514	namespace com
515	{
516
517	// use this macro to implement scriptable interfaces
518	#ifdef RT_OS_WINDOWS
519	#define VBOX_SCRIPTABLE_IMPL(iface) \
520	public IDispatchImpl<iface, &IID_##iface, &LIBID_VirtualBox, \
521	kTypeLibraryMajorVersion, kTypeLibraryMinorVersion>
522
523	#define VBOX_SCRIPTABLE_DISPATCH_IMPL(iface) \
524	STDMETHOD(QueryInterface)(REFIID riid , void **ppObj) \
525	{ \
526	if (riid == IID_##iface) \
527	{ \
528	ppObj = (iface)this; \
529	AddRef(); \
530	return S_OK; \
531	} \
532	if (riid == IID_IUnknown) \
533	{ \
534	ppObj = (IUnknown)this; \
535	AddRef(); \
536	return S_OK; \
537	} \
538	if (riid == IID_IDispatch) \
539	{ \
540	ppObj = (IDispatch)this; \
541	AddRef(); \
542	return S_OK; \
543	} \
544	*ppObj = NULL; \
545	return E_NOINTERFACE; \
546	}
547
548
549	#define VBOX_DEFAULT_INTERFACE_ENTRIES(iface) \
550	COM_INTERFACE_ENTRY(ISupportErrorInfo) \
551	COM_INTERFACE_ENTRY(iface) \
552	COM_INTERFACE_ENTRY2(IDispatch,iface) \
553	COM_INTERFACE_ENTRY_AGGREGATE(IID_IMarshal, m_pUnkMarshaler.p)
554	#else
555	#define VBOX_SCRIPTABLE_IMPL(iface) \
556	public iface
557	#define VBOX_SCRIPTABLE_DISPATCH_IMPL(iface)
558	#define VBOX_DEFAULT_INTERFACE_ENTRIES(iface)
559	#endif
560
561
562	} /* namespace com */
563
564	#endif /* !___VBox_com_defs_h */
565

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

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

Download in other formats: