VirtualBox

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

Last change on this file since 36254 was 35913, checked in by vboxsync, 14 years ago

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette