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 | |
24 | namespace Poco { |
25 | |
26 | |
27 | class 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 | { |
44 | public: |
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 | |
137 | protected: |
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 | |
148 | private: |
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 | // |
162 | inline bool UUID::operator == (const UUID& uuid) const |
163 | { |
164 | return compare(uuid) == 0; |
165 | } |
166 | |
167 | |
168 | inline bool UUID::operator != (const UUID& uuid) const |
169 | { |
170 | return compare(uuid) != 0; |
171 | } |
172 | |
173 | |
174 | inline bool UUID::operator < (const UUID& uuid) const |
175 | { |
176 | return compare(uuid) < 0; |
177 | } |
178 | |
179 | |
180 | inline bool UUID::operator <= (const UUID& uuid) const |
181 | { |
182 | return compare(uuid) <= 0; |
183 | } |
184 | |
185 | |
186 | inline bool UUID::operator > (const UUID& uuid) const |
187 | { |
188 | return compare(uuid) > 0; |
189 | } |
190 | |
191 | |
192 | inline bool UUID::operator >= (const UUID& uuid) const |
193 | { |
194 | return compare(uuid) >= 0; |
195 | } |
196 | |
197 | |
198 | inline UUID::Version UUID::version() const |
199 | { |
200 | return Version(_timeHiAndVersion >> 12); |
201 | } |
202 | |
203 | |
204 | inline bool UUID::isNull() const |
205 | { |
206 | return compare(null()) == 0; |
207 | } |
208 | |
209 | |
210 | inline 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 | |