VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use