doc/gom.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><title>Gedcom object model in C</title>
   2
   3
   4   <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"></head><body text="#000000" bgcolor="#ffffff" link="#000099" vlink="#990099" alink="#000099">
   5
   6 <h1 align="center">Gedcom object model in C</h1>
   7          <br>
   8
   9 <h2>Index</h2>
  10
  11 <ul>
  12           <li><a href="#Main_functions">Main functions</a></li>
  13
  14     <li><a href="#Object_model_structure">Object model structure</a></li>
  15
  16     <li><a href="#User_data">User data</a><br>
  17 <br>
  18     </li>
  19
  20
  21
  22          <li><a href="gomxref.html">C object model details</a><br>
  23             </li>
  24
  25
  26 </ul>
  27
  28 <hr width="100%" size="2">
  29
  30 <h2><a name="Main_functions"></a>Main functions<br>
  31
  32 </h2>
  33 There are two ways to start with a GEDCOM object model (after having called <code>gedcom_init</code>): either by starting from scratch, or by starting from a given GEDCOM file. &nbsp;This is done via the following two functions:<br>
  34 <blockquote><code>int <b>gom_parse_file</b> (const char* file_name)<br>
  35   </code>
  36   <blockquote>This initializes the object model by parsing the GEDCOM file given by <code>file_name</code>. &nbsp;It returns 0 on success and 1 on failure.<br>
  37   </blockquote>
  38 </blockquote>
  39 <blockquote><code>int <b>gom_new_model</b> ()<br>
  40   </code>
  41   <blockquote>This starts an empty model. &nbsp;Actually, this is done by processing the file "<code>new.ged</code>" in the gedcom-parse data directory.<br>
  42   </blockquote>
  43 </blockquote>
  44 In the GEDCOM object model, all the data is immediately available after calling <code>gom_parse_file()</code> or <code>gom_new_model()</code>. &nbsp;For this, an entire model based on C structs is used. &nbsp;These structs are documented <a href="file:///home/verthezp/src/external/gedcom-parse/doc/gomxref.html">here</a>,
  45 and follow the GEDCOM syntax quite closely. &nbsp;Each of the records in
  46 a GEDCOM file are modelled by a separate struct, and some common sub-structures
  47 have their own struct definition.<br>
  48 <br>
  49
  50 The following functions are available to get at these structs:<br>
  51 <ul>
  52   <li>First, there are two functions to get the header record and the submission
  53 record (there can be only one of them in a GEDCOM file):<br>
  54     <blockquote><code>struct header* &nbsp; &nbsp; &nbsp;<b>gom_get_header</b>();<br>
  55 struct submission* &nbsp;<b>gom_get_submission</b>();<br>
  56       </code></blockquote>
  57   </li>
  58   <li>Further, for each of the other records, there are two functions, one
  59 to get the first of such records, and one to get a record via its cross-reference
  60 tag in the GEDCOM file:<br>
  61     <blockquote><code>struct XXX* &nbsp; <b>gom_get_first_XXX</b>();<br>
  62 struct XXX* &nbsp; <b>gom_get_XXX_by_xref</b>(char* xref);</code><br>
  63     </blockquote>
  64   </li>
  65 </ul>
  66 <blockquote>The <b>XXX</b> stands for one of the following: <code>family, </code><code>individual, multimedia, note, repository, source, submitter, user_rec</code>.<br>
  67 </blockquote>
  68 <h2><a name="Object_model_structure"></a>Object model structure<br>
  69
  70 </h2>
  71
  72 All records of a certain type are linked together in a linked list. &nbsp;The
  73 above functions only give access to the first record of each linked list.
  74 &nbsp;The others can be accessed by traversing the linked list via the <code>next</code> member of the structs. &nbsp;This means that e.g. the following piece of code will traverse the linked list of family records:<br>
  75 <blockquote><code>struct family* fam;<br>
  76   <br>
  77 for (fam = gom_get_first_family() ; fam ; fam = fam-&gt;next) {<br>
  78 &nbsp; ...<br>
  79 }</code><br>
  80 </blockquote>
  81 The <code>next</code> member of the last element in the list is guaranteed to have the <code>NULL</code> value.<br>
  82 <br>
  83 Actually, the linked list is a doubly-linked list: each record also has a <code>previous</code> member. &nbsp;But for implementation reasons the behaviour of this <code>previous</code> member on the edges of the linked list will not be guaranteed, i.e. it can be circular or terminated with <code>NULL</code>, no assumptions can be made in the application code.<br>
  84 <br>
  85 This linked-list model applies also to all sub-structures of the main record structs, i.e. each struct that has a <code>next </code>and <code>previous</code>
  86 member following the above conventions. &nbsp;This means that the following
  87 piece of code traverses all children of a family (see the details of the
  88 different structs <a href="gomxref.html">here</a>):<br>
  89 <blockquote><code>struct family* fam = ...;<br>
  90   <br>
  91 struct xref_list* xrl;<br>
  92 for (xrl = fam-&gt;children ; xrl ; xrl = xrl-&gt;next) {<br>
  93 &nbsp; ...<br>
  94 }</code> <br>
  95 </blockquote>
  96 Note that all character strings in the object model are encoded in UTF-8 (<a href="file:///home/verthezp/src/external/gedcom-parse/doc/encoding.html">Why UTF-8?</a>).<br>
  97 <h2><a name="User_data"></a>User data</h2>
  98
  99 Each of the structs has an extra member called <code>extra</code> (of type <code>struct user_data*</code>).
 100 &nbsp;This gathers all non-standard GEDCOM tags within the scope of the struct
 101 in a flat linked list, no matter what the internal structure of the non-standard
 102 tags is. &nbsp;Each element of the linked list has:<br>
 103 <ul>
 104   <li>a level: the level number in the GEDCOM file</li>
 105   <li>a tag: the tag given in the GEDCOM file</li>
 106   <li>a value: the value, which can be a string value or a cross-reference value (one of the two will be non-NULL)<br>
 107   </li>
 108 </ul>
 109 This way, none of the information in the GEDCOM file is lost, even the non-standard information.<br>
 110 <hr width="100%" size="2">
 111
 112 <pre><font size="-1">$Id$<br>$Name$</font><br></pre>
 113
 114
 115 <pre>                    </pre>
 116
 117
 118 <br>
 119 <br>
 120 <br>
 121 </body></html>