+ 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 <code>tag</code> is the GEDCOM tag in string format, the <code>parsed_tag</code>
+ is an integer, for which symbolic values are defined as <code>TAG_HEAD,</code>
+ <code>TAG_SOUR,</code> <code>TAG_DATA,</code> ... and <code>USERTAG </code><code></code>
+ for the application-specific tags. These values are defined in the
+ header <code>gedcom-tags.h</code> that is installed, and included via <code>
+ gedcom.h</code> (so no need to include <code>gedcom-tags.h</code> yourself).<br>
+ <br>
+ The example passes a simple integer as context, but an application could
+ e.g. pass a <code>struct</code> (or an object in a C++ application) 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>
+ and <code>parsed_value</code> arguments 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>
+
+ int
+ parsed_tag,<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 (here e.g. the <code>struct</code> that
+describes the header) is passed to this start callback. The callback
+itself returns here in this example 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 in this example will be the same.
+ Again, the list of identifiers to use as a first argument for the
+subscription function are detailed in the <a href="interface.html#Element_identifiers">
+ interface details</a> .<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, a parsed tag 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. The parsed tag is described in
+ the section for record callbacks above.<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.
+ These data types are described in the <a href="interface.html#Gedcom_val_types">
+ interface details</a>. <br>
+ <br>
+ Some extra notes:<br>
+
projects / gedcom-parse.git / blobdiff