GncGUID

Globally Unique IDs provide a way to uniquely identify something. More...

Files
file	guid.h
	globally unique ID User API

Data Structures
struct	GncGUID
	The type used to store guids in C. More...

Macros
#define	GUID_DATA_SIZE   16
#define	GNC_TYPE_GUID   (gnc_guid_get_type())
#define	GNC_VALUE_HOLDS_GUID(value)   G_VALUE_HOLDS(value, GNC_TYPE_GUID)
#define	GUID_ENCODING_LENGTH   32
	Number of characters needed to encode a guid as a string not including the null terminator.

Functions
GType	gnc_guid_get_type (void)
const GncGUID *	gnc_value_get_guid (const GValue *value)
	gnc_value_get_guid
void	guid_replace (GncGUID *guid)
	Generate a new guid.
GncGUID	guid_new_return (void)
	Generate a new id.
const GncGUID *	guid_null (void)
	Returns a GncGUID which is guaranteed to never reference any entity.
GncGUID *	guid_malloc (void)
	Allocate memory for a GUID.
GncGUID *	guid_new (void)
	Allocate and construct a new GUID.
void	guid_free (GncGUID *guid)
GncGUID *	guid_copy (const GncGUID *guid)
	Returns a newly allocated GncGUID that matches the passed-in GUID.
gchar *	guid_to_string (const GncGUID *guid)
	The guid_to_string() routine returns a null-terminated string encoding of the id.
gchar *	guid_to_string_buff (const GncGUID *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.
gboolean	string_to_guid (const gchar *string, GncGUID *guid)
	Given a string, replace the given guid with the parsed one unless the given value is null.
gboolean	guid_equal (const GncGUID *guid_1, const GncGUID *guid_2)
	Given two GUIDs, return TRUE if they are non-NULL and equal.
gint	guid_compare (const GncGUID *g1, const GncGUID *g2)
guint	guid_hash_to_guint (gconstpointer ptr)
	Hash function for a GUID.
gint	guid_g_hash_table_equal (gconstpointer guid_a, gconstpointer guid_b)
	Equality function for two GUIDs in a GHashTable.
GHashTable *	guid_hash_table_new (void)
	Returns a GHashTable with <GUID*> as key and a <gpointer> as value and no destructor functions for key or value set.

Variables
unsigned char	GncGUID::reserved [GUID_DATA_SIZE]

Detailed Description

Globally Unique IDs provide a way to uniquely identify something.

A GncGUID 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 GncGUIDs 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 GncGUIDs are usually created by initializing a new entity using qof_instance_init, rather than calling GncGUID functions directly.

Macro Definition Documentation

GNC_TYPE_GUID

#define GNC_TYPE_GUID   (gnc_guid_get_type())

Definition at line 61 of file guid.h.

GNC_VALUE_HOLDS_GUID

#define GNC_VALUE_HOLDS_GUID

(

value

)

G_VALUE_HOLDS(value, GNC_TYPE_GUID)

Definition at line 62 of file guid.h.

GUID_DATA_SIZE

#define GUID_DATA_SIZE   16

Definition at line 59 of file guid.h.

GUID_ENCODING_LENGTH

#define GUID_ENCODING_LENGTH   32

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

Definition at line 84 of file guid.h.

Function Documentation

gnc_value_get_guid()

const GncGUID * gnc_value_get_guid

(

const GValue *

value

)

gnc_value_get_guid

Parameters

value

a GValue whose value we want to get.

Returns

the value stored in value

Definition at line 72 of file guid.cpp.

{
    if (!value) return nullptr;
    GncGUID *val;
 
    g_return_val_if_fail (value && G_IS_VALUE (value), nullptr);
    g_return_val_if_fail (GNC_VALUE_HOLDS_GUID (value), nullptr);
 
    val = (GncGUID*) g_value_get_boxed (value);
 
    return val;
}

guid_compare()

gint guid_compare	(	const GncGUID *	g1,
		const GncGUID *	g2
	)

Definition at line 243 of file guid.cpp.

{
    if (guid_1 == guid_2) return 0;
    if (!guid_1) return -1;
    if (!guid_2) return 1;
    return std::memcmp (guid_1->reserved, guid_2->reserved, GUID_DATA_SIZE);
}

guid_copy()

GncGUID * guid_copy

(

const GncGUID *

guid

)

Returns a newly allocated GncGUID that matches the passed-in GUID.

The returned pointer must be freed using guid_free.

Definition at line 155 of file guid.cpp.

{
    if (!guid) return nullptr;
    auto ret = guid_malloc ();
    *ret = *guid;
    return ret;
}

guid_equal()

gboolean guid_equal	(	const GncGUID *	guid_1,
		const GncGUID *	guid_2
	)

Given two GUIDs, return TRUE if they are non-NULL and equal.

Return FALSE, otherwise.

Definition at line 237 of file guid.cpp.

{
    return guid_compare (guid_1, guid_2) == 0;
}

guid_free()

void guid_free

(

GncGUID *

guid

)

Definition at line 145 of file guid.cpp.

{
    if (!guid) return;
    if (guid == s_null_gncguid)
        /* Don't delete that! */
        return;
    delete guid;
}

guid_g_hash_table_equal()

gint guid_g_hash_table_equal	(	gconstpointer	guid_a,
		gconstpointer	guid_b
	)

Equality function for two GUIDs in a GHashTable.

Definition at line 269 of file guid.cpp.

{
    return guid_equal (reinterpret_cast<const GncGUID*> (guid_a),
               reinterpret_cast<const GncGUID*> (guid_b));
}

guid_hash_table_new()

GHashTable * guid_hash_table_new

(

void

)

Returns a GHashTable with <GUID*> as key and a <gpointer> as value and no destructor functions for key or value set.

Definition at line 276 of file guid.cpp.

{
    return g_hash_table_new (guid_hash_to_guint, guid_g_hash_table_equal);
}

guid_hash_to_guint()

guint guid_hash_to_guint

(

gconstpointer

ptr

)

Hash function for a GUID.

Given a GncGUID *, hash it to a guint

Definition at line 255 of file guid.cpp.

{
    if (!ptr)
    {
        PERR ("received nullptr guid pointer.");
        return 0;
    }
    const GncGUID* g = static_cast<const GncGUID*>(ptr);
    guint rv;
    memcpy (&rv, &g->reserved[12], sizeof (guint));
    return rv;
}

guid_malloc()

GncGUID * guid_malloc

(

void

)

Allocate memory for a GUID.

This does not construct a GUID. In other words, the returned pointer has not necessarily been initialized. The returned pointer must be freed with * guid_free.

Definition at line 139 of file guid.cpp.

{
    return new GncGUID;
}

guid_new()

GncGUID * guid_new

(

void

)

Allocate and construct a new GUID.

The returned pointer must be released with guid_free.

Definition at line 186 of file guid.cpp.

{
    auto ret = guid_new_return ();
    return guid_copy (&ret);
}

guid_new_return()

GncGUID guid_new_return

(

void

)

Generate a new id.

Returns

guid A data structure containing a copy of a newly constructed GncGUID.

Definition at line 193 of file guid.cpp.

{
    return gnc::GUID::create_random ();
}

guid_null()

const GncGUID * guid_null

(

void

)

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

Do not free this value! The same pointer is returned on each call.

Definition at line 165 of file guid.cpp.

{
    return s_null_gncguid;
}

guid_replace()

void guid_replace

(

GncGUID *

guid

)

Generate a new guid.

Parameters

guid	A pointer to an allocated guid data structure. The existing value will be replaced with a new value.

Definition at line 178 of file guid.cpp.

{
    if (!guid) return;
    gnc::GUID temp_random {gnc::GUID::create_random ()};
    guid_assign (*guid, temp_random);
}

guid_to_string()

gchar * guid_to_string

(

const GncGUID *

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 (not including the null terminator).

Parameters

guid	The guid to print.

Returns

A pointer to the starting character of the string. The returned memory is owned by the calling routine and must be freed using g_free.

Definition at line 199 of file guid.cpp.

{
    if (!guid) return nullptr;
    char* buffer = g_new (char, GUID_ENCODING_LENGTH + 1);
    guid_to_string_buff (guid, buffer);
    return buffer;
}

guid_to_string_buff()

gchar * guid_to_string_buff	(	const GncGUID *	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, or, if no copy took place, NULL.

Definition at line 208 of file guid.cpp.

{
    if (!str || !guid) return nullptr;
    fast_guid_to_string (guid->reserved, str);
    str[GUID_ENCODING_LENGTH] = '\0';
    return str;
}

string_to_guid()

gboolean string_to_guid	(	const gchar *	string,
		GncGUID *	guid
	)

Given a string, replace the given guid with the parsed one unless the given value is null.

If null is passed as guid or string, false is returned and nothing is done, otherwise, the function returns true. This function accepts both uppor and lower case hex digits. If letters outside the range of [a-fA-F] are passed, they are silently replaced. If non-alphanumeric digits are given, this function will either return false or replace those values with others.

Variable Documentation

reserved

unsigned char GncGUID::reserved[GUID_DATA_SIZE]

Definition at line 76 of file guid.h.