summaryrefslogtreecommitdiffstats
path: root/doc/vf_get_property.3
blob: 828e414a96b97603cd6beeeec0974d26807b62d8 (plain)
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)