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 arbitrary 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