Functions of libvformat
***********************

 -- Function: VFORMATDECLSPEC bool_t vf_parse_init (
     VF_PROP_Taaaa*n_stringaaaaaProperty to locate string from
     VF_PARSER_T   **PP_PARSER,  Ptr to allocated parser.
     VF_OBJECT_T   PP_OBJECT   The object we're parsing into.

     )

     Allocate and initialise a parser.  To parse a VCARD (or any vObject) a user allocates a parser, pushes data through it using vf_parse_text() and finally calls vf_parse_end():

         VF_PARSER_T *p_parser;

         if (vf_parse_init(&p_parser, pp_object))
         {
             do
             {
                 char buffer[...];
                 int numchars;

                 numchars = get_chars_from_somewhere(buffer, ...);

                 ret = vf_parse_text(p_parser, buffer, numchars);
             }
             while (ret && (0 < charsread))
                 ;

             if (!vf_parse_end(p_parser))
             {
                 ret = FALSE;
             }
         }

     A parser allocated by vf_parse_init(), must be deallocated by calling vf_parse_end() whether or not parsing succeeds. Also, parsing may not be complete (ie. values may be held buffered and not evaluated fully or assigned to a VF_OBJECT_T) untill the final call to vf_parse_end() => after a vf_parse_init() you _must_ vf_parse_end().

     Returns TRUE iff parser allocated successfully.

 -- Function: VFORMATDECLSPEC bool_t vf_parse_text (

     VF_PARSER_T   *P_PARSER,    The parser
     char   *P_CHARS,  New characters to parse into object
     int   NUMCHARS  Number of new characters

     )

     Parse indicated text into the object associated with the VPARSE_T. See notes for vf_parse_init().

     Returns TRUE <=> allocation & syntax OK, FALSE else.

 -- Function: VFORMATDECLSPEC bool_t vf_parse_end (

     VF_PARSER_T   *P_PARSE   The parser

     )

     Ensure parse completion, release memory associated with the parser.

     Returns TRUE <=> parse complete with no error.

 -- Function: VFORMATDECLSPEC bool_t vf_read_file (

     VF_OBJECT_T   **PP_OBJECT,  Pointer to output object
     const char   *P_NAME,  Name of file to read

     )

     Reads indicated VOBJECT_T file.

     Returns TRUE <=> read OK, FALSE else.

 -- Function: VFORMATDECLSPEC bool_t vf_write_file (

     const char   *P_NAME,  Output filename
     VF_OBJECT_T   *P_OBJECT,  The object to write
     bool_t   WRITE_ALL  Should write p_next as well?

     )

     Write indicated vobject to file.  For lists of objects (eg. read from a phonebook) the write_all parameter allows the caller to control if the library writes the entire list or just the head item.

     Returns TRUE <=> written OK, FALSE else.

 -- Function: VFORMATDECLSPEC bool_t vf_get_next_object (

     VF_OBJECT_T   **PP_OBJECT  Ptr to pointer to current object

     )

     Find "next" vobject.  Typically called after a call to vf_read_file() which may well read a list of objects from a file for example:

             if (vf_read_file(&p_object, p_filename))
             {
                     do
                     {
                       ...
                     }
                     while (vf_get_next_object(&p_object))
                     ;
             }

     The value of *pp_object is updated by the call if it returns TRUE.

     Returns TRUE iff found (ie. there is a "next" object).

 -- Function: VFORMATDECLSPEC VF_OBJECT_T * vf_create_object (

     const char   *P_TYPE,  Type of object to create
     VF_OBJECT_T   *P_PARENT  Parent object if any

     )

     Creates an empty vformat object.

     Returns  Ptr to object if created else NULL.

 -- Function: const VFORMATDECLSPEC char * vf_get_object_type (

     VF_OBJECT_T   *P_OBJECT  Object to locate type of

     )

     Return the type string identifying the indicated vformat object, the string after the 'BEGIN' mark so 'VCARD' or 'VNOTE' etc.

     Return  Ptr to string.

 -- Function: VFORMATDECLSPEC bool_t vf_get_property (

     VF_PROP_T   **PP_PROP,          Output pointer
     VF_OBJECT_T   *P_OBJECT,        Object to add to
     vf_get_t   OPS,                 Search flags
     const char   *P_GROUP,          Group name if any
     const char   *P_NAME,           Name of tag
     const char   *P_QUALIFIER,      First qualifier if any
     ...                                   Subequent qualifiers

     )

     Basic searching function locating elements of the VOBJECT by qualified name.  The function is a varargs function (like sprintf) and the list of arguments must be NULL terminated (hence the appearance of the p_qualifier argument in the arglist).  Valid calls might be:

            vf_get_property(&p_out, p_object, VFGP_FIND, NULL, "N", NULL);
              - find and return "N" properties.  If there are none, return FALSE.

            vf_get_property(&p_out, p_object, VFGP_FIND, NULL, "TEL", "WORK", NULL);
              - find and return "TEL" entries qualified by the "work" attribute
                (ie. work phone numbers). If there are none, return FALSE.

            vf_get_property(&p_out, p_object, VFGP_GET, NULL, "TEL", "WORK", NULL);
              - find and return work phone number.  The entry is automatically
              added if not pre-existing.

            vf_get_property(&p_out, p_object, VFGP_GET, NULL, "TEL", "WORK", NULL);
              - find and return work phone numbers in the group identifier by the "ME"
              identifier.  The entry is automatically added if not pre-existing.

            vf_get_property(&p_out, p_object, VFGP_FIND, "ME", "*", NULL);
              - effectively enumerates all entries in the "ME" group.

     A pointer to the first property matching the search criteria is returned via the pp_prop argument.  The search actually locates all such matches and pointer to subsequent entries (if there are >1) may be found by calling the vf_get_next_property() function.

     The tags may occur in any order _except_ that the p_name must be first.

     Note that the VF_PROP_T returned by pp_prop is an opaque type and the functions vf_get_prop_xxxx() etc. must be used to locate real "values".

     Cached search results (the list enumerated by subsequent calls to the vf_get_next_property() function) are maintained through the use of a a single internal pointer therefore this method is not thread safe.

     Returns TRUE iff found/added successfully.  Ptr to prop returned via pp_prop.

 -- Function: VFORMATDECLSPEC bool_t vf_get_property_ex (

     VF_PROP_T   **PP_PROP,          Output pointer
     VF_OBJECT_T   *P_OBJECT,        Object to search
     vf_get_t   OPS,                 Search flags
     const char   *P_GROUP,          Group name if any
     const char   *P_NAME,           Name of tag
     const char   *P_QUALIFIER,      First qualifier if any
     va_list args                            Argument list

     )

     The grunt behind vf_get_property(). Manages the search as described vf_get_property() but takes the list of arguments as a va_list. This function should be used when writing higher layer functions which take varargs (eg. DDX functions).

     Returns TRUE iff found/added successfully.  ptr to prop returned via pp_prop.

 -- Function: bool_t vf_get_next_property (

     VF_PROP_T   **PP_PROP,     Output pointer

     )

     Find the next property given the current search critera.  User calls vf_get_property() to locate first in a bunch of properties and can iterate over the rest by calling vf_get_next_property().

     Returns TRUE iff found, FALSE else. *pp_prop points to the nex property.

 -- Function: bool_t vf_get_prop_value (

     VF_PROP_T   *P_PROP,                The property
     void   **PP_VALUE,                  Pointer value
     uint32_t   *P_SIZE,                 Integer value
     vf_encoding_t   *P_ENCODING         Type of return values

     )

     Get hold of raw fields associated with the property.  These are of rious types:

          VF_ENC_VOBJECT
            - *pp_value = pointer to contained VF_OBJECT_T which can be
            passed back to any of the object manipulation functions.

          VF_ENC_7BIT, VF_ENC_QUOTEDPRINTABLE
            - *pp_value = ptr to array of char*, *p_size = number of elts.

          VF_ENC_8BIT, VF_BASE64
            - *pp_value = ptr to bytes, *p_size = number of bytes

     Returns TRUE <=> encoding is valid, FALSE else.

 -- Function: bool_t vf_set_prop_value (

     VF_PROP_T   *P_PROP,                The property
     void   *P_VALUE,                    Pointer to the data
     uint32_t   N_PARAM,                 Data size or index
     vf_encoding_t   ENCODING,           Encoding in use
     bool_t   COPY                       Copy the data?

     )

     Set values associated with a property.

     Passing a value of encoding not the same as the current property encoding will cause the property contents to be freed prior to setting the indicated value.

     Returns TRUE <=> re-allocation success & encoding correct, FALSE else.

 -- Function: char * vf_get_prop_value_string (

     VF_PROP_T   *P_PROP,   Property to locate string from
     uint32_t   N_STRING   Index to string required

     )

     Obtain string pointer value from VF_PROP_T.  For example a property may be defined as:

     THING;THIS=STUFF;WITH-QUALIFIERS:fred-fred-fred;gogogo;baabaabaa

     A call to vf_get_prop_value_string() specifying n_string=1 will return a pointer to the gogogo value.

     Return NULL if out of range request, ie. n_string=3 for N:0;1;2

     Returns Pointer to string value if value present, NULL if index  too large.

 -- Function: bool_t vf_get_prop_value (

     VF_PROP_T   *P_PROP,                The property
     void   **PP_VALUE,                  Pointer value
     vf_encoding_t   *P_ENCODING,         Type
     of return values
     uint32_t   *P_SIZE,                 Integer value

     )

     Get hold of raw fields associated with the property.  These are of various types:

     VF_ENC_VOBJECT - *pp_value = pointer to contained VF_OBJECT_T which can be passed back to any of the object manipulation functions.

     VF_ENC_7BIT, VF_ENC_QUOTEDPRINTABLE - *pp_value = ptr to array of char*, *p_size = number of elts.

     VF_ENC_8BIT, VF_BASE64 - *pp_value = ptr to bytes, *p_size = number of bytes

     Returns TRUE <=> encoding is valid, FALSE else.

 -- Function: VFORMATDECLSPEC bool_t vf_set_prop_value (

     VF_PROP_T   *P_PROP,                The property
     void   *P_VALUE,                    Pointer to the data
     uint32_t   N_PARAM,                 Data size or index
     vf_encoding_t   ENCODING,           Encoding in use
     bool_t   COPY                       Copy the data?

     )

     Set values associated with a property.

     Passing a value of encoding not the same as the current property encoding will cause the property contents to be freed prior to setting the indicated value. Returns TRUE <=> re-allocation success & encoding correct, FALSE else.

 -- Function: VFORMATDECLSPEC char * vf_get_prop_value_string (

     VF_PROP_T   *P_PROP,                Property to locate string from
     uint32_t   N_STRING                 Index to string required

     )

     Obtain string pointer value from VF_PROP_T.  For example a property may be defined as:

     THING;THIS=STUFF;WITH-QUALIFIERS:fred-fred-fred;gogogo;baabaabaa

     A call to vf_get_prop_value_string() specifying n_string=1 will return a pointer to the gogogo value.

     Return NULL if out of range request, ie. n_string=3 for N:0;1;2

     Returns Pointer to string value if value present, NULL if index  too large.

 -- Function: VFORMATDECLSPEC char * vf_get_prop_name_string (

     VF_PROP_T   *P_PROP,                Property to locate string from
     uint32_t   N_STRING                 Index to string required

     )

     Get n'th name string.  For example a property may be defined as: THING;THIS=STUFF;WITH-QUALIFIERS:fred-fred-fred;gogogo;baabaabaa A call to vf_get_prop_name_string() specifying n_string=2 will return a pointer to the WITH-QUALIFIERS value. Return NULL if out of range request, ie. n_string=4 for X;A;B;C:foo

     Returns Pointer to string value if value present, NULL if index  too large.

 -- Function: VFORMATDECLSPEC bool_t vf_set_prop_name_string (

     VF_PROP_T   *P_PROP,                Property we're setting a value in
     uint32_t   N_STRING,                Index to string
     const char   *P_STRING              Pointer to string

     )

     Set n'th name string.

     Returns TRUE iff allocation OK, FALSE else.

 -- Function: VFORMATDECLSPEC void vf_get_prop_name (

     VF_PROP_T   *P_PROP,                The property
     char   *P_BUFFER,                   The buffer
     uint32_t   BUFSIZE                  Size of the buffer

     )

     Build the property name string in the indicated buffer.

     Returns (none)

 -- Function: VFORMATDECLSPEC VF_OBJECT_T * vf_get_prop_value_object (

     VF_PROP_T   *P_PROP                 Property to locate object from

     )

     Obtain object pointer value from VF_PROP_T.

     Returns Pointer to vobject value (or NULL if not found).

 -- Function: VFORMATDECLSPEC bool_t vf_set_prop_value_object (

     VF_PROP_T   *P_PROP,
     VF_OBJECT_T   *P_OBJECT

     )

     Set the value of the indicated property to be a VOBJECT.

     Returns TRUE <=> set successfully.

 -- Function: VFORMATDECLSPEC bool_t vf_set_prop_value_string (

     VF_PROP_T   *P_PROP,                Property we're setting a value in
     uint32_t   N_STRING,                Index to string
     const char   *P_STRING              Pointer to string

     )

     Set the value of a property.

     Returns TRUE <=> set successfully.

 -- Function: VFORMATDECLSPEC bool_t vf_set_prop_value_base64 (

     VF_PROP_T   *P_PROP,                Property we're setting a value in
     const uint8_t   *P_DATA,            Pointer to the binary data
     uint32_t   LENGTH,                  Length of the binary data
     bool_t   COPY                       Copy or keep pointer

     )

     Set the value of a property.

     Returns TRUE <=> set successfully.

 -- Function: const VFORMATDECLSPEC uint8_t * vf_get_prop_value_base64 (

     VF_PROP_T   *P_PROP,                Property we're setting a value in
     uint32_t   *P_LENGTH                Length of the binary data

     )

     Get a BASE64 property.  Returns ptr, passes length via parameter.

     Returns Ptr to data.

 -- Function: VFORMATDECLSPEC bool_t vf_set_property_from_file (

     VF_PROP_T   *P_PROP,                The property
     vf_encoding_t   ENCODING,           Encoding to use
     const char   *P_FILENAME            Source filename

     )

     Loads the indicated file into memory and sets the indicated property.

     Returns TRUE iff succeded, FALSE else.

 -- Function: VFORMATDECLSPEC void vf_delete_object (

     VF_OBJECT_T   *P_OBJECT,            The object to delete
     bool_t   ALL                        Delete all subsequent objects?

     )

     Cleans up the memory used by the indicated vformat object.

     Returns (none)

 -- Function: VFORMATDECLSPEC  void vf_delete_prop (

     VF_OBJECT_T   *P_OBJECT,            The object we're deleting from
     VF_PROP_T   *P_PROP,                The property we're removing
     bool_t dc                         Should property contents be deleted?

     )

     Deletes indicated property from the indicated object.  Deletes prop contents if dc is set.

     Returns (none)

 -- Function: VFORMATDECLSPEC  bool_t vf_find_prop_qual_index (

     VF_PROP_T   *P_PROP,                    The property we're querying
     uint32_t   *P_QUALIFIER_INDEX,          Ptr to output name index
     uint32_t   *P_FOUND_VALUE_INDEX,        Ptr to output index in array
     const char   **PP_POSSIBLE_VALUES,      Array of possible values
     const char   *P_TOKEN,                  Token searched for
     vf_search_flags_t   MATCH               String comparison flags

     )

     Locate property qualifier given either an array of possible values or a single token that is either present or absent.  For example if we have a property:

     NAME;THIRD;TIME;LUCKY:VALUE1;VALUE2;VALUE3

     Then there are two possible searches.

     Firstly we can look for the property qualifier which can take values from the array { "FIRST", "SECOND", THIRD" } in which case the array is passed as pp_possible_values and the function returns with the values *p_found_value_index=2, p_qualifier_index=1

     Secondly we can look for the token with value "TIME" in which case p_token is set to "TIME" and the function returns *p_qualifier_index=2.

     Returns TRUE iff found, FALSE else.

 -- Function: VFORMATDECLSPEC  bool_t vf_is_modified (

     VF_OBJECT_T   *P_OBJECT             The object

     )

     Fetch status of modified flag.

     Returns TRUE iff modified since list read/write.

 -- Function: VFORMATDECLSPEC  const char * vf_find_charset (

     VF_PROP_T   *P_PROP                 The property we're querying

     )

     Locate the CHARSET property which indicates the character encoding in use - which indicates how the octet stream encoded in the VCARD is to be decoded into characters.

     Returns Pointer to character encoding name eg. "UTF-8".

 -- Function: VFORMATDECLSPEC  bool_t vf_date_string_to_time (

     uint32_t   *P_TIME,                 Output time value
     const char   *P_STRING              Input string

     )

     Convert calendar string to absolute time.  The basic formats are 19960401, 19960401T073000Z

     Returns TRUE <=> conversion OK, FALSE else.

 -- Function: VFORMATDECLSPEC  bool_t vf_period_string_to_time (

     VF_ISO8601_PERIOD_T   *P_PERIOD,    Output time value
     const char   *P_STRING              Input string

     )

     Convert period definition string to time value.  The format is P[aaaY][bbbM][cccW][dddD]T[eeeH][fffM][gggS] where 'aaa' is a number of years, bbb months etc.

     Returns TRUE <=> conversion OK, FALSE else.

 -- Function: VFORMATDECLSPEC  uint32_t vf_period_time_to_string (

     char   *P_STRING,                       Output string
     const VF_ISO8601_PERIOD_T   *P_PERIOD   Input period value

     )

     Convert a VF_ISO8601_PERIOD_T to a string.

     Returns Number of characters written.

 -- Function: VFORMATDECLSPEC  bool_t vf_set_prop_value_time (

     VF_PROP_T   *P_PROP,            The property
     uint32_t   N_STRING,            Which string we're encoding to
     const time_t   T_VALUE          Time value

     )

     Set a time_t value into a VF property.

     Returns TRUE iff property added & set OK.

 -- Function: VFORMATDECLSPEC  bool_t vf_get_prop_value_time (

     VF_PROP_T   *P_PROP,            The property
     uint32_t   N_STRING,            Which string we're decoding
     time_t   *P_T_VALUE             Pointer to output time value

     )

     Fetch a time_t value from a VF property.

     Returns TRUE iff foudn & converted OK.