Small correction in help string.

[gedcom-parse.git] / doc / interface.html

diff --git a/doc/interface.html b/doc/interface.html
index 68cea056841bd13363a64fd92462228750fcb435..5e9d8b23cb980f4eaef7fa1002067c3e40331fc8 100644 (file)
--- a/doc/interface.html
+++ b/doc/interface.html
@@ -14,11 +14,11 @@
         <li><a href="#Gedcom_val_types">Gedcom_val types</a></li>
                    
   <ul>
-         <li><a href="#struct_date_value">struct date_value</a></li>
-         <li><a href="#struct_date">struct date</a></li><li><a href="#age_value">struct age_value</a><br>
+         <li><a href="#date_value">struct date_value</a></li>
+         <li><a href="#date">struct date</a></li><li><a href="#age_value">struct age_value</a><br>
     </li>
 
-     <li><a href="#struct_xref_value">struct xref_value</a><br>
+     <li><a href="#xref_value">struct xref_value</a><br>
         </li>
                    
   </ul>
@@ -825,9 +825,8 @@ element   start callback.<br>
     ELT_SUB_INDIV_RESI,<br>
     ELT_SUB_INDIV_BIRT,<br>
     ELT_SUB_INDIV_GEN,<br>
-    ELT_SUB_INDIV_ADOP<br>
-          </code><br>
-          <br>
+    ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN</code><br>
            </td>
            <td valign="top"><code>STRING</code><br>
            </td>
@@ -915,9 +914,8 @@ element   start callback.<br>
     ELT_SUB_INDIV_RESI,<br>
     ELT_SUB_INDIV_BIRT,<br>
     ELT_SUB_INDIV_GEN,<br>
-    ELT_SUB_INDIV_ADOP<br>
-          </code><br>
-          <br>
+    ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN</code><br>
            </td>
            <td valign="top"><code>STRING</code><br>
            </td>
@@ -929,7 +927,14 @@ element   start callback.<br>
            </td>
            <td valign="top"><code>REC_INDI</code><br>
            </td>
-           <td valign="top"><code>XREF_PTR(INDI)</code><br>
+           <td valign="top"><code>XREF_PTR(FAM),<br>
+XREF_PTR(INDI),<br>
+XREF_PTR(NOTE),<br>
+XREF_PTR(OBJE),<br>
+XREF_PTR(REPO),<br>
+XREF_PTR(SOUR),<br>
+XREF_PTR(SUBM),<br>
+XREF_PTR(SUBN)</code><br>
            </td>
          </tr>
          <tr>
@@ -1047,8 +1052,8 @@ element   start callback.<br>
     ELT_SUB_INDIV_RESI,<br>
     ELT_SUB_INDIV_BIRT,<br>
     ELT_SUB_INDIV_GEN,<br>
-    ELT_SUB_INDIV_ADOP<br>
-          </code><br>
+    ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN</code><br>
            </td>
            <td valign="top"><code>STRING</code><br>
            </td>
@@ -1064,10 +1069,8 @@ element   start callback.<br>
      ELT_SUB_INDIV_RESI,<br>
      ELT_SUB_INDIV_BIRT,<br>
      ELT_SUB_INDIV_GEN,<br>
-     ELT_SUB_INDIV_ADOP<br>
-          </code><br>
-          <br>
-          <br>
+     ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN</code><br>
            </td>
            <td valign="top"><code>DATE</code><br>
            </td>
@@ -1083,9 +1086,8 @@ element   start callback.<br>
     ELT_SUB_INDIV_RESI</code><code>,<br>
      ELT_SUB_INDIV_BIRT,<br>
      ELT_SUB_INDIV_GEN,<br>
-     ELT_SUB_INDIV_ADOP</code><br>
-          <br>
-          <br>
+     ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN</code><br>
            </td>
            <td valign="top"><code>AGE</code><br>
            </td>
@@ -1101,9 +1103,8 @@ element   start callback.<br>
     ELT_SUB_INDIV_RESI</code><code>,<br>
      ELT_SUB_INDIV_BIRT,<br>
      ELT_SUB_INDIV_GEN,<br>
-     ELT_SUB_INDIV_ADOP</code><br>
-          <br>
-          <br>
+     ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN</code><br>
            </td>
            <td valign="top"><code>STRING</code><br>
            </td>
@@ -1119,9 +1120,8 @@ element   start callback.<br>
     ELT_SUB_INDIV_RESI</code><code>,<br>
      ELT_SUB_INDIV_BIRT,<br>
      ELT_SUB_INDIV_GEN,<br>
-     ELT_SUB_INDIV_ADOP</code><br>
-          <br>
-          <br>
+     ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN</code><br>
            </td>
            <td valign="top"><code>STRING</code><br>
            </td>
@@ -1466,6 +1466,7 @@ element   start callback.<br>
      ELT_SUB_INDIV_BIRT,<br>
      ELT_SUB_INDIV_GEN,<br>
      ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN,<br>
     ELT_SUB_SOUR</code><br>
            </td>
            <td valign="top"><code>NULL<br>
@@ -1519,6 +1520,7 @@ element   start callback.<br>
      ELT_SUB_INDIV_BIRT,<br>
      ELT_SUB_INDIV_GEN,<br>
      ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN,<br>
     ELT_SUB_LIO_BAPL,<br>
     ELT_SUB_LIO_SLGC,<br>
     ELT_SUB_LSS_SLGS,<br>
@@ -1613,7 +1615,12 @@ element   start callback.<br>
            <td valign="top"><code>ELT_SUB_FAM_EVT</code>,<br>
           <code>ELT_SUB_FAM_EVT_EVEN,<br>
     ELT_SUB_INDIV_ATTR,<br>
-    ELT_SUB_INDIV_RESI</code><br>
+    ELT_SUB_INDIV_RESI</code><code>,
+     <br>
+ELT_SUB_INDIV_BIRT,<br>
+     ELT_SUB_INDIV_GEN,<br>
+     ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN</code><br>
            </td>
            <td valign="top"><code>STRING</code><br>
            </td>
@@ -1642,6 +1649,7 @@ element   start callback.<br>
      ELT_SUB_INDIV_BIRT,<br>
      ELT_SUB_INDIV_GEN,<br>
      ELT_SUB_INDIV_ADOP,<br>
+ELT_SUB_INDIV_EVEN,<br>
     ELT_SUB_LIO_BAPL,<br>
     ELT_SUB_LIO_SLGC,<br>
     ELT_SUB_LSS_SLGS,<br>
@@ -1857,13 +1865,13 @@ the value    that is returned by <code>GEDCOM_STRING(val)</code> is always the s
 <code>raw_value</code> passed    to the start callback, and is thus in fact redundant.<br>
      <br>
       The date value is used for all elements that return a date. &nbsp;See 
-<a href="#struct_date_value">here</a> for the definition.<br>
+<a href="#date_value">here</a> for the definition.<br>
  <br>
  The xref value is for cross-references between records in the file. &nbsp;See 
-<a href="#struct_xref_value">here</a> for the definition.<br>
+<a href="#xref_value">here</a> for the definition.<br>
      <br>
          
-<h3><a name="struct_date_value"></a>struct date_value</h3>
+<h3><a name="date_value"></a>struct date_value</h3>
      This struct describes a date as given in the GEDCOM file, and has the
  following  definition:<br>
          
@@ -1991,7 +1999,7 @@ the value    that is returned by <code>GEDCOM_STRING(val)</code> is always the s
   </table>
        <br>
                    
-  <h3><a name="struct_date"></a>struct date<br>
+  <h3><a name="date"></a>struct date<br>
        </h3>
      The <code>date1</code> and <code>date2</code> also have a strict syntax:<br>
                    
@@ -2176,7 +2184,7 @@ The modifier can be one of the following:<br>
 <li><code> AGE_NO_MODIFIER</code> : no modifier</li><li><code>AGE_LESS_THAN</code><code></code>&nbsp; : the modifier '&lt;' is added</li><li><code>AGE_GREATER_THAN </code>: the modifier '&gt;' is added</li>
 </ul>
 <br>
-<h3><a name="struct_xref_value"></a>struct xref_value</h3>
+<h3><a name="xref_value"></a>struct xref_value</h3>
 
  This struct represents a cross-reference in the GEDCOM file (but note that 
 the <code>Gedcom_val</code> contains a pointer to such a struct, not the struct
@@ -2200,7 +2208,9 @@ be one of:<br>
                  <li><code>XREF_REPO</code></li>
                  <li><code>XREF_SOUR</code></li>
                  <li><code>XREF_SUBM</code></li>
-                 <li><code>XREF_SUBN</code></li>
+                 <li><code>XREF_SUBN</code></li><li><code>XREF_ANY</code> (if the type is not known, see below)<br>
+  </li>
+
                  <li><code>XREF_USER</code> (for application-specific cross-references)<br>
                    <code></code></li>
                
@@ -2211,6 +2221,10 @@ can be filled by the application with an object (of any type) that corresponds
 with the cross-reference, and then later extracted when the cross-reference 
 is used or defined again in the file. &nbsp;This relieves the application 
 from the burden of maintaining the mapping between cross-references and objects.<br>
+<br>
+The value <code>XREF_ANY</code> is used when the type of the object is not
+immediately known: it has to come from further information. &nbsp;This is
+the case in an association (<code>ELT_SUB_ASSO</code>): the type is then given by the <code>TYPE</code> subtag.<br>
                <br>
   The parser checks whether all cross-references that are used are defined
  (if not, an error is produced) and whether all cross-references that are
@@ -2219,11 +2233,63 @@ the type of the cross-reference is the same on definition and use (if not,
 an error is produced). &nbsp;The first two checks are done at the end of
 the parsing, because cross-references can be defined after their usage in
 GEDCOM.<br>
-               <br>
+<br>
+The following functions are available to manipulate xref_value objects:<br>
+<blockquote><code>struct xref_value* <b>gedcom_get_by_xref</b> (const char *key)</code><br>
+  <blockquote>&nbsp;Retrieve an xref_value by its key. &nbsp;Returns <code>NULL</code> if the given key isn't a valid cross-reference key (see below) or isn't used.<br>
+  </blockquote>
+  <code>struct xref_value* <b>gedcom_add_xref</b> (Xref_type type, const char* key, Gedcom_ctxt object)</code> <br>
+  <blockquote>Add an xref_value of the given <code>type</code> (see list above), with the given <code>key</code>, to the given <code>object</code>, with a use count equal to 0. &nbsp;Returns the new xref_value if success. &nbsp;Returns <code>NULL</code> in one of the following cases:<br>
+    <ul>
+      <li>the key isn't a valid cross-reference key (see below)</li>
+      <li>there is already an xref_value with the same key</li>
+      <li>there was a memory allocation error</li>
+    </ul>
+  </blockquote>
+  <code>int <b>gedcom_delete_xref</b> (const char* key)<br>
+  </code>
+  <blockquote>Delete the xref_value corresponding to the given key. &nbsp;Returns 0 if success. &nbsp;Returns 1 in one of the following cases:<br>
+    <ul>
+      <li>the key isn't a valid cross-reference key (see below)</li>
+      <li>there is no xref_value with the given key</li>
+      <li>the xref_value is still in use, i.e. its use count is not 0 (see <code>gedcom_link_xref</code> and <code>gedcom_unlink_xref</code> below)</li>
+    </ul>
+  </blockquote>
+  <code>struct xref_value* <b>gedcom_link_xref</b> (Xref_type type, const char* key)<br>
+struct xref_value* <b>gedcom_unlink_xref</b> (Xref_type type, const char* key)</code><br>
+  <blockquote>Declare the xref_value corresponding to the given key as being
+used/no longer used (linked to or unlinked) as the given type. &nbsp;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.<br>
+    <br>
+Returns the xref_value object if success, and its use count is incremented/decremented. &nbsp;Returns <code>NULL</code> in one of the following cases:<br>
+    <ul>
+      <li>the key isn't a valid cross-reference key (see below)</li>
+      <li>there is no xref_value with the given key</li>
+      <li>the xref_value was previously added as another type than the type provided here<br>
+      </li>
+    </ul>
+  </blockquote>
+</blockquote>
+<blockquote>
+                       </blockquote>
+
+A cross-reference key must be a string of maximum 22 characters, of the following format:<br>
+<ul>
+  <li>an at sign ('@')</li>
+  <li>followed by an alphanumeric character (A-Z, a-z, 0-9 or underscore)</li>
+  <li>followed by zero or more characters, which can be any character except an at sign</li>
+  <li>terminated by an at sign ('@')</li>
+</ul>
+An example would thus be: "@This is an xref_val@".<br>
+
                                                                        
               <hr width="100%" size="2">                            
               <pre>$Id$<br>$Name$<br></pre>
       <br>
                                                                         
               <br>
+<br>
+<br>
+<br>
+<br>
 </body></html>
\ No newline at end of file