sal/inc/rtl/uuid.h

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