VirtualBoxBase.h@ 63240

Last change on this file since 63240 was 63147, checked in by vboxsync, 8 years ago
Main: warnings
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.0 KB

Line
1	/* $Id: VirtualBoxBase.h 63147 2016-08-08 11:12:33Z vboxsync $ */
2	/** @file
3	* VirtualBox COM base classes definition
4	*/
5
6	/*
7	* Copyright (C) 2006-2016 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
18	#ifndef ____H_VIRTUALBOXBASEIMPL
19	#define ____H_VIRTUALBOXBASEIMPL
20
21	#include <iprt/cdefs.h>
22	#include <iprt/thread.h>
23
24	#include <list>
25	#include <map>
26
27	#include "ObjectState.h"
28
29	#include "VBox/com/AutoLock.h"
30	#include "VBox/com/string.h"
31	#include "VBox/com/Guid.h"
32
33	#include "VBox/com/VirtualBox.h"
34
35	// avoid including VBox/settings.h and VBox/xml.h; only declare the classes
36	namespace xml
37	{
38	class File;
39	}
40
41	namespace com
42	{
43	class ErrorInfo;
44	}
45
46	using namespace com;
47	using namespace util;
48
49	class VirtualBox;
50	class Machine;
51	class Medium;
52	class Host;
53	typedef std::list<ComObjPtr<Medium> > MediaList;
54	typedef std::list<Utf8Str> StringsList;
55
56	////////////////////////////////////////////////////////////////////////////////
57	//
58	// COM helpers
59	//
60	////////////////////////////////////////////////////////////////////////////////
61
62	#if !defined(VBOX_WITH_XPCOM)
63
64	/* use a special version of the singleton class factory,
65	* see KB811591 in msdn for more info. */
66
67	#undef DECLARE_CLASSFACTORY_SINGLETON
68	#define DECLARE_CLASSFACTORY_SINGLETON(obj) DECLARE_CLASSFACTORY_EX(CMyComClassFactorySingleton<obj>)
69
70	template <class T>
71	class CMyComClassFactorySingleton : public ATL::CComClassFactory
72	{
73	public:
74	CMyComClassFactorySingleton() :
75	m_hrCreate(S_OK), m_spObj(NULL)
76	{
77	}
78	virtual ~CMyComClassFactorySingleton()
79	{
80	if (m_spObj)
81	m_spObj->Release();
82	}
83	// IClassFactory
84	STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid, void** ppvObj)
85	{
86	HRESULT hRes = E_POINTER;
87	if (ppvObj != NULL)
88	{
89	*ppvObj = NULL;
90	// no aggregation for singletons
91	AssertReturn(pUnkOuter == NULL, CLASS_E_NOAGGREGATION);
92	if (m_hrCreate == S_OK && m_spObj == NULL)
93	{
94	Lock();
95	__try
96	{
97	// Fix: The following If statement was moved inside the __try statement.
98	// Did another thread arrive here first?
99	if (m_hrCreate == S_OK && m_spObj == NULL)
100	{
101	// lock the module to indicate activity
102	// (necessary for the monitor shutdown thread to correctly
103	// terminate the module in case when CreateInstance() fails)
104	ATL::_pAtlModule->Lock();
105	ATL::CComObjectCached<T> *p;
106	m_hrCreate = ATL::CComObjectCached<T>::CreateInstance(&p);
107	if (SUCCEEDED(m_hrCreate))
108	{
109	m_hrCreate = p->QueryInterface(IID_IUnknown, (void **)&m_spObj);
110	if (FAILED(m_hrCreate))
111	{
112	delete p;
113	}
114	}
115	ATL::_pAtlModule->Unlock();
116	}
117	}
118	__finally
119	{
120	Unlock();
121	}
122	}
123	if (m_hrCreate == S_OK)
124	{
125	hRes = m_spObj->QueryInterface(riid, ppvObj);
126	}
127	else
128	{
129	hRes = m_hrCreate;
130	}
131	}
132	return hRes;
133	}
134	HRESULT m_hrCreate;
135	IUnknown *m_spObj;
136	};
137
138	#endif /* !defined(VBOX_WITH_XPCOM) */
139
140	////////////////////////////////////////////////////////////////////////////////
141	//
142	// Macros
143	//
144	////////////////////////////////////////////////////////////////////////////////
145
146	/**
147	* Special version of the Assert macro to be used within VirtualBoxBase
148	* subclasses.
149	*
150	* In the debug build, this macro is equivalent to Assert.
151	* In the release build, this macro uses \|setError(E_FAIL, ...)\| to set the
152	* error info from the asserted expression.
153	*
154	* @see VirtualBoxBase::setError
155	*
156	* @param expr Expression which should be true.
157	*/
158	#define ComAssert(expr) \
159	do { \
160	if (RT_LIKELY(!!(expr))) \
161	{ /* likely */ } \
162	else \
163	{ \
164	AssertMsgFailed(("%s\n", #expr)); \
165	setError(E_FAIL, \
166	"Assertion failed: [%s] at '%s' (%d) in %s.\nPlease contact the product vendor!", \
167	#expr, __FILE__, __LINE__, __PRETTY_FUNCTION__); \
168	} \
169	} while (0)
170
171	/**
172	* Special version of the AssertFailed macro to be used within VirtualBoxBase
173	* subclasses.
174	*
175	* In the debug build, this macro is equivalent to AssertFailed.
176	* In the release build, this macro uses \|setError(E_FAIL, ...)\| to set the
177	* error info from the asserted expression.
178	*
179	* @see VirtualBoxBase::setError
180	*
181	*/
182	#define ComAssertFailed() \
183	do { \
184	AssertFailed(); \
185	setError(E_FAIL, \
186	"Assertion failed: at '%s' (%d) in %s.\nPlease contact the product vendor!", \
187	__FILE__, __LINE__, __PRETTY_FUNCTION__); \
188	} while (0)
189
190	/**
191	* Special version of the AssertMsg macro to be used within VirtualBoxBase
192	* subclasses.
193	*
194	* See ComAssert for more info.
195	*
196	* @param expr Expression which should be true.
197	* @param a printf argument list (in parenthesis).
198	*/
199	#define ComAssertMsg(expr, a) \
200	do { \
201	if (RT_LIKELY(!!(expr))) \
202	{ /* likely */ } \
203	else \
204	{ \
205	Utf8StrFmt MyAssertMsg a; /* may throw bad_alloc */ \
206	AssertMsgFailed(("%s\n", MyAssertMsg.c_str())); \
207	setError(E_FAIL, \
208	"Assertion failed: [%s] at '%s' (%d) in %s.\n%s.\nPlease contact the product vendor!", \
209	#expr, __FILE__, __LINE__, __PRETTY_FUNCTION__, MyAssertMsg.c_str()); \
210	} \
211	} while (0)
212
213	/**
214	* Special version of the AssertMsgFailed macro to be used within VirtualBoxBase
215	* subclasses.
216	*
217	* See ComAssert for more info.
218	*
219	* @param a printf argument list (in parenthesis).
220	*/
221	#define ComAssertMsgFailed(a) \
222	do { \
223	Utf8StrFmt MyAssertMsg a; /* may throw bad_alloc */ \
224	AssertMsgFailed(("%s\n", MyAssertMsg.c_str())); \
225	setError(E_FAIL, \
226	"Assertion failed: at '%s' (%d) in %s.\n%s.\nPlease contact the product vendor!", \
227	__FILE__, __LINE__, __PRETTY_FUNCTION__, MyAssertMsg.c_str()); \
228	} while (0)
229
230	/**
231	* Special version of the AssertRC macro to be used within VirtualBoxBase
232	* subclasses.
233	*
234	* See ComAssert for more info.
235	*
236	* @param vrc VBox status code.
237	*/
238	#define ComAssertRC(vrc) ComAssertMsgRC(vrc, ("%Rra", vrc))
239
240	/**
241	* Special version of the AssertMsgRC macro to be used within VirtualBoxBase
242	* subclasses.
243	*
244	* See ComAssert for more info.
245	*
246	* @param vrc VBox status code.
247	* @param msg printf argument list (in parenthesis).
248	*/
249	#define ComAssertMsgRC(vrc, msg) ComAssertMsg(RT_SUCCESS(vrc), msg)
250
251	/**
252	* Special version of the AssertComRC macro to be used within VirtualBoxBase
253	* subclasses.
254	*
255	* See ComAssert for more info.
256	*
257	* @param hrc COM result code
258	*/
259	#define ComAssertComRC(hrc) ComAssertMsg(SUCCEEDED(hrc), ("COM RC=%Rhrc (0x%08X)", (hrc), (hrc)))
260
261
262	/** Special version of ComAssert that returns ret if expr fails */
263	#define ComAssertRet(expr, ret) \
264	do { ComAssert(expr); if (!(expr)) return (ret); } while (0)
265	/** Special version of ComAssertMsg that returns ret if expr fails */
266	#define ComAssertMsgRet(expr, a, ret) \
267	do { ComAssertMsg(expr, a); if (!(expr)) return (ret); } while (0)
268	/** Special version of ComAssertRC that returns ret if vrc does not succeed */
269	#define ComAssertRCRet(vrc, ret) \
270	do { ComAssertRC(vrc); if (!RT_SUCCESS(vrc)) return (ret); } while (0)
271	/** Special version of ComAssertComRC that returns ret if rc does not succeed */
272	#define ComAssertComRCRet(rc, ret) \
273	do { ComAssertComRC(rc); if (!SUCCEEDED(rc)) return (ret); } while (0)
274	/** Special version of ComAssertComRC that returns rc if rc does not succeed */
275	#define ComAssertComRCRetRC(rc) \
276	do { ComAssertComRC(rc); if (!SUCCEEDED(rc)) return (rc); } while (0)
277	/** Special version of ComAssertFailed that returns ret */
278	#define ComAssertFailedRet(ret) \
279	do { ComAssertFailed(); return (ret); } while (0)
280	/** Special version of ComAssertMsgFailed that returns ret */
281	#define ComAssertMsgFailedRet(msg, ret) \
282	do { ComAssertMsgFailed(msg); return (ret); } while (0)
283
284
285	/** Special version of ComAssert that returns void if expr fails */
286	#define ComAssertRetVoid(expr) \
287	do { ComAssert(expr); if (!(expr)) return; } while (0)
288	/** Special version of ComAssertMsg that returns void if expr fails */
289	#define ComAssertMsgRetVoid(expr, a) \
290	do { ComAssertMsg(expr, a); if (!(expr)) return; } while (0)
291	/** Special version of ComAssertRC that returns void if vrc does not succeed */
292	#define ComAssertRCRetVoid(vrc) \
293	do { ComAssertRC(vrc); if (!RT_SUCCESS(vrc)) return; } while (0)
294	/** Special version of ComAssertComRC that returns void if rc does not succeed */
295	#define ComAssertComRCRetVoid(rc) \
296	do { ComAssertComRC(rc); if (!SUCCEEDED(rc)) return; } while (0)
297	/** Special version of ComAssertFailed that returns void */
298	#define ComAssertFailedRetVoid() \
299	do { ComAssertFailed(); return; } while (0)
300	/** Special version of ComAssertMsgFailed that returns void */
301	#define ComAssertMsgFailedRetVoid(msg) \
302	do { ComAssertMsgFailed(msg); return; } while (0)
303
304
305	/** Special version of ComAssert that evaluates eval and breaks if expr fails */
306	#define ComAssertBreak(expr, eval) \
307	if (1) { ComAssert(expr); if (!(expr)) { eval; break; } } else do {} while (0)
308	/** Special version of ComAssertMsg that evaluates eval and breaks if expr fails */
309	#define ComAssertMsgBreak(expr, a, eval) \
310	if (1) { ComAssertMsg(expr, a); if (!(expr)) { eval; break; } } else do {} while (0)
311	/** Special version of ComAssertRC that evaluates eval and breaks if vrc does not succeed */
312	#define ComAssertRCBreak(vrc, eval) \
313	if (1) { ComAssertRC(vrc); if (!RT_SUCCESS(vrc)) { eval; break; } } else do {} while (0)
314	/** Special version of ComAssertFailed that evaluates eval and breaks */
315	#define ComAssertFailedBreak(eval) \
316	if (1) { ComAssertFailed(); { eval; break; } } else do {} while (0)
317	/** Special version of ComAssertMsgFailed that evaluates eval and breaks */
318	#define ComAssertMsgFailedBreak(msg, eval) \
319	if (1) { ComAssertMsgFailed (msg); { eval; break; } } else do {} while (0)
320	/** Special version of ComAssertComRC that evaluates eval and breaks if rc does not succeed */
321	#define ComAssertComRCBreak(rc, eval) \
322	if (1) { ComAssertComRC(rc); if (!SUCCEEDED(rc)) { eval; break; } } else do {} while (0)
323	/** Special version of ComAssertComRC that just breaks if rc does not succeed */
324	#define ComAssertComRCBreakRC(rc) \
325	if (1) { ComAssertComRC(rc); if (!SUCCEEDED(rc)) { break; } } else do {} while (0)
326
327
328	/** Special version of ComAssert that evaluates eval and throws it if expr fails */
329	#define ComAssertThrow(expr, eval) \
330	do { ComAssert(expr); if (!(expr)) { throw (eval); } } while (0)
331	/** Special version of ComAssertRC that evaluates eval and throws it if vrc does not succeed */
332	#define ComAssertRCThrow(vrc, eval) \
333	do { ComAssertRC(vrc); if (!RT_SUCCESS(vrc)) { throw (eval); } } while (0)
334	/** Special version of ComAssertComRC that evaluates eval and throws it if rc does not succeed */
335	#define ComAssertComRCThrow(rc, eval) \
336	do { ComAssertComRC(rc); if (!SUCCEEDED(rc)) { throw (eval); } } while (0)
337	/** Special version of ComAssertComRC that just throws rc if rc does not succeed */
338	#define ComAssertComRCThrowRC(rc) \
339	do { ComAssertComRC(rc); if (!SUCCEEDED(rc)) { throw rc; } } while (0)
340	/** Special version of ComAssert that throws eval */
341	#define ComAssertFailedThrow(eval) \
342	do { ComAssertFailed(); { throw (eval); } } while (0)
343
344	////////////////////////////////////////////////////////////////////////////////
345
346	/**
347	* Checks that the pointer argument is not NULL and returns E_INVALIDARG +
348	* extended error info on failure.
349	* @param arg Input pointer-type argument (strings, interface pointers...)
350	*/
351	#define CheckComArgNotNull(arg) \
352	do { \
353	if (RT_LIKELY((arg) != NULL)) \
354	{ /* likely */ }\
355	else \
356	return setError(E_INVALIDARG, tr("Argument %s is NULL"), #arg); \
357	} while (0)
358
359	/**
360	* Checks that the pointer argument is a valid pointer or NULL and returns
361	* E_INVALIDARG + extended error info on failure.
362	* @param arg Input pointer-type argument (strings, interface pointers...)
363	*/
364	#define CheckComArgMaybeNull(arg) \
365	do { \
366	if (RT_LIKELY(RT_VALID_PTR(arg) \|\| (arg) == NULL)) \
367	{ /* likely */ }\
368	else \
369	return setError(E_INVALIDARG, tr("Argument %s is an invalid pointer"), #arg); \
370	} while (0)
371
372	/**
373	* Checks that the given pointer to an argument is valid and returns
374	* E_POINTER + extended error info otherwise.
375	* @param arg Pointer argument.
376	*/
377	#define CheckComArgPointerValid(arg) \
378	do { \
379	if (RT_LIKELY(RT_VALID_PTR(arg))) \
380	{ /* likely */ }\
381	else \
382	return setError(E_POINTER, \
383	tr("Argument %s points to invalid memory location (%p)"), \
384	#arg, (void *)(arg)); \
385	} while (0)
386
387	/**
388	* Checks that safe array argument is not NULL and returns E_INVALIDARG +
389	* extended error info on failure.
390	* @param arg Input safe array argument (strings, interface pointers...)
391	*/
392	#define CheckComArgSafeArrayNotNull(arg) \
393	do { \
394	if (RT_LIKELY(!ComSafeArrayInIsNull(arg))) \
395	{ /* likely */ }\
396	else \
397	return setError(E_INVALIDARG, tr("Argument %s is NULL"), #arg); \
398	} while (0)
399
400	/**
401	* Checks that a string input argument is valid (not NULL or obviously invalid
402	* pointer), returning E_INVALIDARG + extended error info if invalid.
403	* @param a_bstrIn Input string argument (IN_BSTR).
404	*/
405	#define CheckComArgStr(a_bstrIn) \
406	do { \
407	IN_BSTR const bstrInCheck = (a_bstrIn); /* type check */ \
408	if (RT_LIKELY(RT_VALID_PTR(bstrInCheck))) \
409	{ /* likely */ }\
410	else \
411	return setError(E_INVALIDARG, tr("Argument %s is an invalid pointer"), #a_bstrIn); \
412	} while (0)
413	/**
414	* Checks that the string argument is not a NULL, a invalid pointer or an empty
415	* string, returning E_INVALIDARG + extended error info on failure.
416	* @param a_bstrIn Input string argument (BSTR etc.).
417	*/
418	#define CheckComArgStrNotEmptyOrNull(a_bstrIn) \
419	do { \
420	IN_BSTR const bstrInCheck = (a_bstrIn); /* type check */ \
421	if (RT_LIKELY(RT_VALID_PTR(bstrInCheck) && *(bstrInCheck) != '\0')) \
422	{ /* likely */ }\
423	else \
424	return setError(E_INVALIDARG, tr("Argument %s is empty or an invalid pointer"), #a_bstrIn); \
425	} while (0)
426
427	/**
428	* Converts the Guid input argument (string) to a Guid object, returns with
429	* E_INVALIDARG and error message on failure.
430	*
431	* @param a_Arg Argument.
432	* @param a_GuidVar The Guid variable name.
433	*/
434	#define CheckComArgGuid(a_Arg, a_GuidVar) \
435	do { \
436	Guid tmpGuid(a_Arg); \
437	(a_GuidVar) = tmpGuid; \
438	if (RT_LIKELY((a_GuidVar).isValid())) \
439	{ /* likely */ }\
440	else \
441	return setError(E_INVALIDARG, \
442	tr("GUID argument %s is not valid (\"%ls\")"), #a_Arg, Bstr(a_Arg).raw()); \
443	} while (0)
444
445	/**
446	* Checks that the given expression (that must involve the argument) is true and
447	* returns E_INVALIDARG + extended error info on failure.
448	* @param arg Argument.
449	* @param expr Expression to evaluate.
450	*/
451	#define CheckComArgExpr(arg, expr) \
452	do { \
453	if (RT_LIKELY(!!(expr))) \
454	{ /* likely */ }\
455	else \
456	return setError(E_INVALIDARG, \
457	tr("Argument %s is invalid (must be %s)"), #arg, #expr); \
458	} while (0)
459
460	/**
461	* Checks that the given expression (that must involve the argument) is true and
462	* returns E_INVALIDARG + extended error info on failure. The error message must
463	* be customized.
464	* @param arg Argument.
465	* @param expr Expression to evaluate.
466	* @param msg Parenthesized printf-like expression (must start with a verb,
467	* like "must be one of...", "is not within...").
468	*/
469	#define CheckComArgExprMsg(arg, expr, msg) \
470	do { \
471	if (RT_LIKELY(!!(expr))) \
472	{ /* likely */ }\
473	else \
474	return setError(E_INVALIDARG, tr("Argument %s %s"), \
475	#arg, Utf8StrFmt msg .c_str()); \
476	} while (0)
477
478	/**
479	* Checks that the given pointer to an output argument is valid and returns
480	* E_POINTER + extended error info otherwise.
481	* @param arg Pointer argument.
482	*/
483	#define CheckComArgOutPointerValid(arg) \
484	do { \
485	if (RT_LIKELY(RT_VALID_PTR(arg))) \
486	{ /* likely */ }\
487	else \
488	return setError(E_POINTER, \
489	tr("Output argument %s points to invalid memory location (%p)"), \
490	#arg, (void *)(arg)); \
491	} while (0)
492
493	/**
494	* Checks that the given pointer to an output safe array argument is valid and
495	* returns E_POINTER + extended error info otherwise.
496	* @param arg Safe array argument.
497	*/
498	#define CheckComArgOutSafeArrayPointerValid(arg) \
499	do { \
500	if (RT_LIKELY(!ComSafeArrayOutIsNull(arg))) \
501	{ /* likely */ }\
502	else \
503	return setError(E_POINTER, \
504	tr("Output argument %s points to invalid memory location (%p)"), \
505	#arg, (void*)(arg)); \
506	} while (0)
507
508	/**
509	* Sets the extended error info and returns E_NOTIMPL.
510	*/
511	#define ReturnComNotImplemented() \
512	do { \
513	return setError(E_NOTIMPL, tr("Method %s is not implemented"), __FUNCTION__); \
514	} while (0)
515
516	/**
517	* Declares an empty constructor and destructor for the given class.
518	* This is useful to prevent the compiler from generating the default
519	* ctor and dtor, which in turn allows to use forward class statements
520	* (instead of including their header files) when declaring data members of
521	* non-fundamental types with constructors (which are always called implicitly
522	* by constructors and by the destructor of the class).
523	*
524	* This macro is to be placed within (the public section of) the class
525	* declaration. Its counterpart, DEFINE_EMPTY_CTOR_DTOR, must be placed
526	* somewhere in one of the translation units (usually .cpp source files).
527	*
528	* @param cls class to declare a ctor and dtor for
529	*/
530	#define DECLARE_EMPTY_CTOR_DTOR(cls) cls(); virtual ~cls();
531
532	/**
533	* Defines an empty constructor and destructor for the given class.
534	* See DECLARE_EMPTY_CTOR_DTOR for more info.
535	*/
536	#define DEFINE_EMPTY_CTOR_DTOR(cls) \
537	cls::cls() { /empty/ } \
538	cls::~cls() { /empty/ }
539
540	/**
541	* A variant of 'throw' that hits a debug breakpoint first to make
542	* finding the actual thrower possible.
543	*/
544	#ifdef DEBUG
545	# define DebugBreakThrow(a) \
546	do { \
547	RTAssertDebugBreak(); \
548	throw (a); \
549	} while (0)
550	#else
551	# define DebugBreakThrow(a) throw (a)
552	#endif
553
554	/**
555	* Parent class of VirtualBoxBase which enables translation support (which
556	* Main doesn't have yet, but this provides the tr() function which will one
557	* day provide translations).
558	*
559	* This class sits in between Lockable and VirtualBoxBase only for the one
560	* reason that the USBProxyService wants translation support but is not
561	* implemented as a COM object, which VirtualBoxBase implies.
562	*/
563	class ATL_NO_VTABLE VirtualBoxTranslatable
564	: public Lockable
565	{
566	public:
567
568	/**
569	* Placeholder method with which translations can one day be implemented
570	* in Main. This gets called by the tr() function.
571	* @param context
572	* @param pcszSourceText
573	* @param comment
574	* @return
575	*/
576	static const char translate(const char context,
577	const char *pcszSourceText,
578	const char *comment = 0)
579	{
580	NOREF(context);
581	NOREF(comment);
582	return pcszSourceText;
583	}
584
585	/**
586	* Translates the given text string by calling translate() and passing
587	* the name of the C class as the first argument ("context of
588	* translation"). See VirtualBoxBase::translate() for more info.
589	*
590	* @param aSourceText String to translate.
591	* @param aComment Comment to the string to resolve possible
592	* ambiguities (NULL means no comment).
593	*
594	* @return Translated version of the source string in UTF-8 encoding, or
595	* the source string itself if the translation is not found in the
596	* specified context.
597	*/
598	inline static const char tr(const char pcszSourceText,
599	const char *aComment = NULL)
600	{
601	return VirtualBoxTranslatable::translate(NULL, // getComponentName(), eventually
602	pcszSourceText,
603	aComment);
604	}
605	};
606
607	////////////////////////////////////////////////////////////////////////////////
608	//
609	// VirtualBoxBase
610	//
611	////////////////////////////////////////////////////////////////////////////////
612
613	#define VIRTUALBOXBASE_ADD_VIRTUAL_COMPONENT_METHODS(cls, iface) \
614	virtual const IID& getClassIID() const \
615	{ \
616	return cls::getStaticClassIID(); \
617	} \
618	static const IID& getStaticClassIID() \
619	{ \
620	return COM_IIDOF(iface); \
621	} \
622	virtual const char* getComponentName() const \
623	{ \
624	return cls::getStaticComponentName(); \
625	} \
626	static const char* getStaticComponentName() \
627	{ \
628	return #cls; \
629	}
630
631	/**
632	* VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT:
633	* This macro must be used once in the declaration of any class derived
634	* from VirtualBoxBase. It implements the pure virtual getClassIID() and
635	* getComponentName() methods. If this macro is not present, instances
636	* of a class derived from VirtualBoxBase cannot be instantiated.
637	*
638	* @param X The class name, e.g. "Class".
639	* @param IX The interface name which this class implements, e.g. "IClass".
640	*/
641	#ifdef VBOX_WITH_XPCOM
642	#define VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(cls, iface) \
643	VIRTUALBOXBASE_ADD_VIRTUAL_COMPONENT_METHODS(cls, iface)
644	#else // !VBOX_WITH_XPCOM
645	#define VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(cls, iface) \
646	VIRTUALBOXBASE_ADD_VIRTUAL_COMPONENT_METHODS(cls, iface) \
647	STDMETHOD(InterfaceSupportsErrorInfo)(REFIID riid) \
648	{ \
649	const ATL::_ATL_INTMAP_ENTRY* pEntries = cls::_GetEntries(); \
650	Assert(pEntries); \
651	if (!pEntries) \
652	return S_FALSE; \
653	BOOL bSupports = FALSE; \
654	BOOL bISupportErrorInfoFound = FALSE; \
655	while (pEntries->pFunc != NULL && !bSupports) \
656	{ \
657	if (!bISupportErrorInfoFound) \
658	bISupportErrorInfoFound = InlineIsEqualGUID(*(pEntries->piid), IID_ISupportErrorInfo); \
659	else \
660	bSupports = InlineIsEqualGUID(*(pEntries->piid), riid); \
661	pEntries++; \
662	} \
663	Assert(bISupportErrorInfoFound); \
664	return bSupports ? S_OK : S_FALSE; \
665	}
666	#endif // !VBOX_WITH_XPCOM
667
668	/**
669	* VBOX_TWEAK_INTERFACE_ENTRY:
670	* Macro for defining magic interface entries needed for all interfaces
671	* implemented by any subclass of VirtualBoxBase.
672	*/
673	#ifdef VBOX_WITH_XPCOM
674	#define VBOX_TWEAK_INTERFACE_ENTRY(iface)
675	#else // !VBOX_WITH_XPCOM
676	#define VBOX_TWEAK_INTERFACE_ENTRY(iface) \
677	COM_INTERFACE_ENTRY_AGGREGATE(IID_IMarshal, m_pUnkMarshaler.m_p)
678	#endif // !VBOX_WITH_XPCOM
679
680
681	/**
682	* Abstract base class for all component classes implementing COM
683	* interfaces of the VirtualBox COM library.
684	*
685	* Declares functionality that should be available in all components.
686	*
687	* The object state logic is documented in ObjectState.h.
688	*/
689	class ATL_NO_VTABLE VirtualBoxBase
690	: public VirtualBoxTranslatable,
691	public ATL::CComObjectRootEx<ATL::CComMultiThreadModel>
692	#if !defined (VBOX_WITH_XPCOM)
693	, public ISupportErrorInfo
694	#endif
695	{
696	protected:
697	#ifdef RT_OS_WINDOWS
698	ComPtr<IUnknown> m_pUnkMarshaler;
699	#endif
700
701	HRESULT BaseFinalConstruct();
702	void BaseFinalRelease();
703
704	public:
705	VirtualBoxBase();
706	virtual ~VirtualBoxBase();
707
708	/**
709	* Uninitialization method.
710	*
711	* Must be called by all final implementations (component classes) when the
712	* last reference to the object is released, before calling the destructor.
713	*
714	* @note Never call this method the AutoCaller scope or after the
715	* ObjectState::addCaller() call not paired by
716	* ObjectState::releaseCaller() because it is a guaranteed deadlock.
717	* See AutoUninitSpan and AutoCaller.h/ObjectState.h for details.
718	*/
719	virtual void uninit()
720	{ }
721
722	/**
723	*/
724	ObjectState &getObjectState()
725	{
726	return mState;
727	}
728
729	/**
730	* Pure virtual method for simple run-time type identification without
731	* having to enable C++ RTTI.
732	*
733	* This must be implemented by every subclass deriving from VirtualBoxBase;
734	* use the VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT macro to do that most easily.
735	*/
736	virtual const IID& getClassIID() const = 0;
737
738	/**
739	* Pure virtual method for simple run-time type identification without
740	* having to enable C++ RTTI.
741	*
742	* This must be implemented by every subclass deriving from VirtualBoxBase;
743	* use the VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT macro to do that most easily.
744	*/
745	virtual const char* getComponentName() const = 0;
746
747	/**
748	* Virtual method which determines the locking class to be used for validating
749	* lock order with the standard member lock handle. This method is overridden
750	* in a number of subclasses.
751	*/
752	virtual VBoxLockingClass getLockingClass() const
753	{
754	return LOCKCLASS_OTHEROBJECT;
755	}
756
757	virtual RWLockHandle *lockHandle() const;
758
759	static HRESULT handleUnexpectedExceptions(VirtualBoxBase *const aThis, RT_SRC_POS_DECL);
760
761	static HRESULT setErrorInternal(HRESULT aResultCode,
762	const GUID &aIID,
763	const char *aComponent,
764	Utf8Str aText,
765	bool aWarning,
766	bool aLogIt,
767	LONG aResultDetail = 0);
768	static void clearError(void);
769
770	HRESULT setError(HRESULT aResultCode);
771	HRESULT setError(HRESULT aResultCode, const char *pcsz, ...);
772	HRESULT setError(const ErrorInfo &ei);
773	HRESULT setErrorVrc(int vrc);
774	HRESULT setErrorVrc(int vrc, const char *pcszMsgFmt, ...);
775	HRESULT setErrorBoth(HRESULT hrc, int vrc);
776	HRESULT setErrorBoth(HRESULT hrc, int vrc, const char *pcszMsgFmt, ...);
777	HRESULT setWarning(HRESULT aResultCode, const char *pcsz, ...);
778	HRESULT setErrorNoLog(HRESULT aResultCode, const char *pcsz, ...);
779
780
781	/** Initialize COM for a new thread. */
782	static HRESULT initializeComForThread(void)
783	{
784	#ifndef VBOX_WITH_XPCOM
785	HRESULT hrc = CoInitializeEx(NULL, COINIT_MULTITHREADED \| COINIT_DISABLE_OLE1DDE \| COINIT_SPEED_OVER_MEMORY);
786	AssertComRCReturn(hrc, hrc);
787	#endif
788	return S_OK;
789	}
790
791	/** Uninitializes COM for a dying thread. */
792	static void uninitializeComForThread(void)
793	{
794	#ifndef VBOX_WITH_XPCOM
795	CoUninitialize();
796	#endif
797	}
798
799
800	private:
801	/** Object for representing object state */
802	ObjectState mState;
803
804	/** User-level object lock for subclasses */
805	RWLockHandle *mObjectLock;
806
807	/** Slot of this object in the saFactoryStats array */
808	uint32_t iFactoryStat;
809
810	private:
811	DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(VirtualBoxBase); /* Shuts up MSC warning C4625. */
812	};
813
814	/** Structure for counting the currently existing and ever created objects
815	* for each component name. */
816	typedef struct CLASSFACTORY_STAT
817	{
818	const char *psz;
819	uint64_t current;
820	uint64_t overall;
821	} CLASSFACTORY_STAT;
822
823	/** Maximum number of component names to deal with. There will be debug
824	* assertions if the value is too low. Since the table is global and its
825	* entries are reasonably small, it's not worth squeezing out the last bit. */
826	#define CLASSFACTORYSTATS_MAX 128
827
828	/* global variables (defined in VirtualBoxBase.cpp) */
829	extern CLASSFACTORY_STAT g_aClassFactoryStats[CLASSFACTORYSTATS_MAX];
830	extern RWLockHandle *g_pClassFactoryStatsLock;
831
832	extern void APIDumpComponentFactoryStats();
833
834	/**
835	* Dummy macro that is used to shut down Qt's lupdate tool warnings in some
836	* situations. This macro needs to be present inside (better at the very
837	* beginning) of the declaration of the class that inherits from
838	* VirtualBoxTranslatable, to make lupdate happy.
839	*/
840	#define Q_OBJECT
841
842	////////////////////////////////////////////////////////////////////////////////
843
844	////////////////////////////////////////////////////////////////////////////////
845
846
847	/**
848	* Simple template that manages data structure allocation/deallocation
849	* and supports data pointer sharing (the instance that shares the pointer is
850	* not responsible for memory deallocation as opposed to the instance that
851	* owns it).
852	*/
853	template <class D>
854	class Shareable
855	{
856	public:
857
858	Shareable() : mData(NULL), mIsShared(FALSE) {}
859	~Shareable() { free(); }
860
861	void allocate() { attach(new D); }
862
863	virtual void free() {
864	if (mData) {
865	if (!mIsShared)
866	delete mData;
867	mData = NULL;
868	mIsShared = false;
869	}
870	}
871
872	void attach(D *d) {
873	AssertMsg(d, ("new data must not be NULL"));
874	if (d && mData != d) {
875	if (mData && !mIsShared)
876	delete mData;
877	mData = d;
878	mIsShared = false;
879	}
880	}
881
882	void attach(Shareable &d) {
883	AssertMsg(
884	d.mData == mData \|\| !d.mIsShared,
885	("new data must not be shared")
886	);
887	if (this != &d && !d.mIsShared) {
888	attach(d.mData);
889	d.mIsShared = true;
890	}
891	}
892
893	void share(D *d) {
894	AssertMsg(d, ("new data must not be NULL"));
895	if (mData != d) {
896	if (mData && !mIsShared)
897	delete mData;
898	mData = d;
899	mIsShared = true;
900	}
901	}
902
903	void share(const Shareable &d) { share(d.mData); }
904
905	void attachCopy(const D *d) {
906	AssertMsg(d, ("data to copy must not be NULL"));
907	if (d)
908	attach(new D(*d));
909	}
910
911	void attachCopy(const Shareable &d) {
912	attachCopy(d.mData);
913	}
914
915	virtual D *detach() {
916	D *d = mData;
917	mData = NULL;
918	mIsShared = false;
919	return d;
920	}
921
922	D *data() const {
923	return mData;
924	}
925
926	D *operator->() const {
927	AssertMsg(mData, ("data must not be NULL"));
928	return mData;
929	}
930
931	bool isNull() const { return mData == NULL; }
932	bool operator!() const { return isNull(); }
933
934	bool isShared() const { return mIsShared; }
935
936	protected:
937
938	D *mData;
939	bool mIsShared;
940	};
941
942	/**
943	* Simple template that enhances Shareable<> and supports data
944	* backup/rollback/commit (using the copy constructor of the managed data
945	* structure).
946	*/
947	template<class D>
948	class Backupable : public Shareable<D>
949	{
950	public:
951
952	Backupable() : Shareable<D>(), mBackupData(NULL) {}
953
954	void free()
955	{
956	AssertMsg(this->mData \|\| !mBackupData, ("backup must be NULL if data is NULL"));
957	rollback();
958	Shareable<D>::free();
959	}
960
961	D *detach()
962	{
963	AssertMsg(this->mData \|\| !mBackupData, ("backup must be NULL if data is NULL"));
964	rollback();
965	return Shareable<D>::detach();
966	}
967
968	void share(const Backupable &d)
969	{
970	AssertMsg(!d.isBackedUp(), ("data to share must not be backed up"));
971	if (!d.isBackedUp())
972	Shareable<D>::share(d.mData);
973	}
974
975	/**
976	* Stores the current data pointer in the backup area, allocates new data
977	* using the copy constructor on current data and makes new data active.
978	*
979	* @deprecated Use backupEx to avoid throwing wild out-of-memory exceptions.
980	*/
981	void backup()
982	{
983	AssertMsg(this->mData, ("data must not be NULL"));
984	if (this->mData && !mBackupData)
985	{
986	D pNewData = new D(this->mData);
987	mBackupData = this->mData;
988	this->mData = pNewData;
989	}
990	}
991
992	/**
993	* Stores the current data pointer in the backup area, allocates new data
994	* using the copy constructor on current data and makes new data active.
995	*
996	* @returns S_OK, E_OUTOFMEMORY or E_FAIL (internal error).
997	*/
998	HRESULT backupEx()
999	{
1000	AssertMsgReturn(this->mData, ("data must not be NULL"), E_FAIL);
1001	if (this->mData && !mBackupData)
1002	{
1003	try
1004	{
1005	D pNewData = new D(this->mData);
1006	mBackupData = this->mData;
1007	this->mData = pNewData;
1008	}
1009	catch (std::bad_alloc &)
1010	{
1011	return E_OUTOFMEMORY;
1012	}
1013	}
1014	return S_OK;
1015	}
1016
1017	/**
1018	* Deletes new data created by #backup() and restores previous data pointer
1019	* stored in the backup area, making it active again.
1020	*/
1021	void rollback()
1022	{
1023	if (this->mData && mBackupData)
1024	{
1025	delete this->mData;
1026	this->mData = mBackupData;
1027	mBackupData = NULL;
1028	}
1029	}
1030
1031	/**
1032	* Commits current changes by deleting backed up data and clearing up the
1033	* backup area. The new data pointer created by #backup() remains active
1034	* and becomes the only managed pointer.
1035	*
1036	* This method is much faster than #commitCopy() (just a single pointer
1037	* assignment operation), but makes the previous data pointer invalid
1038	* (because it is freed). For this reason, this method must not be
1039	* used if it's possible that data managed by this instance is shared with
1040	* some other Shareable instance. See #commitCopy().
1041	*/
1042	void commit()
1043	{
1044	if (this->mData && mBackupData)
1045	{
1046	if (!this->mIsShared)
1047	delete mBackupData;
1048	mBackupData = NULL;
1049	this->mIsShared = false;
1050	}
1051	}
1052
1053	/**
1054	* Commits current changes by assigning new data to the previous data
1055	* pointer stored in the backup area using the assignment operator.
1056	* New data is deleted, the backup area is cleared and the previous data
1057	* pointer becomes active and the only managed pointer.
1058	*
1059	* This method is slower than #commit(), but it keeps the previous data
1060	* pointer valid (i.e. new data is copied to the same memory location).
1061	* For that reason it's safe to use this method on instances that share
1062	* managed data with other Shareable instances.
1063	*/
1064	void commitCopy()
1065	{
1066	if (this->mData && mBackupData)
1067	{
1068	mBackupData = (this->mData);
1069	delete this->mData;
1070	this->mData = mBackupData;
1071	mBackupData = NULL;
1072	}
1073	}
1074
1075	void assignCopy(const D *pData)
1076	{
1077	AssertMsg(this->mData, ("data must not be NULL"));
1078	AssertMsg(pData, ("data to copy must not be NULL"));
1079	if (this->mData && pData)
1080	{
1081	if (!mBackupData)
1082	{
1083	D pNewData = new D(pData);
1084	mBackupData = this->mData;
1085	this->mData = pNewData;
1086	}
1087	else
1088	this->mData = pData;
1089	}
1090	}
1091
1092	void assignCopy(const Backupable &d)
1093	{
1094	assignCopy(d.mData);
1095	}
1096
1097	bool isBackedUp() const
1098	{
1099	return mBackupData != NULL;
1100	}
1101
1102	D *backedUpData() const
1103	{
1104	return mBackupData;
1105	}
1106
1107	protected:
1108
1109	D *mBackupData;
1110	};
1111
1112	#endif // !____H_VIRTUALBOXBASEIMPL
1113

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

source: vbox/trunk/src/VBox/Main/include/VirtualBoxBase.h@ 63240

Download in other formats: