Guid.h@ 52664

Last change on this file since 52664 was 51689, checked in by vboxsync, 10 years ago
Main/Guid: typos
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 13.5 KB

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

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

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

Download in other formats: