- </h4>
-As a simple example, we will get some information from the header of a GEDCOM
-file. First, have a look at the following piece of code:<br>
- <blockquote><code>Gedcom_ctxt <b>my_header_start_cb</b> (int level,
-Gedcom_val xref, char *tag)<br>
-{<br>
- printf("The header starts\n");<br>
- return (Gedcom_ctxt)1;<br>
-}<br>
- <br>
-void <b>my_header_end_cb</b> (Gedcom_ctxt self)<br>
-{<br>
- printf("The header ends, context is %d\n", self); /* context
-will print as "1" */<br>
-}<br>
- <br>
-...<br>
- <b>gedcom_subscribe_to_record</b>(REC_HEAD, my_header_start_cb, my_header_end_cb);<br>
-...<br>
-result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
- </blockquote>
- Using the <code>gedcom_subscribe_to_record</code> function, the application
-requests to use the specified callbacks as start and end callback. The end
-callback is optional: you can pass <code>NULL</code> if you are not interested
-in the end callback. The identifiers to use as first argument to the
-function (here <code>REC_HEAD</code>) are described in <i>TBD (use the header
-file for now...)</i>.<br>
- <br>
-From the name of the function it becomes clear that this function is specific
-to complete records. For the separate elements in records there is
-another function, which we'll see shortly. Again, the callbacks need
-to have the signatures as shown in the example.<br>
- <br>
-The <code>Gedcom_ctxt</code> type that is used as a result of the start callback
-and as an argument to the end callback is vital for passing context necessary
-for the application. This type is meant to be opaque; in fact, it's
-a void pointer, so you can pass anything via it. The important thing
-to know is that the context that the application returns in the start callback
-will be passed in the end callback as an argument, and as we will see shortly,
-also to all the directly subordinate elements of the record.<br>
- <br>
-The example passes a simple integer as context, but an application could
-e.g. pass a <code>struct</code> that will contain the information for the
-header. In the end callback, the application could then e.g. do some
-finalizing operations on the <code>struct</code> to put it in its database.<br>
- <br>
-(Note that the <code>Gedcom_val</code> type for the <code>xref</code> argument
-was not discussed, see further for this)<br>
- <br>
- <h4><i>Callbacks for elements</i></h4>
-We will now retrieve the SOUR field (the name of the program that wrote the
-file) from the header:<br>
- <blockquote><code>Gedcom_ctxt <b>my_header_source_start_cb</b>(Gedcom_ctxt
-parent,<br>
-
- int
- level,<br>
-
- char*
- tag,<br>
-
- char*
- raw_value,<br>
-
- Gedcom_val parsed_value)<br>
-{<br>
- char *source = GEDCOM_STRING(parsed_value);<br>
- printf("This file was written by %s\n", source);<br>
- return parent;<br>
-}<br>
- <br>
-void <b>my_header_source_end_cb</b>(Gedcom_ctxt parent,<br>
-
- Gedcom_ctxt self,<br>
-
- Gedcom_val parsed_value)<br>
-{<br>
- printf("End of the source description\n");<br>
-}<br>
- <br>
-...<br>
- <b>gedcom_subscribe_to_element</b>(ELT_HEAD_SOUR,<br>
-
- my_header_source_start_cb,<br>
-
- my_header_source_end_cb);<br>
-...<br>
-result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
- </blockquote>
-The subscription mechanism for elements is similar, only the signatures of
-the callbacks differ. The signature for the start callback shows that
-the context of the parent line (e.g. the <code>struct</code> that describes
-the header) is passed to this start callback. The callback itself returns
-here the same context, but this can be its own context object of course.
- The end callback is called with both the context of the parent and
-the context of itself, which will be the same in the example.<br>
- <br>
-If we look at the other arguments of the start callback, we see the level
-number (the initial number of the line in the GEDCOM file), the tag (e.g.
-"SOUR"), and then a raw value and a parsed value. The raw value is
-just the raw string that occurs as value on the line next to the tag (in
-UTF-8 encoding). The parsed value is the meaningful value that is parsed
-from that raw string.<br>
- <br>
-The <code>Gedcom_val</code> type is meant to be an opaque type. The
-only thing that needs to be known about it is that it can contain specific
-data types, which have to be retrieved from it using pre-defined macros.
- Currently, the specific types are (with <code>val</code> of type <code>
-Gedcom_val</code>):<br>
- <br>
- <table cellpadding="2" cellspacing="2" border="1" width="100%">
- <tbody>
- <tr>
- <td valign="top"><br>
- </td>
- <td valign="top"><b>type checker</b><br>
- </td>
- <td valign="top"><b>cast operator</b><br>
- </td>
- </tr>
- <tr>
- <td valign="top">null value<br>
- </td>
- <td valign="top"><code>GEDCOM_IS_NULL(val)</code><br>
- </td>
- <td valign="top">N/A<br>
- </td>
- </tr>
- <tr>
- <td valign="top">string<br>
- </td>
- <td valign="top"><code>GEDCOM_IS_STRING(val)</code><br>
- </td>
- <td valign="top"><code>char* str = GEDCOM_STRING(val);</code><br>
- </td>
- </tr>
- <tr>
- <td valign="top">date<br>
- </td>
- <td valign="top"><code>GEDCOM_IS_DATE(val)</code><br>
- </td>
- <td valign="top"><code>struct date_value dv = GEDCOM_DATE(val)
-;</code><br>
- </td>
- </tr>
- </tbody>
- </table>
- <br>
-The null value is used for when the GEDCOM spec doesn't allow a value, or
-when an optional value is allowed but none is given.<br>
- <br>
-The string value is the most general used value currently, for all those
-values that don't have a more specific meaning. In essence, the value
-that is returned by GEDCOM_STRING is always the same as the raw_value 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. (<i>Description
-of struct date_value TBD: look in the header file for the moment</i>).<br>
- <br>
-The type checker returns a true or a false value according to the type of
-the value, but this is in principle only necessary in the rare circumstances
-that two types are possible, or where an optional value can be provided.
- In most cases, the type is fixed for a specific tag (<i>types per tag
-to be described</i>).<br>
+ </h4>
+ As a simple example, we will get some information from the header of
+a GEDCOM file. First, have a look at the following piece of code:<br>
+
+ <blockquote><code>Gedcom_ctxt <b>my_header_start_cb</b> (int level,
+ <br>
+
+ Gedcom_val xref, <br>
+
+ char *tag, <br>
+
+ char *raw_value,<br>
+
+ int parsed_tag, <br>
+
+ Gedcom_val parsed_value)<br>
+ {<br>
+ printf("The header starts\n");<br>
+ return (Gedcom_ctxt)1;<br>
+ }<br>
+ <br>
+ void <b>my_header_end_cb</b> (Gedcom_ctxt self)<br>
+ {<br>
+ printf("The header ends, context is %d\n", self); /* context
+ will print as "1" */<br>
+ }<br>
+ <br>
+ ...<br>
+ <b>gedcom_subscribe_to_record</b>(REC_HEAD, my_header_start_cb,
+ my_header_end_cb);<br>
+ ...<br>
+ result = <b>gedcom_parse_file</b>("myfamily.ged");</code><br>
+ </blockquote>
+ Using the <code>gedcom_subscribe_to_record</code> function, the application
+ requests to use the specified callbacks as start and end callback. The end
+ callback is optional: you can pass <code>NULL</code> if you are not interested
+ in the end callback. The identifiers to use as first argument to
+the function (here <code>REC_HEAD</code>) are described in the <a href="interface.html#Record_identifiers">
+ interface details</a>.<br>
+ <br>
+ From the name of the function it becomes clear that this function is
+specific to complete records. For the separate elements in records
+there is another function, which we'll see shortly. Again, the callbacks
+need to have the signatures as shown in the example.<br>
+ <br>
+ The <code>Gedcom_ctxt</code> type that is used as a result of the start
+ callback and as an argument to the end callback is vital for passing context
+ necessary for the application. This type is meant to be opaque; in
+ fact, it's a void pointer, so you can pass anything via it. The important
+ thing to know is that the context that the application returns in the start
+ callback will be passed in the end callback as an argument, and as we will
+ see shortly, also to all the directly subordinate elements of the record.<br>