Guid.h@ 69107

Last change on this file since 69107 was 69107, checked in by vboxsync, 7 years ago
include/VBox/: (C) year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 13.6 KB

Line
1	/* $Id: Guid.h 69107 2017-10-17 10:53:48Z vboxsync $ */
2	/** @file
3	* MS COM / XPCOM Abstraction Layer - Guid class declaration.
4	*/
5
6	/*
7	* Copyright (C) 2006-2017 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	* 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_Guid_h
28	#define ___VBox_com_Guid_h
29
30	/* Make sure all the stdint.h macros are included - must come first! */
31	#ifndef __STDC_LIMIT_MACROS
32	# define __STDC_LIMIT_MACROS
33	#endif
34	#ifndef __STDC_CONSTANT_MACROS
35	# define __STDC_CONSTANT_MACROS
36	#endif
37
38	#include "VBox/com/string.h"
39
40	#include <iprt/uuid.h>
41	#include <iprt/err.h>
42
43
44	/** @defgroup grp_com_guid GUID Class
45	* @ingroup grp_com
46	* @{
47	*/
48
49	namespace com
50	{
51
52	typedef enum GuidState_t
53	{
54	GUID_ZERO,
55	GUID_NORMAL,
56	GUID_INVALID
57	} GuidState_t;
58
59	/**
60	* Helper class that represents the UUID type and hides platform-specific
61	* implementation details.
62	*/
63	class Guid
64	{
65	public:
66
67	Guid()
68	{
69	::RTUuidClear(&mUuid);
70	mGuidState = GUID_ZERO;
71	dbg_refresh();
72	}
73
74	Guid(const Guid &that)
75	{
76	mUuid = that.mUuid;
77	mGuidState = that.mGuidState;
78	dbg_refresh();
79	}
80
81	Guid(const RTUUID &that)
82	{
83	mGuidState = GUID_NORMAL;
84	mUuid = that;
85	if (isZero())
86	mGuidState = GUID_ZERO;
87	dbg_refresh();
88	}
89
90	Guid(const GUID &that)
91	{
92	AssertCompileSize(GUID, sizeof(RTUUID));
93	::memcpy(&mUuid, &that, sizeof(GUID));
94	mGuidState = GUID_NORMAL;
95	if (isZero())
96	mGuidState = GUID_ZERO;
97	dbg_refresh();
98	}
99
100	/**
101	* Construct a GUID from a string.
102	*
103	* @param that The UUID string. Can be with or without the curly
104	* brackets. Empty strings are translated to a zero
105	* GUID, and strings which are not confirming to
106	* valid GUID string representations are marked as
107	* invalid.
108	*/
109	Guid(const char *that)
110	{
111	initString(that);
112	}
113
114	/**
115	* Construct a GUID from a BSTR.
116	*
117	* @param that The UUID BSTR. Can be with or without the curly
118	* brackets. Empty strings are translated to a zero
119	* GUID, and strings which are not confirming to
120	* valid GUID string representations are marked as
121	* invalid.
122	*/
123	Guid(CBSTR that)
124	{
125	initBSTR(that);
126	}
127
128	/**
129	* Construct a GUID from a Utf8Str.
130	*
131	* @param that The UUID Utf8Str. Can be with or without the curly
132	* brackets. Empty strings are translated to a zero
133	* GUID, and strings which are not confirming to
134	* valid GUID string representations are marked as
135	*/
136	Guid(const Utf8Str &that)
137	{
138	initString(that.c_str());
139	}
140
141	/**
142	* Construct a GUID from a RTCString.
143	*
144	* @param that The UUID RTCString. Can be with or without the curly
145	* brackets. Empty strings are translated to a zero
146	* GUID, and strings which are not confirming to
147	* valid GUID string representations are marked as
148	*/
149	Guid(const RTCString &that)
150	{
151	initString(that.c_str());
152	}
153
154	/**
155	* Construct a GUID from a Bstr.
156	*
157	* @param that The UUID Bstr. Can be with or without the curly
158	* brackets. Empty strings are translated to a zero
159	* GUID, and strings which are not confirming to
160	* valid GUID string representations are marked as
161	*/
162	Guid(const Bstr &that)
163	{
164	initBSTR(that.raw());
165	}
166
167	Guid& operator=(const Guid &that)
168	{
169	mUuid = that.mUuid;
170	mGuidState = that.mGuidState;
171	dbg_refresh();
172	return *this;
173	}
174
175	Guid& operator=(const RTUUID &guid)
176	{
177	mUuid = guid;
178	mGuidState = GUID_NORMAL;
179	if (isZero())
180	mGuidState = GUID_ZERO;
181	dbg_refresh();
182	return *this;
183	}
184
185	Guid& operator=(const GUID &guid)
186	{
187	AssertCompileSize(GUID, sizeof(RTUUID));
188	::memcpy(&mUuid, &guid, sizeof(GUID));
189	mGuidState = GUID_NORMAL;
190	if (isZero())
191	mGuidState = GUID_ZERO;
192	dbg_refresh();
193	return *this;
194	}
195
196	Guid& operator=(const char *str)
197	{
198	if (!str \|\| !*str)
199	{
200	::RTUuidClear(&mUuid);
201	mGuidState = GUID_ZERO;
202	}
203	else
204	{
205	mGuidState = GUID_NORMAL;
206	int rc = ::RTUuidFromStr(&mUuid, str);
207	if (RT_FAILURE(rc))
208	{
209	::RTUuidClear(&mUuid);
210	mGuidState = GUID_INVALID;
211	}
212	else if (isZero())
213	mGuidState = GUID_ZERO;
214	}
215	dbg_refresh();
216	return *this;
217	}
218
219	Guid& operator=(CBSTR str)
220	{
221	if (!str \|\| !*str)
222	{
223	::RTUuidClear(&mUuid);
224	mGuidState = GUID_ZERO;
225	}
226	else
227	{
228	mGuidState = GUID_NORMAL;
229	int rc = ::RTUuidFromUtf16(&mUuid, str);
230	if (RT_FAILURE(rc))
231	{
232	::RTUuidClear(&mUuid);
233	mGuidState = GUID_INVALID;
234	}
235	else if (isZero())
236	mGuidState = GUID_ZERO;
237	}
238	dbg_refresh();
239	return *this;
240	}
241
242	Guid& operator=(const Utf8Str &str)
243	{
244	return operator=(str.c_str());
245	}
246
247	Guid& operator=(const RTCString &str)
248	{
249	return operator=(str.c_str());
250	}
251
252	Guid& operator=(const Bstr &str)
253	{
254	return operator=(str.raw());
255	}
256
257	void create()
258	{
259	::RTUuidCreate(&mUuid);
260	mGuidState = GUID_NORMAL;
261	dbg_refresh();
262	}
263
264	void clear()
265	{
266	::RTUuidClear(&mUuid);
267	mGuidState = GUID_ZERO;
268	dbg_refresh();
269	}
270
271	/**
272	* Convert the GUID to a string.
273	*
274	* @returns String object containing the formatted GUID.
275	* @throws std::bad_alloc
276	*/
277	Utf8Str toString() const
278	{
279	if (mGuidState == GUID_INVALID)
280	{
281	/* What to return in case of wrong Guid */
282	return Utf8Str("00000000-0000-0000-0000-00000000000");
283	}
284
285	char buf[RTUUID_STR_LENGTH];
286	::memset(buf, '\0', sizeof(buf));
287	::RTUuidToStr(&mUuid, buf, sizeof(buf));
288
289	return Utf8Str(buf);
290	}
291
292	/**
293	* Like toString, but encloses the returned string in curly brackets.
294	*
295	* @returns String object containing the formatted GUID in curly brackets.
296	* @throws std::bad_alloc
297	*/
298	Utf8Str toStringCurly() const
299	{
300	if (mGuidState == GUID_INVALID)
301	{
302	/* What to return in case of wrong Guid */
303	return Utf8Str("{00000000-0000-0000-0000-00000000000}");
304	}
305
306	char buf[RTUUID_STR_LENGTH + 2];
307	::memset(buf, '\0', sizeof(buf));
308	::RTUuidToStr(&mUuid, buf + 1, sizeof(buf) - 2);
309	buf[0] = '{';
310	buf[sizeof(buf) - 2] = '}';
311
312	return Utf8Str(buf);
313	}
314
315	/**
316	* Convert the GUID to a string.
317	*
318	* @returns Bstr object containing the formatted GUID.
319	* @throws std::bad_alloc
320	*/
321	Bstr toUtf16() const
322	{
323	if (mGuidState == GUID_INVALID)
324	{
325	/* What to return in case of wrong Guid */
326	return Bstr("00000000-0000-0000-0000-00000000000");
327	}
328
329	RTUTF16 buf[RTUUID_STR_LENGTH];
330	::memset(buf, '\0', sizeof(buf));
331	::RTUuidToUtf16(&mUuid, buf, RT_ELEMENTS(buf));
332
333	return Bstr(buf);
334	}
335
336	bool isValid() const
337	{
338	return mGuidState != GUID_INVALID;
339	}
340
341	bool isZero() const
342	{
343	return mGuidState == GUID_ZERO;
344	}
345
346	bool operator==(const Guid &that) const { return ::RTUuidCompare(&mUuid, &that.mUuid) == 0; }
347	bool operator==(const RTUUID &guid) const { return ::RTUuidCompare(&mUuid, &guid) == 0; }
348	bool operator==(const GUID &guid) const { return ::RTUuidCompare(&mUuid, (PRTUUID)&guid) == 0; }
349	bool operator!=(const Guid &that) const { return !operator==(that); }
350	bool operator!=(const GUID &guid) const { return !operator==(guid); }
351	bool operator!=(const RTUUID &guid) const { return !operator==(guid); }
352	bool operator<(const Guid &that) const { return ::RTUuidCompare(&mUuid, &that.mUuid) < 0; }
353	bool operator<(const GUID &guid) const { return ::RTUuidCompare(&mUuid, (PRTUUID)&guid) < 0; }
354	bool operator<(const RTUUID &guid) const { return ::RTUuidCompare(&mUuid, &guid) < 0; }
355
356	/**
357	* To directly copy the contents to a GUID, or for passing it as an input
358	* parameter of type (const GUID ), the compiler converts. /
359	const GUID &ref() const
360	{
361	return (const GUID )&mUuid;
362	}
363
364	/**
365	* To pass instances to printf-like functions.
366	*/
367	PCRTUUID raw() const
368	{
369	return (PCRTUUID)&mUuid;
370	}
371
372	#if !defined(VBOX_WITH_XPCOM)
373
374	/** To assign instances to OUT_GUID parameters from within the interface
375	* method. */
376	const Guid &cloneTo(GUID *pguid) const
377	{
378	if (pguid)
379	::memcpy(pguid, &mUuid, sizeof(GUID));
380	return *this;
381	}
382
383	/** To pass instances as OUT_GUID parameters to interface methods. */
384	GUID *asOutParam()
385	{
386	return (GUID *)&mUuid;
387	}
388
389	#else
390
391	/** To assign instances to OUT_GUID parameters from within the
392	* interface method */
393	const Guid &cloneTo(nsID **ppGuid) const
394	{
395	if (ppGuid)
396	ppGuid = (nsID )nsMemory::Clone(&mUuid, sizeof(nsID));
397
398	return *this;
399	}
400
401	/**
402	* Internal helper class for asOutParam().
403	*
404	* This takes a GUID reference in the constructor and copies the mUuid from
405	* the method to that instance in its destructor.
406	*/
407	class GuidOutParam
408	{
409	GuidOutParam(Guid &guid)
410	: ptr(0),
411	outer(guid)
412	{
413	outer.clear();
414	}
415
416	nsID *ptr;
417	Guid &outer;
418	GuidOutParam(const GuidOutParam &that); // disabled
419	GuidOutParam &operator=(const GuidOutParam &that); // disabled
420	public:
421	operator nsID**() { return &ptr; }
422	~GuidOutParam()
423	{
424	if (ptr && outer.isZero())
425	{
426	outer = *ptr;
427	outer.dbg_refresh();
428	nsMemory::Free(ptr);
429	}
430	}
431	friend class Guid;
432	};
433
434	/** to pass instances as OUT_GUID parameters to interface methods */
435	GuidOutParam asOutParam() { return GuidOutParam(*this); }
436
437	#endif
438
439	/**
440	* Static immutable empty (zero) object. May be used for comparison purposes.
441	*/
442	static const Guid Empty;
443
444	private:
445	void initString(const char *that)
446	{
447	if (!that \|\| !*that)
448	{
449	::RTUuidClear(&mUuid);
450	mGuidState = GUID_ZERO;
451	}
452	else
453	{
454	mGuidState = GUID_NORMAL;
455	int rc = ::RTUuidFromStr(&mUuid, that);
456	if (RT_FAILURE(rc))
457	{
458	::RTUuidClear(&mUuid);
459	mGuidState = GUID_INVALID;
460	}
461	else if (isZero())
462	mGuidState = GUID_ZERO;
463	}
464	dbg_refresh();
465	}
466
467	void initBSTR(CBSTR that)
468	{
469	if (!that \|\| !*that)
470	{
471	::RTUuidClear(&mUuid);
472	mGuidState = GUID_ZERO;
473	}
474	else
475	{
476	mGuidState = GUID_NORMAL;
477	int rc = ::RTUuidFromUtf16(&mUuid, that);
478	if (RT_FAILURE(rc))
479	{
480	::RTUuidClear(&mUuid);
481	mGuidState = GUID_INVALID;
482	}
483	else if (isZero())
484	mGuidState = GUID_ZERO;
485	}
486	dbg_refresh();
487	}
488
489	/**
490	* Refresh the debug-only UUID string.
491	*
492	* In debug code, refresh the UUID string representatino for debugging;
493	* must be called every time the internal uuid changes; compiles to nothing
494	* in release code.
495	*/
496	inline void dbg_refresh()
497	{
498	#ifdef DEBUG
499	switch (mGuidState)
500	{
501	case GUID_ZERO:
502	case GUID_NORMAL:
503	::RTUuidToStr(&mUuid, mszUuid, RTUUID_STR_LENGTH);
504	break;
505	default:
506	::memset(mszUuid, '\0', sizeof(mszUuid));
507	::RTStrCopy(mszUuid, sizeof(mszUuid), "INVALID");
508	break;
509	}
510	m_pcszUUID = mszUuid;
511	#endif
512	}
513
514	/** The UUID. */
515	RTUUID mUuid;
516
517	GuidState_t mGuidState;
518
519	#ifdef DEBUG
520	/** String representation of mUuid for printing in the debugger. */
521	char mszUuid[RTUUID_STR_LENGTH];
522	/** Another string variant for the debugger, points to szUUID. */
523	const char *m_pcszUUID;
524	#endif
525	};
526
527	} /* namespace com */
528
529	/** @} */
530
531	#endif /* !___VBox_com_Guid_h */
532

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

source: vbox/trunk/include/VBox/com/Guid.h@ 69107

Download in other formats: