1//
2// UUID.h
3//
4// Library: Foundation
5// Package: UUID
6// Module: UUID
7//
8// Definition of the UUID class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef Foundation_UUID_INCLUDED
18#define Foundation_UUID_INCLUDED
19
20
21#include "Poco/Foundation.h"
22
23
24namespace Poco {
25
26
27class Foundation_API UUID
28 /// A UUID is an identifier that is unique across both space and time,
29 /// with respect to the space of all UUIDs. Since a UUID is a fixed
30 /// size and contains a time field, it is possible for values to
31 /// rollover (around A.D. 3400, depending on the specific algorithm
32 /// used). A UUID can be used for multiple purposes, from tagging
33 /// objects with an extremely short lifetime, to reliably identifying
34 /// very persistent objects across a network.
35 ///
36 /// This class implements a Universal Unique Identifier,
37 /// as specified in Appendix A of the DCE 1.1 Remote Procedure
38 /// Call Specification (http://www.opengroup.org/onlinepubs/9629399/),
39 /// RFC 2518 (WebDAV), section 6.4.1 and the UUIDs and GUIDs internet
40 /// draft by Leach/Salz from February, 1998
41 /// (http://www.ics.uci.edu/~ejw/authoring/uuid-guid/draft-leach-uuids-guids-01.txt)
42 /// and also http://tools.ietf.org/html/draft-mealling-uuid-urn-05
43{
44public:
45 enum Version
46 {
47 UUID_TIME_BASED = 0x01,
48 UUID_DCE_UID = 0x02,
49 UUID_NAME_BASED = 0x03,
50 UUID_RANDOM = 0x04,
51 UUID_NAME_BASED_SHA1 = 0x05
52
53 };
54
55 UUID();
56 /// Creates a nil (all zero) UUID.
57
58 UUID(const UUID& uuid);
59 /// Copy constructor.
60
61 explicit UUID(const std::string& uuid);
62 /// Parses the UUID from a string.
63
64 explicit UUID(const char* uuid);
65 /// Parses the UUID from a string.
66
67 ~UUID();
68 /// Destroys the UUID.
69
70 UUID& operator = (const UUID& uuid);
71 /// Assignment operator.
72
73 void swap(UUID& uuid);
74 /// Swaps the UUID with another one.
75
76 void parse(const std::string& uuid);
77 /// Parses the UUID from its string representation.
78
79 bool tryParse(const std::string& uuid);
80 /// Tries to interpret the given string as an UUID.
81 /// If the UUID is syntactically valid, assigns the
82 /// members and returns true. Otherwise leaves the
83 /// object unchanged and returns false.
84
85 std::string toString() const;
86 /// Returns a string representation of the UUID consisting
87 /// of groups of hexadecimal digits separated by hyphens.
88
89 void copyFrom(const char* buffer);
90 /// Copies the UUID (16 bytes) from a buffer or byte array.
91 /// The UUID fields are expected to be
92 /// stored in network byte order.
93 /// The buffer need not be aligned.
94
95 void copyTo(char* buffer) const;
96 /// Copies the UUID to the buffer. The fields
97 /// are in network byte order.
98 /// The buffer need not be aligned.
99 /// There must have room for at least 16 bytes.
100
101 Version version() const;
102 /// Returns the version of the UUID.
103
104 int variant() const;
105 /// Returns the variant number of the UUID:
106 /// - 0 reserved for NCS backward compatibility
107 /// - 2 the Leach-Salz variant (used by this class)
108 /// - 6 reserved, Microsoft Corporation backward compatibility
109 /// - 7 reserved for future definition
110
111 bool operator == (const UUID& uuid) const;
112 bool operator != (const UUID& uuid) const;
113 bool operator < (const UUID& uuid) const;
114 bool operator <= (const UUID& uuid) const;
115 bool operator > (const UUID& uuid) const;
116 bool operator >= (const UUID& uuid) const;
117
118 bool isNull() const;
119 /// Returns true iff the UUID is nil (in other words,
120 /// consists of all zeros).
121
122 static const UUID& null();
123 /// Returns a null/nil UUID.
124
125 static const UUID& dns();
126 /// Returns the namespace identifier for the DNS namespace.
127
128 static const UUID& uri();
129 /// Returns the namespace identifier for the URI (former URL) namespace.
130
131 static const UUID& oid();
132 /// Returns the namespace identifier for the OID namespace.
133
134 static const UUID& x500();
135 /// Returns the namespace identifier for the X500 namespace.
136
137protected:
138 UUID(UInt32 timeLow, UInt32 timeMid, UInt32 timeHiAndVersion, UInt16 clockSeq, UInt8 node[]);
139 UUID(const char* bytes, Version version);
140 int compare(const UUID& uuid) const;
141 static void appendHex(std::string& str, UInt8 n);
142 static void appendHex(std::string& str, UInt16 n);
143 static void appendHex(std::string& str, UInt32 n);
144 static Int16 nibble(char hex);
145 void fromNetwork();
146 void toNetwork();
147
148private:
149 UInt32 _timeLow;
150 UInt16 _timeMid;
151 UInt16 _timeHiAndVersion;
152 UInt16 _clockSeq;
153 UInt8 _node[6];
154
155 friend class UUIDGenerator;
156};
157
158
159//
160// inlines
161//
162inline bool UUID::operator == (const UUID& uuid) const
163{
164 return compare(uuid) == 0;
165}
166
167
168inline bool UUID::operator != (const UUID& uuid) const
169{
170 return compare(uuid) != 0;
171}
172
173
174inline bool UUID::operator < (const UUID& uuid) const
175{
176 return compare(uuid) < 0;
177}
178
179
180inline bool UUID::operator <= (const UUID& uuid) const
181{
182 return compare(uuid) <= 0;
183}
184
185
186inline bool UUID::operator > (const UUID& uuid) const
187{
188 return compare(uuid) > 0;
189}
190
191
192inline bool UUID::operator >= (const UUID& uuid) const
193{
194 return compare(uuid) >= 0;
195}
196
197
198inline UUID::Version UUID::version() const
199{
200 return Version(_timeHiAndVersion >> 12);
201}
202
203
204inline bool UUID::isNull() const
205{
206 return compare(null()) == 0;
207}
208
209
210inline void swap(UUID& u1, UUID& u2)
211{
212 u1.swap(u2);
213}
214
215
216} // namespace Poco
217
218
219#endif // Foundation_UUID_INCLUDED
220