diff options
Diffstat (limited to 'doc/vf_get_property.3')
| -rw-r--r-- | doc/vf_get_property.3 | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/doc/vf_get_property.3 b/doc/vf_get_property.3 new file mode 100644 index 0000000..828e414 --- /dev/null +++ b/doc/vf_get_property.3 @@ -0,0 +1,128 @@ +.\" WARNING! THIS FILE WAS GENERATED AUTOMATICALLY BY c2man! +.\" DO NOT EDIT! CHANGES MADE TO THIS FILE WILL BE LOST! +.TH "vf_get_property" 3 "30 April 2003" "c2man vf_iface.h" +.SH "NAME" +vf_get_property \- vf_get_property() +.SH "SYNOPSIS" +.ft B +#include <../vformat/vf_iface.h> +.sp +extern bool_t vf_get_property +.br +( +.br + VF_PROP_T **pp_prop, +.br + VF_OBJECT_T *p_object, +.br + vf_get_t ops, +.br + const char *p_group, +.br + const char *p_name, +.br + const char *p_qualifier, +.br + ... +.br +); +.ft R +.SH "PARAMETERS" +.TP +.B "VF_PROP_T **pp_prop" +Output pointer. +.TP +.B "VF_OBJECT_T *p_object" +Object to add to. +.TP +.B "vf_get_t ops" +Search flags. +.TP +.B "const char *p_group" +Group name if any. +.TP +.B "const char *p_name" +Name of tag. +.TP +.B "const char *p_qualifier" +First qualifier if any. +.TP +.B "..." +Subequent qualifiers. +.SH "DESCRIPTION" +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); +.br +- Find and return "N" properties. If there are none, return FALSE. + +Vf_get_property(&p_out, p_object, VFGP_FIND, NULL, "TEL", "WORK", NULL); +.br +- 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); +.br +- 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); +.br +- 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); +.br +- 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. +.SH "RETURNS" +TRUE iff found/added successfully. Ptr to prop returned via pp_prop. +.SH "SEE ALSO" +vf_parse_init(3), +vf_parse_text(3), +vf_parse_end(3), +vf_read_file(3), +vf_write_file(3), +vf_get_next_object(3), +vf_create_object(3), +vf_get_object_type(3), +vf_get_property_ex(3), +vf_get_next_property(3), +vf_get_prop_value(3), +vf_set_prop_value(3), +vf_get_prop_value_string(3), +vf_get_prop_name_string(3), +vf_set_prop_name_string(3), +vf_get_prop_name(3), +vf_get_prop_value_object(3), +vf_set_prop_value_object(3), +vf_set_prop_value_string(3), +vf_set_prop_value_base64(3), +vf_get_prop_value_base64(3), +vf_set_property_from_file(3), +vf_delete_object(3), +vf_delete_prop(3), +vf_find_prop_qual_index(3), +vf_is_modified(3), +vf_find_charset(3), +vf_date_string_to_time(3), +vf_period_string_to_time(3), +vf_period_time_to_string(3), +vf_set_prop_value_time(3), +vf_get_prop_value_time(3) |