1 /********************************************************************\
2  * guid.h -- globally unique ID User API                            *
3  * Copyright (C) 2000 Dave Peticolas <peticola@cs.ucdavis.edu>      *
4  *               2014 Aaron Laws <dartmetrash@gmail.com>            *
5  *                                                                  *
6  * This program is free software; you can redistribute it and/or    *
7  * modify it under the terms of the GNU General Public License as   *
8  * published by the Free Software Foundation; either version 2 of   *
9  * the License, or (at your option) any later version.              *
10  *                                                                  *
11  * This program is distributed in the hope that it will be useful,  *
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of   *
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the    *
14  * GNU General Public License for more details.                     *
15  *                                                                  *
16  * You should have received a copy of the GNU General Public License*
17  * along with this program; if not, contact:                        *
18  *                                                                  *
19  * Free Software Foundation           Voice:  +1-617-542-5942       *
20  * 51 Franklin Street, Fifth Floor    Fax:    +1-617-542-2652       *
21  * Boston, MA  02110-1301,  USA       gnu@gnu.org                   *
22  *                                                                  *
23 \********************************************************************/
24 
25 #ifndef GUID_H
26 #define GUID_H
27 
28 #include <glib-object.h>
29 #ifdef __cplusplus
30 extern "C"
31 {
32 #endif
33 
34 #include <stddef.h>
35 
36 /** @addtogroup Entity
37     @{ */
38 /** @addtogroup GncGUID
39     Globally Unique IDs provide a way to uniquely identify
40     something.  A GncGUID is a unique, cryptographically
41     random 128-bit value.  The identifier is so random that
42     it is safe to assume that there is no other such item
43     on the planet Earth, and indeed, not even in the Galaxy
44     or beyond.
45 
46     QOF GncGUIDs can be used independently of any other subsystem
47     in QOF. In particular, they do not require the use of
48     other parts of the object subsystem. New GncGUIDs are usually
49     created by initializing a new entity using qof_instance_init,
50     rather than calling GncGUID functions directly.
51 
52     @{ */
53 /** @file guid.h
54     @brief  globally unique ID User API
55     @author Copyright (C) 2000 Dave Peticolas <peticola@cs.ucdavis.edu>
56         Copyright 2014 Aaron Laws <dartmetrash@gmail.com>
57 */
58 
59 #define GUID_DATA_SIZE	16
60 
61 #define GNC_TYPE_GUID (gnc_guid_get_type())
62 #define GNC_VALUE_HOLDS_GUID(value) G_VALUE_HOLDS(value, GNC_TYPE_GUID)
63 
64 /* We use two definitions for gncguid: one when compiling for C (so that
65  * the object can be persisted), and a different one when compiling for C++
66  * found in guid.hpp
67  */
68 #ifdef __cplusplus
69 namespace gnc {
70 struct GUID;
71 }
72 #endif
73 
74 /** The type used to store guids in C */
75 typedef struct _gncGuid {
76     unsigned char reserved[GUID_DATA_SIZE];
77 } GncGUID;
78 
79 GType gnc_guid_get_type (void);
80 const GncGUID* gnc_value_get_guid (const GValue *value);
81 
82 /** Number of characters needed to encode a guid as a string
83  * not including the null terminator. */
84 #define GUID_ENCODING_LENGTH 32
85 
86 /** Generate a new guid.
87  *
88  *  @param guid A pointer to an allocated guid data structure.  The
89  *  existing value will be replaced with a new value.
90  */
91 void guid_replace (GncGUID *guid);
92 
93 /** Generate a new id.
94  *
95  * @return guid A data structure containing a copy of a newly constructed GncGUID.
96  */
97 GncGUID guid_new_return (void);
98 
99 /** Returns a GncGUID which is guaranteed to never reference any entity.
100  *
101  * Do not free this value! The same pointer is returned on each call.*/
102 const GncGUID * guid_null (void);
103 
104 /**
105  * Allocate memory for a GUID. This does not construct a GUID. In other words,
106  * the returned pointer has not necessarily been initialized. The returned
107  * pointer must be freed with * guid_free.
108  */
109 GncGUID * guid_malloc (void);
110 
111 /**
112  * Allocate and construct a new GUID. The returned pointer must be
113  * released with guid_free.
114  */
115 GncGUID * guid_new (void);
116 
117 /*Free the guid pointed to. Do not use this guid any more.*/
118 void   guid_free (GncGUID *guid);
119 
120 /**
121  * Returns a newly allocated GncGUID that matches the passed-in GUID.
122  * The returned pointer must be freed using guid_free.
123  */
124 GncGUID *guid_copy (const GncGUID *guid);
125 
126 /** The guid_to_string() routine returns a null-terminated string
127  *  encoding of the id. String encodings of identifiers are hex
128  *  numbers printed only with the characters '0' through '9' and
129  *  'a' through 'f'. The encoding will always be GUID_ENCODING_LENGTH
130  *  characters long (not including the null terminator).
131  *
132  *  @param guid The guid to print.
133  *
134  *  @return A pointer to the starting character of the string.  The
135  *  returned memory is owned by the calling routine and must be freed
136  *  using g_free.
137  */
138 gchar * guid_to_string (const GncGUID * guid);
139 
140 /** The guid_to_string_buff() routine puts a null-terminated string
141  *  encoding of the id into the memory pointed at by buff.  The
142  *  buffer must be at least GUID_ENCODING_LENGTH+1 characters long.
143  *  This routine is handy for avoiding a malloc/free cycle.  It
144  *  returns a pointer to the >>end<< of what was written.  (i.e. it
145  *  can be used like 'stpcpy' during string concatenation)
146  *
147  *  @param guid The guid to print.
148  *
149  *  @param buff The buffer to print it into.
150  *
151  *  @return A pointer to the terminating null character of the string,
152  *     or, if no copy took place, NULL.
153  */
154 gchar * guid_to_string_buff (const GncGUID * guid, /*@ out @*/ gchar *buff);
155 
156 
157 /** Given a string, replace the given guid with the parsed one unless
158  * the given value is null.
159  * If null is passed as guid or string, false is returned and nothing
160  * is done, otherwise, the function returns true.
161  * This function accepts both uppor and lower case hex digits. If
162  * letters outside the range of [a-fA-F] are passed, they are silently
163  * replaced. If non-alphanumeric digits are given, this function will
164  * either return false or replace those values with others.
165  */
166 gboolean string_to_guid(const gchar * string, /*@ out @*/ GncGUID * guid);
167 
168 
169 /** Given two GUIDs, return TRUE if they are non-NULL and equal.
170  * Return FALSE, otherwise. */
171 gboolean guid_equal(const GncGUID *guid_1, const GncGUID *guid_2);
172 gint     guid_compare(const GncGUID *g1, const GncGUID *g2);
173 
174 /** Hash function for a GUID. Given a GncGUID *, hash it to a guint */
175 guint guid_hash_to_guint(gconstpointer ptr);
176 
177 /** Equality function for two GUIDs in a GHashTable. */
178 gint guid_g_hash_table_equal (gconstpointer guid_a, gconstpointer guid_b);
179 
180 /** Returns a GHashTable with <GUID*> as key and a <gpointer> as
181  * value and no destructor functions for key or value set. */
182 GHashTable *guid_hash_table_new(void);
183 
184 /* @} */
185 /* @} */
186 #ifdef __cplusplus
187 }
188 #endif
189 
190 #endif
191