path: root/doc/libvformat-1.texi

@node    Functions of libvformat
@chapter Functions of libvformat
@deftypefun  {VFORMATDECLSPEC bool_t} vf_parse_init (
@multitable{VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PARSER_T @tab @var{**pp_parser},@tab Ptr to allocated parser.  
@item VF_OBJECT_T @tab @var{pp_object} @tab The object we're parsing into. 
@end multitable
)



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():

@verbatim

    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;
        }
    }

@end verbatim

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. 

@end deftypefun

@deftypefun  {VFORMATDECLSPEC bool_t} vf_parse_text (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item  VF_PARSER_T @tab @var{*p_parser}, @tab  The parser 
@item  char @tab @var{*p_chars},@tab New characters to parse into object 
@item  int @tab @var{numchars}@tab Number of new characters 
@end multitable
)


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

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

@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_parse_end (
            @multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
            @item VF_PARSER_T @tab @var{*p_parse} @tab The parser 
            @end multitable
            )



Ensure parse completion, release memory associated with the parser.

Returns TRUE <=> parse complete with no error.
@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_read_file (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_OBJECT_T @tab @var{**pp_object},@tab Pointer to output object 
@item const char @tab @var{*p_name},@tab Name of file to read
@end multitable
)

          
Reads indicated VOBJECT_T file.

Returns TRUE <=> read OK, FALSE else.

@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_write_file (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item const char @tab @var{*p_name},@tab Output filename
@item VF_OBJECT_T @tab @var{*p_object},@tab The object to write
@item bool_t @tab @var{write_all}@tab Should write p_next as well?
@end multitable
)


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.

@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_get_next_object (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_OBJECT_T @tab @var{**pp_object}@tab Ptr to pointer to current object
@end multitable
)



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: 

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

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

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

@deftypefun {VFORMATDECLSPEC VF_OBJECT_T *} vf_create_object (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item const char @tab @var{*p_type},@tab Type of object to create
@item VF_OBJECT_T @tab @var{*p_parent}@tab Parent object if any
@end multitable
)


Creates an empty vformat object.

Returns  Ptr to object if created else NULL.
@end deftypefun

@deftypefun {const VFORMATDECLSPEC char *} vf_get_object_type (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_OBJECT_T @tab @var{*p_object}@tab Object to locate type of
@end multitable
)



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

Return  Ptr to string.
@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_get_property (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{**pp_prop},        @tab Output pointer         
@item VF_OBJECT_T @tab @var{*p_object},      @tab Object to add to       
@item vf_get_t @tab @var{ops},               @tab Search flags           
@item const char @tab @var{*p_group},        @tab Group name if any        
@item const char @tab @var{*p_name},         @tab Name of tag 	       
@item const char @tab @var{*p_qualifier},    @tab First qualifier if any 
@item ...       @tab                         @tab Subequent qualifiers   
@end multitable
)


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:

@example
  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.
@end example

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.

@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_get_property_ex (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{**pp_prop},        @tab Output pointer                    
@item VF_OBJECT_T @tab @var{*p_object},      @tab Object to search	    
@item vf_get_t @tab @var{ops},               @tab Search flags	            
@item const char @tab @var{*p_group},        @tab Group name if any	    
@item const char @tab @var{*p_name},         @tab Name of tag		    
@item const char @tab @var{*p_qualifier},    @tab First qualifier if any    
@item va_list args                          @tab Argument list         
@end multitable
)             


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.

@end deftypefun

@deftypefun bool_t vf_get_next_property (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{**pp_prop},   @tab Output pointer
@end multitable
)



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.

@end deftypefun

@deftypefun bool_t vf_get_prop_value (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab The property
@item void @tab @var{**pp_value},                @tab Pointer value
@item uint32_t @tab @var{*p_size},               @tab Integer value
@item vf_encoding_t @tab @var{*p_encoding}       @tab Type of return values
@end multitable
)   

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

@example
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
@end example

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


@end deftypefun


@deftypefun bool_t vf_set_prop_value (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item     VF_PROP_T @tab @var{*p_prop},              @tab The property
@item     void @tab @var{*p_value},                  @tab Pointer to the data 
@item     uint32_t @tab @var{n_param},               @tab Data size or index 
@item     vf_encoding_t @tab @var{encoding},         @tab Encoding in use 
@item      bool_t @tab @var{copy}                     @tab Copy the data? 
@end multitable
)

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.

@end deftypefun

@deftypefun {char *} vf_get_prop_value_string (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item           VF_PROP_T @tab @var{*p_prop}, @tab Property to locate string from
@item           uint32_t @tab @var{n_string} @tab Index to string required
@end multitable
)

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.

@end deftypefun

@deftypefun bool_t vf_get_prop_value (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}     
@item           VF_PROP_T @tab @var{*p_prop},              @tab The property 
@item           void @tab @var{**pp_value},                @tab Pointer value 
@item           vf_encoding_t @tab @var{*p_encoding},       @tab Type
of return values 
@item           uint32_t @tab @var{*p_size},               @tab Integer value      
@end multitable    
)

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.


@end deftypefun



@deftypefun {VFORMATDECLSPEC bool_t} vf_set_prop_value (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab The property 
@item void @tab @var{*p_value},                  @tab Pointer to the data 
@item uint32_t @tab @var{n_param},               @tab Data size or index 
@item vf_encoding_t @tab @var{encoding},         @tab Encoding in use 
@item bool_t @tab @var{copy}                     @tab Copy the data? 
@end multitable  
)

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.



@end deftypefun

@deftypefun {VFORMATDECLSPEC char *} vf_get_prop_value_string (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab Property to locate string from 
@item uint32_t @tab @var{n_string}               @tab Index to string required 
@end multitable  
)

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.




@end deftypefun

@deftypefun {VFORMATDECLSPEC char *} vf_get_prop_name_string ( 
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab Property to locate string from 
@item uint32_t @tab @var{n_string}               @tab Index to string required 
@end multitable  
)


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.


@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_set_prop_name_string (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab Property we're setting a value in 
@item uint32_t @tab @var{n_string},              @tab Index to string 
@item const char @tab @var{*p_string}            @tab Pointer to string 
@end multitable  
)



Set n'th name string.

Returns TRUE iff allocation OK, FALSE else.

@end deftypefun

@deftypefun {VFORMATDECLSPEC void} vf_get_prop_name (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab The property 
@item char @tab @var{*p_buffer},                 @tab The buffer 
@item uint32_t @tab @var{bufsize}                @tab Size of the buffer 
@end multitable  
)




Build the property name string in the indicated buffer.

Returns (none)



@end deftypefun

@deftypefun {VFORMATDECLSPEC VF_OBJECT_T *} vf_get_prop_value_object (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop}               @tab Property to locate object from 
@end multitable  
)


Obtain object pointer value from VF_PROP_T.

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


@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_set_prop_value_object (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},
@item VF_OBJECT_T @tab @var{*p_object}
@end multitable  
)


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

Returns TRUE <=> set successfully.


@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_set_prop_value_string (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab Property we're setting a value in 
@item uint32_t @tab @var{n_string},              @tab Index to string 
@item const char @tab @var{*p_string }           @tab Pointer to string 
@end multitable  
)

Set the value of a property.

Returns TRUE <=> set successfully.



@end deftypefun

@deftypefun {VFORMATDECLSPEC bool_t} vf_set_prop_value_base64 (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab Property we're setting a value in 
@item const uint8_t @tab @var{*p_data},          @tab Pointer to the binary data 
@item uint32_t @tab @var{length},                @tab Length of the binary data 
@item bool_t @tab @var{copy}                     @tab Copy or keep pointer 
@end multitable  
)



Set the value of a property.

Returns TRUE <=> set successfully.


@end deftypefun

@deftypefun {const VFORMATDECLSPEC uint8_t *} vf_get_prop_value_base64 (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab Property we're setting a value in 
@item uint32_t @tab @var{*p_length}              @tab Length of the binary data 
@end multitable  
)



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

Returns Ptr to data.


@end deftypefun

@deftypefun  {VFORMATDECLSPEC bool_t} vf_set_property_from_file (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},              @tab The property 
@item vf_encoding_t @tab @var{encoding},         @tab Encoding to use     
@item const char @tab @var{*p_filename}          @tab Source filename 
@end multitable  
)



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

Returns TRUE iff succeded, FALSE else.


@end deftypefun

@deftypefun {VFORMATDECLSPEC void} vf_delete_object (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_OBJECT_T @tab @var{*p_object},          @tab The object to delete 
@item bool_t @tab @var{all }                     @tab Delete all subsequent objects? 
@end multitable  
)


Cleans up the memory used by the indicated vformat object.

Returns (none)


@end deftypefun

@deftypefun {VFORMATDECLSPEC  void} vf_delete_prop (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_OBJECT_T @tab @var{*p_object},          @tab The object we're deleting from 
@item VF_PROP_T @tab @var{*p_prop},              @tab The property we're removing 
@item bool_t dc                       @tab Should property contents be deleted? 
@end multitable  
)


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

Returns (none)


@end deftypefun

@deftypefun {VFORMATDECLSPEC  bool_t} vf_find_prop_qual_index (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},                  @tab The property we're querying 
@item uint32_t @tab @var{*p_qualifier_index},        @tab Ptr to output name index 
@item uint32_t @tab @var{*p_found_value_index},      @tab Ptr to output index in array 
@item const char @tab @var{**pp_possible_values},    @tab Array of possible values 
@item const char @tab @var{*p_token},                @tab Token searched for 
@item vf_search_flags_t @tab @var{match}             @tab String comparison flags 
@end multitable  
)



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.


@end deftypefun

@deftypefun {VFORMATDECLSPEC  bool_t} vf_is_modified (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_OBJECT_T @tab @var{*p_object}           @tab The object 
@end multitable  
)




Fetch status of modified flag.

Returns TRUE iff modified since list read/write.


@end deftypefun

@deftypefun {VFORMATDECLSPEC  const char *} vf_find_charset (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop}               @tab The property we're querying 
@end multitable  
)



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".


@end deftypefun

@deftypefun {VFORMATDECLSPEC  bool_t} vf_date_string_to_time (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item  uint32_t @tab @var{*p_time},               @tab Output time value 
@item const char @tab @var{*p_string}            @tab Input string 
@end multitable  
)



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

Returns TRUE <=> conversion OK, FALSE else.


@end deftypefun

@deftypefun {VFORMATDECLSPEC  bool_t} vf_period_string_to_time (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_ISO8601_PERIOD_T @tab @var{*p_period},  @tab Output time value 
@item const char @tab @var{*p_string}            @tab Input string 
@end multitable  
)


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.


@end deftypefun

@deftypefun {VFORMATDECLSPEC  uint32_t} vf_period_time_to_string (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item char @tab @var{*p_string},                     @tab Output string 
@item const VF_ISO8601_PERIOD_T @tab @var{*p_period} @tab Input period value 
@end multitable  
)


Convert a VF_ISO8601_PERIOD_T to a string.

Returns Number of characters written.


@end deftypefun

@deftypefun {VFORMATDECLSPEC  bool_t} vf_set_prop_value_time (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},          @tab The property 
@item uint32_t @tab @var{n_string},          @tab Which string we're encoding to 
@item const time_t @tab @var{t_value}        @tab Time value 
@end multitable  
)


Set a time_t value into a VF property.

Returns TRUE iff property added & set OK.

@end deftypefun

@deftypefun {VFORMATDECLSPEC  bool_t} vf_get_prop_value_time (
@multitable     {VF_PROP_Taaaa}{*n_stringaaaaa}{Property to locate string from}
@item VF_PROP_T @tab @var{*p_prop},          @tab The property 
@item uint32_t @tab @var{n_string},          @tab Which string we're decoding 
@item time_t @tab @var{*p_t_value}           @tab Pointer to output time value 
@end multitable  
)


Fetch a time_t value from a VF property.

Returns TRUE iff foudn & converted OK.

@end deftypefun