X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Finterface.html;fp=doc%2Finterface.html;h=5e9d8b23cb980f4eaef7fa1002067c3e40331fc8;hb=b9c6fb3bbed07eceb019666e101b55265a8abdc3;hp=16e66e929881da59aad88312be315266c8e1df4a;hpb=90a75e98afc72c80e06e566d764d92f076e7f26a;p=gedcom-parse.git
diff --git a/doc/interface.html b/doc/interface.html
index 16e66e9..5e9d8b2 100644
--- a/doc/interface.html
+++ b/doc/interface.html
@@ -2234,11 +2234,54 @@ an error is produced). The first two checks are done at the end of
the parsing, because cross-references can be defined after their usage in
GEDCOM.
-An xref_value can also be retrieved by its key via the following function:
-
-struct xref_value* gedcom_get_by_xref (char *key)
+The following functions are available to manipulate xref_value objects:
+struct xref_value* gedcom_get_by_xref (const char *key)
+ Retrieve an xref_value by its key. Returns NULL if the given key isn't a valid cross-reference key (see below) or isn't used.
+
+ struct xref_value* gedcom_add_xref (Xref_type type, const char* key, Gedcom_ctxt object)
+ Add an xref_value of the given type (see list above), with the given key, to the given object, with a use count equal to 0. Returns the new xref_value if success. Returns NULL in one of the following cases:
+
+ - the key isn't a valid cross-reference key (see below)
+ - there is already an xref_value with the same key
+ - there was a memory allocation error
+
+
+ int gedcom_delete_xref (const char* key)
+
+ Delete the xref_value corresponding to the given key. Returns 0 if success. Returns 1 in one of the following cases:
+
+ - the key isn't a valid cross-reference key (see below)
+ - there is no xref_value with the given key
+ - the xref_value is still in use, i.e. its use count is not 0 (see
gedcom_link_xref and gedcom_unlink_xref below)
+
+
+ struct xref_value* gedcom_link_xref (Xref_type type, const char* key)
+struct xref_value* gedcom_unlink_xref (Xref_type type, const char* key)
+ Declare the xref_value corresponding to the given key as being
+used/no longer used (linked to or unlinked) as the given type. The
+use of these functions is not mandatory, but it can aid in spotting places in the code where xref_value objects are deleted while they are still referenced.
+
+Returns the xref_value object if success, and its use count is incremented/decremented. Returns NULL in one of the following cases:
+
+ - the key isn't a valid cross-reference key (see below)
+ - there is no xref_value with the given key
+ - the xref_value was previously added as another type than the type provided here
+
+
+
+
+
-The function returns NULL if the given key isn't used.
+
+A cross-reference key must be a string of maximum 22 characters, of the following format:
+
+ - an at sign ('@')
+ - followed by an alphanumeric character (A-Z, a-z, 0-9 or underscore)
+ - followed by zero or more characters, which can be any character except an at sign
+ - terminated by an at sign ('@')
+
+An example would thus be: "@This is an xref_val@".
+
$Id$
$Name$
@@ -2248,4 +2291,5 @@ The function returns NULL if the given key isn't used.
-