VirtualBox

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

Last change on this file since 8155 was 8155, checked in by vboxsync, 16 years ago

The Big Sun Rebranding Header Change
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 16.4 KB
Line 
1/** @file
2 * MS COM / XPCOM Abstraction Layer:
3 * Common definitions
4 */
5
6/*
7 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
27 * Clara, CA 95054 USA or visit http://www.sun.com if you need
28 * additional information or have any questions.
29 */
30
31#ifndef ___VBox_com_defs_h
32#define ___VBox_com_defs_h
33
34/*
35 * Include iprt/types.h now to make sure iprt get to stdint.h first,
36 * otherwise a system/xpcom header might beat us and we'll be without
37 * the macros that are optional in C++.
38 */
39#include <iprt/types.h>
40
41#if !defined (VBOX_WITH_XPCOM)
42
43#if defined (RT_OS_WINDOWS)
44
45// Windows COM
46/////////////////////////////////////////////////////////////////////////////
47
48#include <objbase.h>
49#ifndef VBOX_COM_NO_ATL
50#include <atlbase.h>
51#endif
52
53#define NS_DECL_ISUPPORTS
54#define NS_IMPL_ISUPPORTS1_CI(a, b)
55
56/* these are XPCOM only, one for every interface implemented */
57#define NS_DECL_ISUPPORTS
58#define NS_DECL_IVIRTUALBOX
59#define NS_DECL_IMACHINECOLLECTION
60#define NS_DECL_IMACHINE
61
62/** Returns @c true if @a rc represents a warning result code */
63#define SUCCEEDED_WARNING(rc) (SUCCEEDED (rc) && (rc) != S_OK)
64
65/* input pointer argument to method */
66#define INPTR
67
68/* makes the name of the getter interface function (n must be capitalized) */
69#define COMGETTER(n) get_##n
70/* makes the name of the setter interface function (n must be capitalized) */
71#define COMSETTER(n) put_##n
72
73/* a type for an input GUID parameter in the interface method declaration */
74#define GUIDPARAM GUID
75/* a type for an output GUID parameter in the interface method declaration */
76#define GUIDPARAMOUT GUID*
77
78/**
79 * Declares an input safearray parameter in the COM method implementation. Also
80 * used to declare the COM attribute setter parameter. Corresponds to either of
81 * the following XIDL definitions:
82 * <pre>
83 * <param name="arg" ... dir="in" safearray="yes"/>
84 * ...
85 * <attribute name="arg" ... safearray="yes"/>
86 * </pre>
87 *
88 * The method implementation should use the com::SafeArray helper class to work
89 * with parameters declared using this define.
90 *
91 * @param aType Array element type.
92 * @param aArg Parameter/attribute name.
93 */
94#define ComSafeArrayIn(aType, aArg) SAFEARRAY **aArg
95
96/**
97 * Expands to @true if the given input safearray parameter is a "null pointer"
98 * which makes it impossible to use it for reading safearray data.
99 */
100#define ComSafeArrayInIsNull(aArg) (aArg == NULL)
101
102/**
103 * Wraps the given parameter name to generate an expression that is suitable for
104 * passing the parameter to functions that take input safearray parameters
105 * declared using the ComSafeArrayIn marco.
106 *
107 * @param aArg Parameter name to wrap. The given parameter must be declared
108 * within the calling function using the ComSafeArrayIn macro.
109 */
110#define ComSafeArrayInArg(aArg) aArg
111
112/**
113 * Declares an output safearray parameter in the COM method implementation. Also
114 * used to declare the COM attribute getter parameter. Corresponds to either of
115 * the following XIDL definitions:
116 * <pre>
117 * <param name="arg" ... dir="out" safearray="yes"/>
118 * <param name="arg" ... dir="return" safearray="yes"/>
119 * ...
120 * <attribute name="arg" ... safearray="yes"/>
121 * </pre>
122 *
123 * The method implementation should use the com::SafeArray helper class to work
124 * with parameters declared using this define.
125 *
126 * @param aType Array element type.
127 * @param aArg Parameter/attribute name.
128 */
129#define ComSafeArrayOut(aType, aArg) SAFEARRAY **aArg
130
131/**
132 * Expands to @true if the given output safearray parameter is a "null pointer"
133 * which makes it impossible to use it for returning a safearray.
134 */
135#define ComSafeArrayOutIsNull(aArg) (aArg == NULL)
136
137/**
138 * Wraps the given parameter name to generate an expression that is suitable for
139 * passing the parameter to functions that take output safearray parameters
140 * declared using the ComSafeArrayOut marco.
141 *
142 * @param aArg Parameter name to wrap. The given parameter must be declared
143 * within the calling function using the ComSafeArrayOut macro.
144 */
145#define ComSafeArrayOutArg(aArg) aArg
146
147/**
148 * Returns the const reference to the IID (i.e., |const GUID &|) of the given
149 * interface.
150 *
151 * @param i interface class
152 */
153#define COM_IIDOF(I) _ATL_IIDOF (I)
154
155#else /* defined (RT_OS_WINDOWS) */
156
157#error "VBOX_WITH_XPCOM must be defined on a platform other than Windows!"
158
159#endif /* defined (RT_OS_WINDOWS) */
160
161#else /* !defined (VBOX_WITH_XPCOM) */
162
163// XPCOM
164/////////////////////////////////////////////////////////////////////////////
165
166#if defined (RT_OS_OS2)
167
168/* Make sure OS/2 Toolkit headers are pulled in to have
169 * BOOL/ULONG/etc. typedefs already defined in order to be able to redefine
170 * them using #define. */
171#define INCL_BASE
172#define INCL_PM
173#include <os2.h>
174
175/* OS/2 Toolkit defines TRUE and FALSE */
176#undef FALSE
177#undef TRUE
178
179#endif /* defined (RT_OS_OS2) */
180
181#if defined (RT_OS_DARWIN)
182 /* CFBase.h defines these*/
183# undef FALSE
184# undef TRUE
185#endif /* RT_OS_DARWIN */
186
187#include <nsID.h>
188
189#define ATL_NO_VTABLE
190#define DECLARE_CLASSFACTORY(a)
191#define DECLARE_CLASSFACTORY_SINGLETON(a)
192#define DECLARE_REGISTRY_RESOURCEID(a)
193#define DECLARE_NOT_AGGREGATABLE(a)
194#define DECLARE_PROTECT_FINAL_CONSTRUCT(a)
195#define BEGIN_COM_MAP(a)
196#define COM_INTERFACE_ENTRY(a)
197#define COM_INTERFACE_ENTRY2(a,b)
198#define END_COM_MAP(a)
199
200#define HRESULT nsresult
201#define SUCCEEDED NS_SUCCEEDED
202#define FAILED NS_FAILED
203
204#define SUCCEEDED_WARNING(rc) (NS_SUCCEEDED (rc) && (rc) != NS_OK)
205
206#define IUnknown nsISupports
207
208#define BOOL PRBool
209#define BYTE PRUint8
210#define SHORT PRInt16
211#define USHORT PRUint16
212#define LONG PRInt32
213#define ULONG PRUint32
214#define LONG64 PRInt64
215#define ULONG64 PRUint64
216
217#define BSTR PRUnichar *
218#define LPBSTR BSTR *
219#define OLECHAR wchar_t
220
221#define FALSE PR_FALSE
222#define TRUE PR_TRUE
223
224/* makes the name of the getter interface function (n must be capitalized) */
225#define COMGETTER(n) Get##n
226/* makes the name of the setter interface function (n must be capitalized) */
227#define COMSETTER(n) Set##n
228
229/* a type to define a raw GUID variable (better to use the Guid class) */
230#define GUID nsID
231/* a type for an input GUID parameter in the interface method declaration */
232#define GUIDPARAM nsID &
233/* a type for an output GUID parameter in the interface method declaration */
234#define GUIDPARAMOUT nsID **
235
236/* safearray input parameter macros */
237#define ComSafeArrayIn(aType, aArg) PRUint32 aArg##Size, aType *aArg
238#define ComSafeArrayInIsNull(aArg) (aArg == NULL)
239#define ComSafeArrayInArg(aArg) aArg##Size, aArg
240
241/* safearray output parameter macros */
242#define ComSafeArrayOut(aType, aArg) PRUint32 *aArg##Size, aType **aArg
243#define ComSafeArrayOutIsNull(aArg) (aArg == NULL)
244#define ComSafeArrayOutArg(aArg) aArg##Size, aArg
245
246/* CLSID and IID for compatibility with Win32 */
247typedef nsCID CLSID;
248typedef nsIID IID;
249
250/* OLE error codes */
251#define S_OK NS_OK
252#define E_UNEXPECTED NS_ERROR_UNEXPECTED
253#define E_NOTIMPL NS_ERROR_NOT_IMPLEMENTED
254#define E_OUTOFMEMORY NS_ERROR_OUT_OF_MEMORY
255#define E_INVALIDARG NS_ERROR_INVALID_ARG
256#define E_NOINTERFACE NS_ERROR_NO_INTERFACE
257#define E_POINTER NS_ERROR_NULL_POINTER
258#define E_ABORT NS_ERROR_ABORT
259#define E_FAIL NS_ERROR_FAILURE
260/* Note: a better analog for E_ACCESSDENIED would probably be
261 * NS_ERROR_NOT_AVAILABLE, but we want binary compatibility for now. */
262#define E_ACCESSDENIED ((nsresult) 0x80070005L)
263
264#define STDMETHOD(a) NS_IMETHOD a
265#define STDMETHODIMP NS_IMETHODIMP
266
267#define COM_IIDOF(I) NS_GET_IID (I)
268
269/* two very simple ATL emulator classes to provide
270 * FinalConstruct()/FinalRelease() functionality on Linux */
271
272class CComObjectRootEx
273{
274public:
275 HRESULT FinalConstruct() { return S_OK; }
276 void FinalRelease() {}
277};
278
279template <class Base> class CComObject : public Base
280{
281public:
282 virtual ~CComObject() { this->FinalRelease(); }
283};
284
285/* input pointer argument to method */
286#define INPTR const
287
288/* helper functions */
289extern "C"
290{
291BSTR SysAllocString (const OLECHAR* sz);
292BSTR SysAllocStringByteLen (char *psz, unsigned int len);
293BSTR SysAllocStringLen (const OLECHAR *pch, unsigned int cch);
294void SysFreeString (BSTR bstr);
295int SysReAllocString (BSTR *pbstr, const OLECHAR *psz);
296int SysReAllocStringLen (BSTR *pbstr, const OLECHAR *psz, unsigned int cch);
297unsigned int SysStringByteLen (BSTR bstr);
298unsigned int SysStringLen (BSTR bstr);
299}
300
301/**
302 * 'Constructor' for the component class.
303 * This constructor, as opposed to NS_GENERIC_FACTORY_CONSTRUCTOR,
304 * assumes that the component class is derived from the CComObjectRootEx<>
305 * template, so it calls FinalConstruct() right after object creation
306 * and ensures that FinalRelease() will be called right before destruction.
307 * The result from FinalConstruct() is returned to the caller.
308 */
309#define NS_GENERIC_FACTORY_CONSTRUCTOR_WITH_RC(_InstanceClass) \
310static NS_IMETHODIMP \
311_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
312 void **aResult) \
313{ \
314 nsresult rv; \
315 \
316 *aResult = NULL; \
317 if (NULL != aOuter) { \
318 rv = NS_ERROR_NO_AGGREGATION; \
319 return rv; \
320 } \
321 \
322 CComObject <_InstanceClass> *inst = new CComObject <_InstanceClass>(); \
323 if (NULL == inst) { \
324 rv = NS_ERROR_OUT_OF_MEMORY; \
325 return rv; \
326 } \
327 \
328 NS_ADDREF(inst); /* protect FinalConstruct() */ \
329 rv = inst->FinalConstruct(); \
330 if (NS_SUCCEEDED(rv)) \
331 rv = inst->QueryInterface(aIID, aResult); \
332 NS_RELEASE(inst); \
333 \
334 return rv; \
335}
336
337/**
338 * 'Constructor' that uses an existing getter function that gets a singleton.
339 * The getter function must have the following prototype:
340 * nsresult _GetterProc (_InstanceClass **inst)
341 * This constructor, as opposed to NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR,
342 * lets the getter function return a result code that is passed back to the
343 * caller that tries to instantiate the object.
344 * NOTE: assumes that getter does an AddRef - so additional AddRef is not done.
345 */
346#define NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR_WITH_RC(_InstanceClass, _GetterProc) \
347static NS_IMETHODIMP \
348_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
349 void **aResult) \
350{ \
351 nsresult rv; \
352 \
353 _InstanceClass * inst; \
354 \
355 *aResult = NULL; \
356 if (NULL != aOuter) { \
357 rv = NS_ERROR_NO_AGGREGATION; \
358 return rv; \
359 } \
360 \
361 rv = _GetterProc(&inst); \
362 if (NS_FAILED(rv)) \
363 return rv; \
364 \
365 /* sanity check */ \
366 if (NULL == inst) \
367 return NS_ERROR_OUT_OF_MEMORY; \
368 \
369 /* NS_ADDREF(inst); */ \
370 if (NS_SUCCEEDED(rv)) { \
371 rv = inst->QueryInterface(aIID, aResult); \
372 } \
373 NS_RELEASE(inst); \
374 \
375 return rv; \
376}
377
378#endif /* !defined (VBOX_WITH_XPCOM) */
379
380/**
381 * Declares a whar_t string literal from the argument.
382 * Necessary to overcome MSC / GCC differences.
383 * @param s expression to stringify
384 */
385#if defined (_MSC_VER)
386# define WSTR_LITERAL(s) L#s
387#elif defined (__GNUC__)
388# define WSTR_LITERAL(s) L""#s
389#else
390# error "Unsupported compiler!"
391#endif
392
393namespace com
394{
395
396/**
397 * "Last worst" result type.
398 *
399 * Variables of this class are used instead of HRESULT variables when it is
400 * desirable to memorize the "last worst" result code instead of the last
401 * assigned one. In other words, an assignment operation to a variable of this
402 * class will succeed only if the result code to assign has the same or worse
403 * severity. The following table demonstrate this (the first column lists the
404 * previous result code stored in the variable, the first row lists the new
405 * result code being assigned, 'A' means the assignment will take place):
406 *
407 * {{{
408 * FAILED > S_OK S_OK
409 * FAILED A - -
410 * > S_OK A A -
411 * S_OK A A -
412 *
413 * }}}
414 */
415class LWResult
416{
417
418public:
419
420 /**
421 * Constructs a new variable. Note that by default this constructor sets the
422 * result code to E_FAIL to make sure a failure is returned to the caller if
423 * the variable is never assigned another value (which is considered as the
424 * improper use of this class).
425 */
426 LWResult (HRESULT aRC = E_FAIL) : mRC (aRC) {}
427
428 LWResult &operator= (HRESULT aRC)
429 {
430 if (FAILED (aRC) ||
431 (SUCCEEDED (mRC) && aRC != S_OK))
432 mRC = aRC;
433
434 return *this;
435 }
436
437 operator HRESULT() const { return mRC; }
438
439 HRESULT *operator&() { return &mRC; }
440
441private:
442
443 HRESULT mRC;
444};
445
446} /* namespace com */
447
448#endif /* ___VBox_com_defs_h */
449
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use