VirtualBoxBase.h@ 88539

Last change on this file since 88539 was 82968, checked in by vboxsync, 5 years ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.2 KB

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

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

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

Download in other formats: