xref: /aoo41x/main/sal/inc/rtl/uuid.h (revision 514f4c20)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 #ifndef _RTL_UUID_H_
24 #define _RTL_UUID_H_
25 
26 
27 #include <sal/types.h>
28 #include <rtl/string.h>
29 
30 /**
31    @HTML
32    @file
33    Specification (from draft-leach-uuids-guids-01.txt )
34 
35    <p>
36    A UUID is an identifier that is unique across both space and time,
37    with respect to the space of all UUIDs. To be precise, the UUID
38    consists of a finite bit space. Thus, collision cannot be avoided in
39    principle. A UUID can be used for multiple purposes, from tagging objects
40    with an extremely short lifetime, to reliably identifying very persistent
41    objects across a network.
42 
43    <p>
44 	The generation of UUIDs does not require that a registration
45 	authority be contacted for each identifier. Instead, Version 4 UUIDs are
46     generated from (pseudo unique) sequences of (pseudo) random bits.
47  */
48 
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52 
53 /** Generates a new Version 4 (random number based) UUID (Universally Unique
54     IDentifier).
55 
56 	@param pTargetUUID          pointer to at least 16 bytes of memory. After the call it contains
57 	                            the newly generated uuid in network byte order.
58 	@param pPredecessorUUID     ignored (was used when this function returned
59                                 Version 1 instead of Version 4 UUIDs).
60 	@param bUseEthernetAddress  ignored (was used when this function returned
61                                 Version 1 instead of Version 4 UUIDs).
62  */
63 void SAL_CALL rtl_createUuid( sal_uInt8 *pTargetUUID ,
64 							  const sal_uInt8 *pPredecessorUUID,
65 							  sal_Bool bUseEthernetAddress );
66 
67 /** Compare two UUID's lexically
68 
69 	<p>
70 	Note:   lexical ordering is not temporal ordering!
71 	<p>
72 	Note:   For equalnesschecking, a memcmp(pUUID1,pUUID2,16) is more efficient
73 
74 	@return
75 	<ul>
76 	<li>-1   u1 is lexically before u2
77 	<li>0   u1 is equal to u2
78 	<li>1   u1 is lexically after u2
79 	</ul>
80 
81  */
82 sal_Int32 SAL_CALL rtl_compareUuid( const sal_uInt8 *pUUID1 , const sal_uInt8 *pUUID2 );
83 
84 /** Creates named UUIDs.
85 
86 	<p>
87 	The version 3 UUID is meant for generating UUIDs from <em>names</em> that
88 	are drawn from, and unique within, some <em>name space</em>. Some examples
89 	of names (and, implicitly, name spaces) might be DNS names, URLs, ISO
90 	Object IDs (OIDs), reserved words in a programming language, or X.500
91 	Distinguished Names (DNs); thus, the concept of name and name space
92 	should be broadly construed, and not limited to textual names.
93 
94 	<p>
95 	The requirements for such UUIDs are as follows:
96 
97 	<ul>
98 	<li> The UUIDs generated at different times from the same name in the
99          same namespace MUST be equal
100 
101 	<li> The UUIDs generated from two different names in the same namespace
102 	     should be different (with very high probability)
103 
104 	<li> The UUIDs generated from the same name in two different namespaces
105 	     should be different with (very high probability)
106 
107 	<li> If two UUIDs that were generated from names are equal, then they
108 	     were generated from the same name in the same namespace (with very
109 	     high probability).
110 	</ul>
111 
112 	@param pTargetUUID pointer to at least 16 bytes of memory. After the call
113 	                   it contains the newly generated uuid in network byte order.
114 	@param pNameSpaceUUID The namespace uuid. Below are some predefined ones,
115 	                      but any arbitray uuid can be used as namespace.
116 
117 	@param pName the name
118  */
119 void SAL_CALL rtl_createNamedUuid(
120 	sal_uInt8  *pTargetUUID,
121 	const sal_uInt8  *pNameSpaceUUID,
122 	const rtl_String *pName
123 	);
124 
125 
126 
127 /*
128 	Predefined Namespaces
129 	(Use them the following way : sal_uInt8 aNsDNS[16])  = RTL_UUID_NAMESPACE_DNS;
130  */
131 /** namesapce DNS
132 
133 	<p>
134 	(Use them the following way : sal_uInt8 aNsDNS[16])  = RTL_UUID_NAMESPACE_DNS;
135 	<p>
136    6ba7b810-9dad-11d1-80b4-00c04fd430c8 */
137 #define RTL_UUID_NAMESPACE_DNS {\
138       0x6b,0xa7,0xb8,0x10,\
139       0x9d,0xad,\
140       0x11,0xd1,\
141       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
142     }
143 
144 /** namespace URL
145 
146    <p>
147    6ba7b811-9dad-11d1-80b4-00c04fd430c8 */
148 #define RTL_UUID_NAMESPACE_URL { \
149       0x6b, 0xa7, 0xb8, 0x11,\
150       0x9d, 0xad,\
151       0x11, 0xd1,\
152       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
153     }
154 
155 /** namespace oid
156 
157 	<p>
158 	6ba7b812-9dad-11d1-80b4-00c04fd430c8 */
159 #define RTL_UUID_NAMESPACE_OID {\
160       0x6b, 0xa7, 0xb8, 0x12,\
161       0x9d, 0xad,\
162       0x11, 0xd1,\
163       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
164     }
165 
166 /** namespace X500
167 
168 	<p>
169 	6ba7b814-9dad-11d1-80b4-00c04fd430c8 */
170 #define RTL_UUID_NAMESPACE_X500 {\
171       0x6b, 0xa7, 0xb8, 0x14,\
172       0x9d, 0xad,\
173       0x11, 0xd1,\
174       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
175     }
176 
177 
178 /*
179 	This macro must have a value below the system time resolution of the
180 	system. The uuid routines use this value  as an upper limit for adding ticks to the
181 	the predecessor time value if system times are equal.
182  */
183 #ifdef SAL_W32
184 #define UUID_SYSTEM_TIME_RESOLUTION_100NS_TICKS 1000
185 #elif defined SAL_OS2 // YD we use posix functions for time
186 #define UUID_SYSTEM_TIME_RESOLUTION_100NS_TICKS 10
187 #elif LINUX
188 #define UUID_SYSTEM_TIME_RESOLUTION_100NS_TICKS 10
189 #elif NETBSD
190 #define UUID_SYSTEM_TIME_RESOLUTION_100NS_TICKS 10
191 #elif FREEBSD
192 #define UUID_SYSTEM_TIME_RESOLUTION_100NS_TICKS 10
193 #elif SOLARIS
194 #define UUID_SYSTEM_TIME_RESOLUTION_100NS_TICKS 10
195 #elif MACOSX
196 #define UUID_SYSTEM_TIME_RESOLUTION_100NS_TICKS 100000
197 #else
198 #error "System time resolution must be calculated!"
199 #endif
200 
201 #ifdef __cplusplus
202 }
203 #endif
204 
205 #endif
206