|
file | guid.h |
| globally unique ID User API
|
|
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.
#define GUID_DATA_SIZE 16 |
The type used to store guids
Definition at line 52 of file guid.h.
#define GUID_ENCODING_LENGTH 32 |
number of characters needed to encode a guid as a string not including the null terminator.
Definition at line 64 of file guid.h.
gboolean guid_equal |
( |
const GUID * |
guid_1, |
|
|
const GUID * |
guid_2 |
|
) |
| |
Given two GUIDs, return TRUE if they are non-NULL and equal. Return FALSE, otherwise.
Definition at line 620 of file guid.c.
622 if (guid_1 && guid_2)
guint guid_hash_to_guint |
( |
gconstpointer |
ptr | ) |
|
Given a GUID *, hash it to a guint
Definition at line 645 of file guid.c.
647 const GUID *guid = ptr;
653 PERR (
"received NULL guid pointer.");
657 for (i = 0, j = 0; i <
sizeof (guint); i++, j++)
663 hash |= guid->data[j];
#define PERR(format, args...)
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.
Definition at line 285 of file guid.c.
292 md5_init_ctx (&guid_context);
295 bytes += init_from_file (
"/dev/urandom", 512);
299 const char *files[] = {
"/etc/passwd",
304 "/proc/self/environ",
312 for (i = 0; files[i] != NULL; i++)
313 bytes += init_from_file (files[i], BLOCKSIZE);
319 const char *dirs[] = {
331 for (i = 0; dirs[i] != NULL; i++)
332 bytes += init_from_dir (dirs[i], 32);
334 dirname = g_get_home_dir ();
336 bytes += init_from_dir (dirname, 32);
344 md5_process_bytes (&pid,
sizeof (pid), &guid_context);
345 bytes +=
sizeof (pid);
349 md5_process_bytes (&pid,
sizeof (pid), &guid_context);
350 bytes +=
sizeof (pid);
364 md5_process_bytes (s, strlen (s), &guid_context);
369 md5_process_bytes (&uid,
sizeof (uid), &guid_context);
370 bytes +=
sizeof (uid);
373 md5_process_bytes (&gid,
sizeof (gid), &guid_context);
374 bytes +=
sizeof (gid);
380 #ifdef HAVE_GETHOSTNAME 383 memset (
string, 0,
sizeof (
string));
384 gethostname (
string,
sizeof (
string));
385 md5_process_bytes (
string,
sizeof (
string), &guid_context);
386 bytes +=
sizeof (string);
394 srand ((
unsigned int) time (NULL));
396 for (i = 0; i < 32; i++)
400 md5_process_bytes (&n,
sizeof (n), &guid_context);
406 bytes += init_from_time ();
408 PINFO (
"got %llu bytes", (
unsigned long long int) bytes);
410 if (bytes < THRESHOLD)
411 PWARN (
"only got %llu bytes.\n" 412 "The identifiers might not be very random.\n",
413 (
unsigned long long int) bytes);
415 guid_initialized = TRUE;
#define PINFO(format, args...)
#define PWARN(format, args...)
void guid_init_only_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.
- Parameters
-
salt | The additional random values to add to the generator. |
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.
Definition at line 427 of file guid.c.
429 md5_init_ctx (&guid_context);
431 md5_process_bytes (salt, salt_len, &guid_context);
433 guid_initialized = TRUE;
void guid_init_with_salt |
( |
const void * |
salt, |
|
|
size_t |
salt_len |
|
) |
| |
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.
- Parameters
-
salt | The additional random values to add to the generator. |
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.
Definition at line 419 of file guid.c.
423 md5_process_bytes (salt, salt_len, &guid_context);
GUID* guid_malloc |
( |
void |
| ) |
|
Efficiently allocate & free memory for GUIDs
Definition at line 64 of file guid.c.
66 return g_slice_new (
GUID);
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.
- Parameters
-
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.)
Definition at line 444 of file guid.c.
446 static int counter = 0;
452 if (!guid_initialized)
457 md5_finish_ctx (&ctx, guid->data);
473 init_from_int (433781 * counter);
480 fp = fopen (
"/dev/urandom",
"r");
484 init_from_stream (fp, 32);
488 counter = GUID_PERIOD;
GUID guid_new_return |
( |
void |
| ) |
|
Generate a new id. If no initialization function has been called, guid_init() will be called before the id is created.
- Returns
- guid A data structure containing a newly allocated GUID. Caller is responsible for calling guid_free().
Definition at line 495 of file guid.c.
void guid_new(GUID *guid)
const GUID* guid_null |
( |
void |
| ) |
|
Returns a GUID which is guaranteed to never reference any entity.
Definition at line 79 of file guid.c.
81 static int null_inited = 0;
82 static GUID null_guid;
87 char *tmp =
"NULLGUID.EMPTY.";
91 null_guid.data[i] = tmp[i];
void guid_shutdown |
( |
void |
| ) |
|
Release the memory chunk associated with gui storage. Use this only when shutting down the program, as it invalidates all GUIDs at once.
Definition at line 437 of file guid.c.
const gchar* guid_to_string |
( |
const 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.
- Parameters
-
- Returns
- 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.
Definition at line 568 of file guid.c.
570 #ifdef G_THREADS_ENABLED 571 #ifdef GLIB_DEPRECATED_IN_2_32 572 static GPrivate guid_buffer_key = G_PRIVATE_INIT (g_free);
574 static GStaticPrivate guid_buffer_key = G_STATIC_PRIVATE_INIT;
577 #ifdef GLIB_DEPRECATED_IN_2_32 578 string = g_private_get (&guid_buffer_key);
580 string = g_static_private_get (&guid_buffer_key);
585 #ifdef GLIB_DEPRECATED_IN_2_32 586 g_private_set (&guid_buffer_key,
string);
588 g_static_private_set (&guid_buffer_key,
string, g_free);
592 static char string[64];
595 encode_md5_data (guid->data,
string);
#define GUID_ENCODING_LENGTH
gchar* guid_to_string_buff |
( |
const GUID * |
guid, |
|
|
gchar * |
buff |
|
) |
| |
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)
- Parameters
-
guid | The guid to print. |
buff | The buffer to print it into. |
- Returns
- A pointer to the terminating null character of the string.
gboolean string_to_guid |
( |
const gchar * |
string, |
|
|
GUID * |
guid |
|
) |
| |
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.