VirtualBox

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

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

Fixed include order, a bunch of GCC 3.3 warnings, OS/2 build.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 20.6 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/* Make sure all the stdint.h macros are included - must come first! */
35#ifndef __STDC_LIMIT_MACROS
36# define __STDC_LIMIT_MACROS
37#endif
38#ifndef __STDC_CONSTANT_MACROS
39# define __STDC_CONSTANT_MACROS
40#endif
41
42#if defined (RT_OS_OS2)
43
44#if defined(RT_MAX) && RT_MAX != 22
45# error RT_MAX already defined by <iprt/cdefs.h>! Make sure <VBox/com/defs.h> \
46 is included before it.
47#endif
48
49/* Make sure OS/2 Toolkit headers are pulled in to have BOOL/ULONG/etc. typedefs
50 * already defined in order to be able to redefine them using #define. It's
51 * also important to do it before iprt/cdefs.h, otherwise we'll lose RT_MAX in
52 * all code that uses COM Glue. */
53#define INCL_BASE
54#define INCL_PM
55#include <os2.h>
56
57/* OS/2 Toolkit defines TRUE and FALSE */
58#undef FALSE
59#undef TRUE
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 * get 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# include <atlbase.h>
78#include <atlcom.h>
79#endif
80
81#define NS_DECL_ISUPPORTS
82#define NS_IMPL_ISUPPORTS1_CI(a, b)
83
84/* these are XPCOM only, one for every interface implemented */
85#define NS_DECL_ISUPPORTS
86#define NS_DECL_IVIRTUALBOX
87#define NS_DECL_IMACHINECOLLECTION
88#define NS_DECL_IMACHINE
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/** Input pointer argument prefix in the interface method declaration. */
94#define INPTR
95
96/** Makes the name of the getter interface function (n must be capitalized). */
97#define COMGETTER(n) get_##n
98/** Makes the name of the setter interface function (n must be capitalized). */
99#define COMSETTER(n) put_##n
100
101/** Type for an input GUID parameter in the interface method declaration. */
102#define GUIDPARAM GUID
103/** Type for an output GUID parameter in the interface method declaration. */
104#define GUIDPARAMOUT GUID*
105
106/**
107 * Declares an input safearray parameter in the COM method implementation. Also
108 * used to declare the COM attribute setter parameter. Corresponds to either of
109 * the following XIDL definitions:
110 * <pre>
111 * <param name="arg" ... dir="in" safearray="yes"/>
112 * ...
113 * <attribute name="arg" ... safearray="yes"/>
114 * </pre>
115 *
116 * The method implementation should use the com::SafeArray helper class to work
117 * with parameters declared using this define.
118 *
119 * @param aType Array element type.
120 * @param aArg Parameter/attribute name.
121 */
122#define ComSafeArrayIn(aType, aArg) SAFEARRAY **aArg
123
124/**
125 * Expands to @true if the given input safearray parameter is a "null pointer"
126 * which makes it impossible to use it for reading safearray data.
127 */
128#define ComSafeArrayInIsNull(aArg) ((aArg) == NULL || *(aArg) == NULL)
129
130/**
131 * Wraps the given parameter name to generate an expression that is suitable for
132 * passing the parameter to functions that take input safearray parameters
133 * declared using the ComSafeArrayIn marco.
134 *
135 * @param aArg Parameter name to wrap. The given parameter must be declared
136 * within the calling function using the ComSafeArrayIn macro.
137 */
138#define ComSafeArrayInArg(aArg) aArg
139
140/**
141 * Declares an output safearray parameter in the COM method implementation. Also
142 * used to declare the COM attribute getter parameter. Corresponds to either of
143 * the following XIDL definitions:
144 * <pre>
145 * <param name="arg" ... dir="out" safearray="yes"/>
146 * <param name="arg" ... dir="return" safearray="yes"/>
147 * ...
148 * <attribute name="arg" ... safearray="yes"/>
149 * </pre>
150 *
151 * The method implementation should use the com::SafeArray helper class to work
152 * with parameters declared using this define.
153 *
154 * @param aType Array element type.
155 * @param aArg Parameter/attribute name.
156 */
157#define ComSafeArrayOut(aType, aArg) SAFEARRAY **aArg
158
159/**
160 * Expands to @true if the given output safearray parameter is a "null pointer"
161 * which makes it impossible to use it for returning a safearray.
162 */
163#define ComSafeArrayOutIsNull(aArg) ((aArg) == NULL)
164
165/**
166 * Wraps the given parameter name to generate an expression that is suitable for
167 * passing the parameter to functions that take output safearray parameters
168 * declared using the ComSafeArrayOut marco.
169 *
170 * @param aArg Parameter name to wrap. The given parameter must be declared
171 * within the calling function using the ComSafeArrayOut macro.
172 */
173#define ComSafeArrayOutArg(aArg) aArg
174
175/**
176 * Version of ComSafeArrayIn for GUID.
177 * @param aArg Parameter name to wrap.
178 */
179#define ComSafeGUIDArrayIn(aArg) SAFEARRAY **aArg
180
181/**
182 * Version of ComSafeArrayInIsNull for GUID.
183 * @param aArg Parameter name to wrap.
184 */
185#define ComSafeGUIDArrayInIsNull(aArg) ComSafeArrayInIsNull (aArg)
186
187/**
188 * Version of ComSafeArrayInArg for GUID.
189 * @param aArg Parameter name to wrap.
190 */
191#define ComSafeGUIDArrayInArg(aArg) ComSafeArrayInArg (aArg)
192
193/**
194 * Version of ComSafeArrayOut for GUID.
195 * @param aArg Parameter name to wrap.
196 */
197#define ComSafeGUIDArrayOut(aArg) SAFEARRAY **aArg
198
199/**
200 * Version of ComSafeArrayOutIsNull for GUID.
201 * @param aArg Parameter name to wrap.
202 */
203#define ComSafeGUIDArrayOutIsNull(aArg) ComSafeArrayOutIsNull (aArg)
204
205/**
206 * Version of ComSafeArrayOutArg for GUID.
207 * @param aArg Parameter name to wrap.
208 */
209#define ComSafeGUIDArrayOutArg(aArg) ComSafeArrayOutArg (aArg)
210
211/**
212 * Returns the const reference to the IID (i.e., |const GUID &|) of the given
213 * interface.
214 *
215 * @param i interface class
216 */
217#define COM_IIDOF(I) _ATL_IIDOF (I)
218
219#else /* defined (RT_OS_WINDOWS) */
220
221#error "VBOX_WITH_XPCOM must be defined on a platform other than Windows!"
222
223#endif /* defined (RT_OS_WINDOWS) */
224
225#else /* !defined (VBOX_WITH_XPCOM) */
226
227// XPCOM
228/////////////////////////////////////////////////////////////////////////////
229
230#if defined (RT_OS_DARWIN) || (defined (QT_VERSION) && (QT_VERSION >= 0x040000))
231 /* CFBase.h defines these &
232 * qglobal.h from Qt4 defines these */
233# undef FALSE
234# undef TRUE
235#endif /* RT_OS_DARWIN || QT_VERSION */
236
237#include <nsID.h>
238
239#define ATL_NO_VTABLE
240#define DECLARE_CLASSFACTORY(a)
241#define DECLARE_CLASSFACTORY_SINGLETON(a)
242#define DECLARE_REGISTRY_RESOURCEID(a)
243#define DECLARE_NOT_AGGREGATABLE(a)
244#define DECLARE_PROTECT_FINAL_CONSTRUCT(a)
245#define BEGIN_COM_MAP(a)
246#define COM_INTERFACE_ENTRY(a)
247#define COM_INTERFACE_ENTRY2(a,b)
248#define END_COM_MAP(a)
249
250#define HRESULT nsresult
251#define SUCCEEDED NS_SUCCEEDED
252#define FAILED NS_FAILED
253
254#define SUCCEEDED_WARNING(rc) (NS_SUCCEEDED (rc) && (rc) != NS_OK)
255
256#define IUnknown nsISupports
257
258#define BOOL PRBool
259#define BYTE PRUint8
260#define SHORT PRInt16
261#define USHORT PRUint16
262#define LONG PRInt32
263#define ULONG PRUint32
264#define LONG64 PRInt64
265#define ULONG64 PRUint64
266
267#define BSTR PRUnichar *
268#define LPBSTR BSTR *
269#define OLECHAR wchar_t
270
271#define FALSE PR_FALSE
272#define TRUE PR_TRUE
273
274/** Input pointer argument prefix in the interface method declaration. */
275#define INPTR const
276
277/** Makes the name of the getter interface function (n must be capitalized). */
278#define COMGETTER(n) Get##n
279/** Makes the name of the setter interface function (n must be capitalized). */
280#define COMSETTER(n) Set##n
281
282/**
283 * Type to define a raw GUID variable (for members use the com::Guid class
284 * instead).
285 */
286#define GUID nsID
287/** Type for an input GUID parameter in the interface method declaration. */
288#define GUIDPARAM nsID &
289/** Type for an output GUID parameter in the interface method declaration. */
290#define GUIDPARAMOUT nsID **
291
292/* safearray input parameter macros */
293#define ComSafeArrayIn(aType, aArg) PRUint32 aArg##Size, aType *aArg
294#define ComSafeArrayInIsNull(aArg) ((aArg) == NULL)
295#define ComSafeArrayInArg(aArg) aArg##Size, aArg
296
297/* safearray output parameter macros */
298#define ComSafeArrayOut(aType, aArg) PRUint32 *aArg##Size, aType **aArg
299#define ComSafeArrayOutIsNull(aArg) ((aArg) == NULL)
300#define ComSafeArrayOutArg(aArg) aArg##Size, aArg
301
302/* safearray input parameter macros for GUID */
303#define ComSafeGUIDArrayIn(aArg) PRUint32 aArg##Size, const nsID **aArg
304#define ComSafeGUIDArrayInIsNull(aArg) ComSafeArrayInIsNull (aArg)
305#define ComSafeGUIDArrayInArg(aArg) ComSafeArrayInArg (aArg)
306
307/* safearray output parameter macros for GUID */
308#define ComSafeGUIDArrayOut(aArg) PRUint32 *aArg##Size, nsID ***aArg
309#define ComSafeGUIDArrayOutIsNull(aArg) ComSafeArrayOutIsNull (aArg)
310#define ComSafeGUIDArrayOutArg(aArg) ComSafeArrayOutArg (aArg)
311
312/* CLSID and IID for compatibility with Win32 */
313typedef nsCID CLSID;
314typedef nsIID IID;
315
316/* OLE error codes */
317#define S_OK ((nsresult) NS_OK)
318#define E_UNEXPECTED NS_ERROR_UNEXPECTED
319#define E_NOTIMPL NS_ERROR_NOT_IMPLEMENTED
320#define E_OUTOFMEMORY NS_ERROR_OUT_OF_MEMORY
321#define E_INVALIDARG NS_ERROR_INVALID_ARG
322#define E_NOINTERFACE NS_ERROR_NO_INTERFACE
323#define E_POINTER NS_ERROR_NULL_POINTER
324#define E_ABORT NS_ERROR_ABORT
325#define E_FAIL NS_ERROR_FAILURE
326/* Note: a better analog for E_ACCESSDENIED would probably be
327 * NS_ERROR_NOT_AVAILABLE, but we want binary compatibility for now. */
328#define E_ACCESSDENIED ((nsresult) 0x80070005L)
329
330#define STDMETHOD(a) NS_IMETHOD a
331#define STDMETHODIMP NS_IMETHODIMP
332
333#define COM_IIDOF(I) NS_GET_IID (I)
334
335/* two very simple ATL emulator classes to provide
336 * FinalConstruct()/FinalRelease() functionality on Linux */
337
338class CComObjectRootEx
339{
340public:
341 HRESULT FinalConstruct() { return S_OK; }
342 void FinalRelease() {}
343};
344
345template <class Base> class CComObject : public Base
346{
347public:
348 virtual ~CComObject() { this->FinalRelease(); }
349};
350
351/* helper functions */
352extern "C"
353{
354BSTR SysAllocString (const OLECHAR* sz);
355BSTR SysAllocStringByteLen (char *psz, unsigned int len);
356BSTR SysAllocStringLen (const OLECHAR *pch, unsigned int cch);
357void SysFreeString (BSTR bstr);
358int SysReAllocString (BSTR *pbstr, const OLECHAR *psz);
359int SysReAllocStringLen (BSTR *pbstr, const OLECHAR *psz, unsigned int cch);
360unsigned int SysStringByteLen (BSTR bstr);
361unsigned int SysStringLen (BSTR bstr);
362}
363
364/**
365 * 'Constructor' for the component class.
366 * This constructor, as opposed to NS_GENERIC_FACTORY_CONSTRUCTOR,
367 * assumes that the component class is derived from the CComObjectRootEx<>
368 * template, so it calls FinalConstruct() right after object creation
369 * and ensures that FinalRelease() will be called right before destruction.
370 * The result from FinalConstruct() is returned to the caller.
371 */
372#define NS_GENERIC_FACTORY_CONSTRUCTOR_WITH_RC(_InstanceClass) \
373static NS_IMETHODIMP \
374_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
375 void **aResult) \
376{ \
377 nsresult rv; \
378 \
379 *aResult = NULL; \
380 if (NULL != aOuter) { \
381 rv = NS_ERROR_NO_AGGREGATION; \
382 return rv; \
383 } \
384 \
385 CComObject <_InstanceClass> *inst = new CComObject <_InstanceClass>(); \
386 if (NULL == inst) { \
387 rv = NS_ERROR_OUT_OF_MEMORY; \
388 return rv; \
389 } \
390 \
391 NS_ADDREF(inst); /* protect FinalConstruct() */ \
392 rv = inst->FinalConstruct(); \
393 if (NS_SUCCEEDED(rv)) \
394 rv = inst->QueryInterface(aIID, aResult); \
395 NS_RELEASE(inst); \
396 \
397 return rv; \
398}
399
400/**
401 * 'Constructor' that uses an existing getter function that gets a singleton.
402 * The getter function must have the following prototype:
403 * nsresult _GetterProc (_InstanceClass **inst)
404 * This constructor, as opposed to NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR,
405 * lets the getter function return a result code that is passed back to the
406 * caller that tries to instantiate the object.
407 * NOTE: assumes that getter does an AddRef - so additional AddRef is not done.
408 */
409#define NS_GENERIC_FACTORY_SINGLETON_CONSTRUCTOR_WITH_RC(_InstanceClass, _GetterProc) \
410static NS_IMETHODIMP \
411_InstanceClass##Constructor(nsISupports *aOuter, REFNSIID aIID, \
412 void **aResult) \
413{ \
414 nsresult rv; \
415 \
416 _InstanceClass * inst; \
417 \
418 *aResult = NULL; \
419 if (NULL != aOuter) { \
420 rv = NS_ERROR_NO_AGGREGATION; \
421 return rv; \
422 } \
423 \
424 rv = _GetterProc(&inst); \
425 if (NS_FAILED(rv)) \
426 return rv; \
427 \
428 /* sanity check */ \
429 if (NULL == inst) \
430 return NS_ERROR_OUT_OF_MEMORY; \
431 \
432 /* NS_ADDREF(inst); */ \
433 if (NS_SUCCEEDED(rv)) { \
434 rv = inst->QueryInterface(aIID, aResult); \
435 } \
436 NS_RELEASE(inst); \
437 \
438 return rv; \
439}
440
441#endif /* !defined (VBOX_WITH_XPCOM) */
442
443/**
444 * Declares a whar_t string literal from the argument.
445 * Necessary to overcome MSC / GCC differences.
446 * @param s expression to stringify
447 */
448#if defined (_MSC_VER)
449# define WSTR_LITERAL(s) L#s
450#elif defined (__GNUC__)
451# define WSTR_LITERAL(s) L""#s
452#else
453# error "Unsupported compiler!"
454#endif
455
456namespace com
457{
458
459/**
460 * "First worst" result type.
461 *
462 * Variables of this class are used instead of HRESULT variables when it is
463 * desirable to memorize the "first worst" result code instead of the last
464 * assigned one. In other words, an assignment operation to a variable of this
465 * class will succeed only if the result code to assign has worse severity. The
466 * following table demonstrate this (the first column lists the previous result
467 * code stored in the variable, the first row lists the new result code being
468 * assigned, 'A' means the assignment will take place, '> S_OK' means a warning
469 * result code):
470 *
471 * {{{
472 * FAILED > S_OK S_OK
473 * FAILED - - -
474 * > S_OK A - -
475 * S_OK A A -
476 *
477 * }}}
478 *
479 * On practice, you will need to use a FWResult variable when you call some COM
480 * method B after another COM method A fails and want to return the result code
481 * of A even if B also fails, but want to return the failed result code of B if
482 * A issues a warning or succeeds.
483 */
484class FWResult
485{
486
487public:
488
489 /**
490 * Constructs a new variable. Note that by default this constructor sets the
491 * result code to E_FAIL to make sure a failure is returned to the caller if
492 * the variable is never assigned another value (which is considered as the
493 * improper use of this class).
494 */
495 FWResult (HRESULT aRC = E_FAIL) : mRC (aRC) {}
496
497 FWResult &operator= (HRESULT aRC)
498 {
499 if ((FAILED (aRC) && !FAILED (mRC)) ||
500 (mRC == S_OK && aRC != S_OK))
501 mRC = aRC;
502
503 return *this;
504 }
505
506 operator HRESULT() const { return mRC; }
507
508 HRESULT *operator&() { return &mRC; }
509
510private:
511
512 HRESULT mRC;
513};
514
515/**
516 * "Last worst" result type.
517 *
518 * Variables of this class are used instead of HRESULT variables when it is
519 * desirable to memorize the "last worst" result code instead of the last
520 * assigned one. In other words, an assignment operation to a variable of this
521 * class will succeed only if the result code to assign has the same or worse
522 * severity. The following table demonstrate this (the first column lists the
523 * previous result code stored in the variable, the first row lists the new
524 * assigned, 'A' means the assignment will take place, '> S_OK' means a warning
525 * result code):
526 *
527 * {{{
528 * FAILED > S_OK S_OK
529 * FAILED A - -
530 * > S_OK A A -
531 * S_OK A A -
532 *
533 * }}}
534 *
535 * On practice, you will need to use a LWResult variable when you call some COM
536 * method B after COM method A fails and want to return the result code of B
537 * if B also fails, but still want to return the failed result code of A if B
538 * issues a warning or succeeds.
539 */
540class LWResult
541{
542
543public:
544
545 /**
546 * Constructs a new variable. Note that by default this constructor sets the
547 * result code to E_FAIL to make sure a failure is returned to the caller if
548 * the variable is never assigned another value (which is considered as the
549 * improper use of this class).
550 */
551 LWResult (HRESULT aRC = E_FAIL) : mRC (aRC) {}
552
553 LWResult &operator= (HRESULT aRC)
554 {
555 if (FAILED (aRC) ||
556 (SUCCEEDED (mRC) && aRC != S_OK))
557 mRC = aRC;
558
559 return *this;
560 }
561
562 operator HRESULT() const { return mRC; }
563
564 HRESULT *operator&() { return &mRC; }
565
566private:
567
568 HRESULT mRC;
569};
570
571} /* namespace com */
572
573#endif /* ___VBox_com_defs_h */
574
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