1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
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)
|