Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

GUID
[Entity: Types, Identity and Instance Framework]


Detailed Description

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.


Files

file  guid.h
 globally unique ID User API


Data Structures

union  _GUID

Defines

#define GUID_ENCODING_LENGTH   32

Typedefs

typedef _GUID GUID

Functions

void guid_init (void)
void guid_init_with_salt (const void *salt, size_t salt_len)
void guid_init_only_salt (const void *salt, size_t salt_len)
void guid_shutdown (void)
void guid_new (GUID *guid)
const GUID guid_new_return (void)
const GUIDguid_null (void)
GUIDguid_malloc (void)
void guid_free (GUID *guid)
const char * guid_to_string (const GUID *guid)
char * guid_to_string_buff (const GUID *guid, char *buff)
gboolean string_to_guid (const char *string, GUID *guid)
gboolean guid_equal (const GUID *guid_1, const GUID *guid_2)
gint guid_compare (const GUID *g1, const GUID *g2)
guint guid_hash_to_guint (gconstpointer ptr)
GHashTable * guid_hash_table_new (void)


Define Documentation

#define GUID_ENCODING_LENGTH   32
 

number of characters needed to encode a guid as a string not including the null terminator.


Typedef Documentation

typedef union _GUID GUID
 

The type used to store guids


Function Documentation

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.

guint guid_hash_to_guint gconstpointer  ptr  ) 
 

Given a GUID *, hash it to a guint

void guid_init void   ) 
 

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_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.

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.

GUID* guid_malloc void   ) 
 

Efficiently allocate & free memory for GUIDs

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 teh 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.)

const 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 pointer to a data structure contaiing a new GUID. The memory pointed to is owned by this routine and the guid must be copied out.

const GUID* guid_null void   ) 
 

Returns a GUID which is guaranteed to never reference any entity.

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.

const char* 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:
guid The guid to print.
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.

char* guid_to_string_buff const GUID guid,
char *  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 char *  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.


Generated on Sun May 23 15:41:47 2004 for QOF by doxygen 1.3.6-20040222