vf_get_property(3) vf_get_property()

SYNOPSIS

#include <../vformat/vf_iface.h>

extern bool_t vf_get_property
(
       VF_PROP_T **pp_prop,

       VF_OBJECT_T *p_object,

       vf_get_t ops,

       const char *p_group,

       const char *p_name,

       const char *p_qualifier,

       ...

);

PARAMETERS

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.

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);
- 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.