/usr/include/qof/guid.h is in libqof-dev 0.8.8-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 | /********************************************************************\
* guid.h -- globally unique ID User API *
* Copyright (C) 2000 Dave Peticolas <peticola@cs.ucdavis.edu> *
* *
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
* published by the Free Software Foundation; either version 2 of *
* the License, or (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* You should have received a copy of the GNU General Public License*
* along with this program; if not, contact: *
* *
* Free Software Foundation Voice: +1-617-542-5942 *
* 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
* Boston, MA 02110-1301, USA gnu@gnu.org *
* *
\********************************************************************/
#ifndef GUID_H
#define GUID_H
#include <stddef.h>
/** @addtogroup Class
@{ */
/** @addtogroup GUID
Globally Unique ID's provide a way to uniquely identify
some thing. A GUID is a unique, cryptographically
random 128-bit value. The identifier is so random that
it is safe to assume that there is no other such item
on the planet Earth, and indeed, not even in the Galaxy
or beyond.
QOF GUID's can be used independently of any other subsystem
in QOF. In particular, they do not require the use of
other parts of the object subsystem. New GUID's are usually
created by initialising a new entity using qof_instance_init,
rather than calling GUID functions directly.
@{ */
/** @file guid.h
@brief globally unique ID User API
@author Copyright (C) 2000 Dave Peticolas <peticola@cs.ucdavis.edu>
*/
/** The type used to store guids */
#define GUID_DATA_SIZE 16
typedef union _GUID
{
guchar data[GUID_DATA_SIZE];
gint __align_me; /* this just ensures that GUIDs are 32-bit
* aligned on systems that need them to be. */
} GUID;
/** number of characters needed to encode a guid as a string
* not including the null terminator. */
#define GUID_ENCODING_LENGTH 32
/** Initialize the id generator with a variety of random
* sources.
*
* @note Only one of guid_init(), guid_init_with_salt() and
* guid_init_only_salt() should be called. Calling any
* initialization function a second time will reset the generator and
* erase the effect of the first call.
*/
void guid_init (void);
/** Initialize the id generator with a variety of random sources. and
* with the data given in the salt argument. This argument can be
* used to add additional randomness to the generated ids.
*
* @param salt The additional random values to add to the generator.
*
* @param salt_len The length of the additional random values.
*
* @note Only one of guid_init(), guid_init_with_salt() and
* guid_init_only_salt() should be called. Calling any
* initialization function a second time will reset the generator and
* erase the effect of the first call.
*/
void guid_init_with_salt (const void *salt, size_t salt_len);
/** Initialize the id generator with the data given in the salt
* argument, but not with any other source. Calling this function with
* a specific argument will reliably produce a specific sequence of
* ids.
*
* @param salt The additional random values to add to the generator.
*
* @param salt_len The length of the additional random values.
*
* @note Only one of guid_init(), guid_init_with_salt() and
* guid_init_only_salt() should be called. Calling any
* initialization function a second time will reset the generator and
* erase the effect of the first call.
*/
void guid_init_only_salt (const void *salt, size_t salt_len);
/** Release the memory chunk associated with gui storage. Use this
* only when shutting down the program, as it invalidates *all*
* GUIDs at once. */
void guid_shutdown (void);
/** Generate a new id. If no initialization function has been called,
* guid_init() will be called before the id is created.
*
* @param guid A pointer to an existing guid data structure. The
* existing value will be replaced with a new value.
*
* This routine uses the md5 algorithm to build strong random guids.
* Note that while guid's are generated randomly, the odds of this
* routine returning a non-unique id are astronomically small.
* (Literally astronomically: If you had Cray's on every solar
* system in the universe running for the entire age of the universe,
* you'd still have less than a one-in-a-million chance of coming up
* with a duplicate id. 2^128 == 10^38 is a really really big number.)
*/
void guid_new (GUID * guid);
/** Generate a new id. If no initialization function has been called,
* guid_init() will be called before the id is created.
*
* @return guid A data structure containing a newly allocated GUID.
* Caller is responsible for calling guid_free().
*/
GUID guid_new_return (void);
/** Returns a GUID which is guaranteed
to never reference any entity. */
const GUID *guid_null (void);
/** Efficiently allocate & free memory for GUIDs */
GUID *guid_malloc (void);
/* Return a guid set to all zero's */
void guid_free (GUID * guid);
/** The guid_to_string() routine returns a null-terminated string
* encoding of the id. String encodings of identifiers are hex
* numbers printed only with the characters '0' through '9' and
* 'a' through 'f'. The encoding will always be GUID_ENCODING_LENGTH
* characters long.
*
* XXX This routine is not thread safe and is deprecated. Please
* use the routine guid_to_string_buff() instead.
*
* @param guid The guid to print.
*
* @return A pointer to the starting character of the string. The
* returned memory is owned by this routine and may not be freed by
* the caller.
*/
const gchar *guid_to_string (const GUID * guid);
/** The guid_to_string_buff() routine puts a null-terminated string
* encoding of the id into the memory pointed at by buff. The
* buffer must be at least GUID_ENCODING_LENGTH+1 characters long.
* This routine is handy for avoiding a malloc/free cycle. It
* returns a pointer to the >>end<< of what was written. (i.e. it
* can be used like 'stpcpy' during string concatenation)
*
* @param guid The guid to print.
*
* @param buff The buffer to print it into.
*
* @return A pointer to the terminating null character of the string.
*/
gchar *guid_to_string_buff (const GUID * guid, gchar * buff);
/** Given a string, decode the id into the guid if guid is non-NULL.
* The function returns TRUE if the string was a valid 32 character
* hexadecimal number. This function accepts both upper and lower case
* hex digits. If the return value is FALSE, the effect on guid is
* undefined. */
gboolean string_to_guid (const gchar * string, GUID * guid);
/** Given two GUIDs, return TRUE if they are non-NULL and equal.
* Return FALSE, otherwise. */
gboolean guid_equal (const GUID * guid_1, const GUID * guid_2);
gint guid_compare (const GUID * g1, const GUID * g2);
/** Given a GUID *, hash it to a guint */
guint guid_hash_to_guint (gconstpointer ptr);
GHashTable *guid_hash_table_new (void);
/* @} */
/* @} */
#endif
|