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