<ul>
<li><a href="#User_data">User data</a></li>
</ul>
- <li><a href="#Other_functions">Other functions</a></li>
+ <li><a href="#Other_functions">Modifying the object model</a></li>
<ul>
- <li><a href="#Manipulating_strings">Manipulating strings</a><br>
- <br>
+ <li><a href="#Manipulating_strings">Manipulating strings</a></li><li><a href="#Adding_and_removing_records">Adding and removing records</a></li>
+ <li><a href="#Adding_rem_and_moving_xref">Adding, removing and moving cross-references</a><br>
+ </li>
+ <li><a href="#Adding_removing_and_moving">Adding, removing and moving sub-structures</a><br>
+ </li>
+
+ </ul><li><a href="#Writing_the_object_model_to_file">Writing the object model to file</a><br>
+<br>
</li>
- </ul>
+
to get the first of such records, and one to get a record via its cross-reference
tag in the GEDCOM file:<br>
<blockquote><code>struct XXX* <b>gom_get_first_XXX</b>();<br>
-struct XXX* <b>gom_get_XXX_by_xref</b>(char* xref);</code><br>
+struct XXX* <b>gom_get_XXX_by_xref</b>(const char* xref);</code><br>
</blockquote>
</li>
</ul>
This way, none of the information in the GEDCOM file is lost, even the non-standard information.<br>
<br>
<hr width="100%" size="2">
-<h2><a name="Other_functions"></a>Other functions</h2>
+<h2><a name="Other_functions"></a>Modifying the object model</h2>Note that the date manipulations are described <a href="interface.html#date_value">here</a>.<br>
+
<h3><a name="Manipulating_strings"></a>Manipulating strings<br>
</h3>
There are some functions available to retrieve and change strings in the
<br>
The following functions retrieve and set the string in UTF-8 encoding:<br>
<blockquote><code>char* <b>gom_get_string</b> (char* data);<br>
-char* <b>gom_set_string</b> (char** data, const char* utf8_str);</code><br>
+char* <b>gom_set_string</b> (char** data, const char* str_in_utf8);</code><br>
</blockquote>
The first function is in fact superfluous, because it just returns the <code>data</code>, but it is there for symmetry with the functions given below for the locale-defined input and output. <br>
<br>
The second function returns the new value if successful, or <code>NULL</code>
-if an error occurred (e.g. failure to allocate memory). It makes a
+if an error occurred (e.g. failure to allocate memory or the given string is not a valid UTF-8 string). It makes a
copy of the input string to store it in the object model. It also takes
care of deallocating the old value of the data if needed. Note that
the set function needs the address of the data variable, to be able to modify
-it.<br>
+it. In the case of an error, the target data variable is not modified.<br>
<br>
Examples of use of these strings would be, e.g. for retrieving and setting the system ID in the header:<br>
<blockquote><code>struct header* head = gom_get_header();</code><code></code><br>
<br>
A second couple of functions retrieve and set the string in the format defined by the current locale:<br>
<blockquote><code>char* <b>gom_get_string_for_locale</b> (char* data, int* conversion_failures);<br>
-char* <b>gom_set_string_for_locale</b> (char** data, const char* locale_str)</code>;<br>
+char* <b>gom_set_string_for_locale</b> (char** data, const char* str_in_locale)</code>;<br>
</blockquote>
The use of these functions is the same as the previous ones, but e.g. in
the "en_US" locale the string will be returned by the first function in the
-ISO-8859-1 encoding and the second function expects the <code>locale_str</code> to be in this encoding. Conversion to and from UTF-8 for the object model is done on the fly.<br>
+ISO-8859-1 encoding and the second function expects the <code>str_in_locale</code> to be in this encoding. Conversion to and from UTF-8 for the object model is done on the fly.<br>
<br>
Since the conversion from UTF-8 to the locale encoding is not always possible,
the get function has a second parameter that can return the number of conversion
failures for the result string. Pass a pointer to an integer if you
-want to know this. You can pass <code>NULL</code> if you're not interested.<br>
+want to know this. You can pass <code>NULL</code> if you're not interested. The function returns <code>NULL</code>
+if an error occurred (e.g. if the given string is not a valid string for
+the current locale); in that case the target data variable is not modified.<br>
+<br>
+<h3><a name="Adding_and_removing_records"></a>Adding and removing records</h3>
+For each of the record types, there are two functions to add and remove records:
+<blockquote><code>struct XXX* <b>gom_new_XXX</b>(const char* xref);<br>
+int <b>gom_delete_XXX</b>(struct XXX* obj);</code><br>
+ </blockquote>
+
+
+The <code><b>XXX</b></code> stands for one of the following: <code><b>family</b>, </code><code><b>individual</b>, <b>multimedia</b>, <b>note</b>, <b>repository</b>, <b>source</b>, <b>submitter</b>, <b>user_rec</b></code>.<br>
+<br>
+For submission records, the <code><b>gom_delete_submission()</b></code> has no parameters (since there can be only one such object anyway).<br>
+<br>
+When creating new records, the application is responsible for making sure
+that mandatory fields (according to the GEDCOM spec) are filled in afterwards.
+ In a later release, there will be checks in <code>gom_write_file</code> when something is missing.<br>
+<br>
+<h3><a name="Adding_rem_and_moving_xref"></a>Adding, removing and moving cross-references<br>
+</h3>
+For struct members that are of type <code>struct xref_value</code>, the following function is available:<br>
+<blockquote><code>struct xref_value* <b>gom_set_xref</b>(struct xref_value** data, const char* xref);</code><br>
+ </blockquote>
+This function modifies the <code>data</code> variable to point to the given <code>xref</code>, taking care of unreferencing the old value, and referencing the new value. If an error occurs, <code>NULL</code> is returned (and the <code>data</code> variable is not changed). If xref is <code>NULL</code>, the data is set to <code>NULL</code>.<br>
+<br>
+For struct members that are of type <code>struct xref_list</code>, the following functions are available:<br>
+<blockquote><code>struct xref_list* <b>gom_add_xref</b>(struct xref_list** data, const char* xref);<br>
+int <b> gom_remove_xref</b>(struct xref_list** data, const char* xref);<br>
+int <b>gom_move_xref</b>(Gom_direction dir, </code><code>struct xref_list** data, const char* xref);</code><br>
+ </blockquote>
+The first function adds the given <code>xref</code> to the end of the <code>data</code> list. The second function removes the given <code>xref</code> from the <code>data</code> list (if present; if not present an error is generated and 1 is returned).<br>
+<br>
+The third function moves the given <code>xref </code>up or down the <code>data</code> list, depending on the <code>dir</code> parameter, which can be:<br>
+<ul>
+ <li><code>MOVE_UP</code></li>
+ <li><code>MOVE_DOWN</code></li>
+</ul>
+Again, an error is generated and 1 is returned if the given xref is not part
+of the list. If the xref cannot be moved up (because the first in the
+list) or down (because the last in the list), a warning is generated, but
+the function still returns success (0).<br>
+<h3><a name="Adding_removing_and_moving"></a>Adding, removing and moving substructures<br>
+</h3>
+For struct members that are just a single value, the following functions are available:<br>
+<blockquote><code>struct XXX* <b>gom_set_new_XXX</b>(struct XXX** data);<br>
+int <b>gom_delete_XXX</b>(struct XXX** data);</code><br>
+ </blockquote>
+This is the case for <b><code>XXX</code></b> equal to <b><code>address</code></b>, <b><code>change_date</code></b> or <b><code>place</code></b>. The first function creates a new substructure and assigns it to <code>data</code> (<code>NULL</code> is returned if there was already a value). The second function deletes the value from <code>data</code>.<br>
+<br>
+Note: for <code>change_date</code> structs there is also the following short-cut function, which updates the date and time directly:<br>
+<blockquote><code>int <b>gom_update_timestamp</b> (struct change_date** obj, time_t tval);<br></code></blockquote>
+For struct members that are a list (as described <a href="#Object_lists">here</a>), the following functions are available:<br>
+<blockquote><code>struct XXX* <b>gom_add_new_XXX</b>(struct XXX** data);<br>
+int <b>gom_remove_XXX</b>(struct XXX** data, struct XXX* obj);</code><br>
+ <code>int <b>gom_move_XXX</b>(Gom_direction dir, struct XXX** data, struct XXX* obj);</code><br>
+ </blockquote>
+
+This is the case for all <code>XXX</code> structs that have a <code>next</code> and <code>previous</code> member. The first function creates a new substructure and adds it to the end of the <code>data</code> list. The second function deletes the object from the <code>data</code> list (if present; if not present, an error is generated and 1 is returned).<br>
+<br>
+The third function moves the given <code>obj</code> up or down the <code>data</code> list, depending on the <code>dir</code> parameter, similar to the xref functions above.<br>
+<br>
+
<hr width="100%" size="2">
+<h2><a name="Writing_the_object_model_to_file"></a>Writing the object model to file<br>
+</h2>
+Writing the current object model to a file is simply done using the following function:<br>
+<blockquote><code>int <b>gom_write_file</b> (const char* filename, int* total_conv_fails);<br></code></blockquote>
+This writes the model to the file <code>filename</code>. The second parameter can return the total number of conversion failures (pass <code>NULL</code><code></code> if you're not interested). The functions in <a href="usage.html#Controlling_some_settings">this section</a> can be used before <code>gom_write_file</code> to control some settings.<br>
+<br>
+Before you write the file, you can update the timestamp in the header using the following function:<br>
+<blockquote><code>int <b>gom_header_update_timestamp</b> (time_t tval);<br></code></blockquote>
+This sets the <code>date</code> and <code>time</code> fields of the header to the time indicated by <code>tval</code>.
+ The function returns 0 on success, non-zero if an error occurred. Typically,
+the function would be used as follows, to set the current time in the timestamp:<br>
+<blockquote><code>int result;<br>
+result = gom_header_update_timestamp(time(NULL));</code><br>
+</blockquote>
+<hr width="100%" size="2"><br>
+
<pre><font size="-1">$Id$<br>$Name$</font><br></pre>
<pre> </pre>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
<br>
<br>
<br>
projects / gedcom-parse.git / blobdiff