X-Git-Url: https://git.dlugolecki.net.pl/?a=blobdiff_plain;f=doc%2Fgom.html;h=4ab405a46e50422fdcca56d0358c7863772566b7;hb=295e0273f2ff3bb95f7afb1ac639ab7203672c9c;hp=f36dbd0c33ab5c7be3ac8c22fed8f4a2c06167d0;hpb=5d16fb60418c30cd6693556ac6d56d6c0f8cd7a6;p=gedcom-parse.git diff --git a/doc/gom.html b/doc/gom.html index f36dbd0..4ab405a 100644 --- a/doc/gom.html +++ b/doc/gom.html @@ -22,12 +22,13 @@ -
  • Other functions
    • +
  • Modifying the object model
  • Writing the object model to file
    +
    • - + @@ -125,7 +126,12 @@ tags is.  Each element of the linked list has:
    This way, none of the information in the GEDCOM file is lost, even the non-standard information.

    -

    Other functions

    +

    Modifying the object model

    Currently, there are only functions available to modify strings in the model (and the date manipulation functions described here). + In principle it is possible to add new records, notes, ... yourself, +but you have to know what you are doing, because you should keep the model +consistent.  In the next release, functions will be available to add, +remove and modify anything in the model.
    +

    Manipulating strings

    There are some functions available to retrieve and change strings in the @@ -134,16 +140,16 @@ or locale-defined strings.

    The following functions retrieve and set the string in UTF-8 encoding:
    char* gom_get_string (char* data);
    -char* gom_set_string (char** data, const char* utf8_str);
    +char* gom_set_string (char** data, const char* str_in_utf8);
    The first function is in fact superfluous, because it just returns the data, but it is there for symmetry with the functions given below for the locale-defined input and output.  

    The second function returns the new value if successful, or NULL -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.
    +it.  In the case of an error, the target data variable is not modified.

    Examples of use of these strings would be, e.g. for retrieving and setting the system ID in the header:
    struct header* head = gom_get_header();
    @@ -157,17 +163,35 @@ char* newvalue = "My_Gedcom_Tool";

    A second couple of functions retrieve and set the string in the format defined by the current locale:
    char* gom_get_string_for_locale (char* data, int* conversion_failures);
    -char* gom_set_string_for_locale (char** data, const char* locale_str)    ;
    +char* gom_set_string_for_locale (char** data, const char* str_in_locale);
    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 locale_str to be in this encoding.  Conversion to and from UTF-8 for the object model is done on the fly.
    +ISO-8859-1 encoding and the second function expects the str_in_locale to be in this encoding.  Conversion to and from UTF-8 for the object model is done on the fly.

    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 NULL if you're not interested.
    +want to know this.  You can pass NULL if you're not interested.  The function returns NULL +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.
    +

    Writing the object model to file
    +

    +Writing the current object model to a file is simply done using the following function:
    +
    int gom_write_file (const char* filename, int* total_conv_fails);
    +This writes the model to the file filename.  The second parameter can return the total number of conversion failures (pass NULL if you're not interested).  The functions in this section can be used before gom_write_file to control some settings.
    +
    +Before you write the file, you can update the timestamp in the header using the following function:
    +
    int gom_header_update_timestamp (time_t tval);
    +This sets the date and time fields of the header to the time indicated by tval. + 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:
    +
    int result;
    +result = gom_header_update_timestamp(time(NULL));
    +
    +

    + 
    $Id$
    $Name$
    @@ -175,6 +199,11 @@ want to know this.  You can pass NULL if you're not interested
    +
    +
    +
    +
    +