include/rtl/uuid.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23 #ifndef INCLUDED_RTL_UUID_H
  24 #define INCLUDED_RTL_UUID_H
  25
  26 #include "sal/config.h"
  27
  28 #include "rtl/string.h"
  29 #include "sal/saldllapi.h"
  30 #include "sal/types.h"
  31
  32 /**
  33    @file
  34    Specification (from draft-leach-uuids-guids-01.txt )
  35
  36    <p>
  37    A UUID is an identifier that is unique across both space and time,
  38    with respect to the space of all UUIDs. To be precise, the UUID
  39    consists of a finite bit space. Thus, collision cannot be avoided in
  40    principle. A UUID can be used for multiple purposes, from tagging objects
  41    with an extremely short lifetime, to reliably identifying very persistent
  42    objects across a network.
  43
  44    <p>
  45     The generation of UUIDs does not require that a registration
  46     authority be contacted for each identifier. Instead, Version 4 UUIDs are
  47     generated from (pseudo unique) sequences of (pseudo) random bits.
  48  */
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 /** Generates a new Version 4 (random number based) UUID (Universally Unique
  55     IDentifier).
  56
  57     @param pTargetUUID          pointer to at least 16 bytes of memory. After the call it contains
  58                                 the newly generated uuid in network byte order.
  59     @param pPredecessorUUID     ignored (was used when this function returned
  60                                 Version 1 instead of Version 4 UUIDs).
  61     @param bUseEthernetAddress  ignored (was used when this function returned
  62                                 Version 1 instead of Version 4 UUIDs).
  63  */
  64 SAL_DLLPUBLIC void SAL_CALL rtl_createUuid(
  65                               sal_uInt8 *pTargetUUID,
  66                               const sal_uInt8 *pPredecessorUUID,
  67                               sal_Bool bUseEthernetAddress );
  68
  69 /** Compare two UUID's lexically
  70
  71     <p>
  72     Note:   lexical ordering is not temporal ordering!
  73     <p>
  74     Note:   For equalnesschecking, a memcmp(pUUID1,pUUID2,16) is more efficient
  75
  76     @return
  77     <ul>
  78     <li>-1   u1 is lexically before u2
  79     <li>0   u1 is equal to u2
  80     <li>1   u1 is lexically after u2
  81     </ul>
  82
  83  */
  84 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_compareUuid(
  85         const sal_uInt8 *pUUID1 , const sal_uInt8 *pUUID2 );
  86
  87 /** Creates named UUIDs.
  88
  89     <p>
  90     The version 3 UUID is meant for generating UUIDs from <em>names</em> that
  91     are drawn from, and unique within, some <em>name space</em>. Some examples
  92     of names (and, implicitly, name spaces) might be DNS names, URLs, ISO
  93     Object IDs (OIDs), reserved words in a programming language, or X.500
  94     Distinguished Names (DNs); thus, the concept of name and name space
  95     should be broadly construed, and not limited to textual names.
  96
  97     <p>
  98     The requirements for such UUIDs are as follows:
  99
 100     <ul>
 101     <li> The UUIDs generated at different times from the same name in the
 102          same namespace MUST be equal
 103
 104     <li> The UUIDs generated from two different names in the same namespace
 105          should be different (with very high probability)
 106
 107     <li> The UUIDs generated from the same name in two different namespaces
 108          should be different with (very high probability)
 109
 110     <li> If two UUIDs that were generated from names are equal, then they
 111          were generated from the same name in the same namespace (with very
 112          high probability).
 113     </ul>
 114
 115     @param pTargetUUID pointer to at least 16 bytes of memory. After the call
 116                        it contains the newly generated uuid in network byte order.
 117     @param pNameSpaceUUID The namespace uuid. Below are some predefined ones,
 118                           but any arbitrary uuid can be used as namespace.
 119
 120     @param pName the name
 121  */
 122 SAL_DLLPUBLIC void SAL_CALL rtl_createNamedUuid(
 123     sal_uInt8  *pTargetUUID,
 124     const sal_uInt8  *pNameSpaceUUID,
 125     const rtl_String *pName
 126     );
 127
 128
 129
 130 /*
 131     Predefined Namespaces
 132     (Use them the following way : sal_uInt8 aNsDNS[16])  = RTL_UUID_NAMESPACE_DNS;
 133  */
 134 /** namespace DNS
 135
 136     <p>
 137     (Use them the following way : sal_uInt8 aNsDNS[16])  = RTL_UUID_NAMESPACE_DNS;
 138     <p>
 139    6ba7b810-9dad-11d1-80b4-00c04fd430c8 */
 140 #define RTL_UUID_NAMESPACE_DNS {\
 141       0x6b,0xa7,0xb8,0x10,\
 142       0x9d,0xad,\
 143       0x11,0xd1,\
 144       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
 145     }
 146
 147 /** namespace URL
 148
 149    <p>
 150    6ba7b811-9dad-11d1-80b4-00c04fd430c8 */
 151 #define RTL_UUID_NAMESPACE_URL { \
 152       0x6b, 0xa7, 0xb8, 0x11,\
 153       0x9d, 0xad,\
 154       0x11, 0xd1,\
 155       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
 156     }
 157
 158 /** namespace oid
 159
 160     <p>
 161     6ba7b812-9dad-11d1-80b4-00c04fd430c8 */
 162 #define RTL_UUID_NAMESPACE_OID {\
 163       0x6b, 0xa7, 0xb8, 0x12,\
 164       0x9d, 0xad,\
 165       0x11, 0xd1,\
 166       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
 167     }
 168
 169 /** namespace X500
 170
 171     <p>
 172     6ba7b814-9dad-11d1-80b4-00c04fd430c8 */
 173 #define RTL_UUID_NAMESPACE_X500 {\
 174       0x6b, 0xa7, 0xb8, 0x14,\
 175       0x9d, 0xad,\
 176       0x11, 0xd1,\
 177       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
 178     }
 179
 180 #ifdef __cplusplus
 181 }
 182 #endif
 183
 184 #endif
 185
 186 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */