X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Finterface.html;h=5e9d8b23cb980f4eaef7fa1002067c3e40331fc8;hb=349d849a4f6cfad7a5f2badcda0e3c5799f0302f;hp=16e66e929881da59aad88312be315266c8e1df4a;hpb=dddfe62fbb132fc877bd7354bea1708cad7bc9ae;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 givenkey
, to the givenobject
, with a use count equal to 0. Returns the new xref_value if success. ReturnsNULL
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
andgedcom_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. ReturnsNULL
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 returnsNULL
if the given key isn't used.
+ +A cross-reference key must be a string of maximum 22 characters, of the following format:
++
+An example would thus be: "@This is an xref_val@".- 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 ('@')
+
+
$Id$@@ -2248,4 +2291,5 @@ The function returns
$Name$NULL
if the given key isn't used.
-