Debian Codegraph @

deps/libneon/src/ne_props.h

raw
1 /*
2 WebDAV Properties manipulation
3 Copyright (C) 1999-2006, Joe Orton <[email protected]>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public
16 License along with this library; if not, write to the Free
17 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
18 MA 02111-1307, USA
19
20 */
21
22 #ifndef NE_PROPS_H
23 #define NE_PROPS_H
24
25 #include "ne_request.h"
26 #include "ne_207.h"
27
28 NE_BEGIN_DECLS
29
30 /* There are two interfaces for fetching properties. The first is
31 * 'ne_simple_propfind', which is relatively simple, and easy to use,
32 * but only lets you fetch FLAT properties, i.e. properties which are
33 * just a string of bytes. The complex interface is 'ne_propfind_*',
34 * which is complicated, and hard to use, but lets you parse
35 * structured properties, i.e. properties which have XML content. */
36
37 /* The 'ne_simple_propfind' interface. ***
38 *
39 * ne_simple_propfind allows you to fetch a set of properties for a
40 * single resource, or a tree of resources. You set the operation
41 * going by passing these arguments:
42 *
43 * - the session which should be used.
44 * - the URI and the depth of the operation (0, 1, infinite)
45 * - the names of the properties which you want to fetch
46 * - a results callback, and the userdata for the callback.
47 *
48 * For each resource found, the results callback is called, passing
49 * you two things along with the userdata you passed in originally:
50 *
51 * - the URI of the resource (const ne_uri *uri)
52 * - the properties results set (const ne_prop_result_set *results)
53 * */
54
55 /* The name of a WebDAV property. 'nspace' may be NULL. */
56 typedef struct {
57 const char *nspace, *name;
58 } ne_propname;
59
60 typedef struct ne_prop_result_set_s ne_prop_result_set;
61
62 /* Get the value of a given property. Will return NULL if there was an
63 * error fetching this property on this resource. Call
64 * ne_propset_result to get the response-status if so. */
65 const char *ne_propset_value(const ne_prop_result_set *set,
66 const ne_propname *propname);
67
68 /* Returns the status structure for fetching the given property on
69 * this resource. This function will return NULL if the server did not
70 * return the property (which is a server error). */
71 const ne_status *ne_propset_status(const ne_prop_result_set *set,
72 const ne_propname *propname);
73
74 /* Returns the private pointer for the given propset. */
75 void *ne_propset_private(const ne_prop_result_set *set);
76
77 /* Return language string of property (may be NULL). */
78 const char *ne_propset_lang(const ne_prop_result_set *set,
79 const ne_propname *pname);
80
81 /* ne_propset_iterate iterates over a properties result set,
82 * calling the callback for each property in the set. userdata is
83 * passed as the first argument to the callback. value may be NULL,
84 * indicating an error occurred fetching this property: look at
85 * status for the error in that case.
86 *
87 * If the iterator returns non-zero, ne_propset_iterate will return
88 * immediately with that value.
89 */
90 typedef int (*ne_propset_iterator)(void *userdata,
91 const ne_propname *pname,
92 const char *value,
93 const ne_status *status);
94
95 /* Iterate over all the properties in 'set', calling 'iterator'
96 * for each, passing 'userdata' as the first argument to callback.
97 *
98 * Returns:
99 * whatever value iterator returns.
100 */
101 int ne_propset_iterate(const ne_prop_result_set *set,
102 ne_propset_iterator iterator, void *userdata);
103
104 /* Callback for handling the results of fetching properties for a
105 * single resource (identified by URI 'uri'). The results are stored
106 * in the result set 'results': use ne_propset_* to examine this
107 * object. */
108 typedef void (*ne_props_result)(void *userdata, const ne_uri *uri,
109 const ne_prop_result_set *results);
110
111 /* Fetch properties for a resource (if depth == NE_DEPTH_ZERO),
112 * or a tree of resources (if depth == NE_DEPTH_ONE or _INFINITE).
113 *
114 * Names of the properties required must be given in 'props',
115 * or if props is NULL, *all* properties are fetched.
116 *
117 * 'results' is called for each resource in the response, userdata is
118 * passed as the first argument to the callback. It is important to
119 * note that the callback is called as the response is read off the
120 * socket, so don't do anything silly in it (e.g. sleep(100), or call
121 * any functions which use this session).
122 *
123 * Note that if 'depth' is NE_DEPTH_INFINITY, some servers may refuse
124 * the request.
125 *
126 * Returns NE_*. */
127 int ne_simple_propfind(ne_session *sess, const char *path, int depth,
128 const ne_propname *props,
129 ne_props_result results, void *userdata);
130
131 /* The properties of a resource can be manipulated using ne_proppatch.
132 * A single proppatch request may include any number of individual
133 * "set" and "remove" operations, and is defined to have
134 * "all-or-nothing" semantics, so either all the operations succeed,
135 * or none do. */
136
137 /* A proppatch operation may either set a property to have a new
138 * value, in which case 'type' must be ne_propset, and 'value' must be
139 * non-NULL; or it can remove a property; in which case 'type' must be
140 * ne_propremove, and 'value' is ignored. In both cases, 'name' must
141 * be set to the name of the property to alter. */
142 enum ne_proppatch_optype {
143 ne_propset,
144 ne_propremove
145 };
146 typedef struct {
147 const ne_propname *name;
148 enum ne_proppatch_optype type;
149 const char *value;
150 } ne_proppatch_operation;
151
152 /* Execute a set of property operations 'ops' on 'path'. 'ops' is an
153 * array terminated by an operation with a NULL 'name' field. Returns
154 * NE_*. */
155 int ne_proppatch(ne_session *sess, const char *path,
156 const ne_proppatch_operation *ops);
157
158 /* Retrieve property names for the resources at 'path'. 'results'
159 * callback is called for each resource. Use 'ne_propset_iterate' on
160 * the passed results object to retrieve the list of property names.
161 * */
162 int ne_propnames(ne_session *sess, const char *path, int depth,
163 ne_props_result results, void *userdata);
164
165 /* The complex, you-do-all-the-work, property fetch interface:
166 */
167
168 struct ne_propfind_handler_s;
169 typedef struct ne_propfind_handler_s ne_propfind_handler;
170
171 /* Retrieve the 'private' pointer for the current propset for the
172 * given handler, as returned by the ne_props_create_complex callback
173 * installed using 'ne_propfind_set_private'. If this callback was
174 * not registered, this function will return NULL. */
175 void *ne_propfind_current_private(ne_propfind_handler *handler);
176
177 /* Create a PROPFIND handler, for the given resource or set of
178 * resources.
179 *
180 * Depth must be one of NE_DEPTH_*. */
181 ne_propfind_handler *
182 ne_propfind_create(ne_session *sess, const char *path, int depth);
183
184 /* Return the XML parser for the given handler (only need if you want
185 * to handle complex properties). */
186 ne_xml_parser *ne_propfind_get_parser(ne_propfind_handler *handler);
187
188 /* This interface reserves the state integer range 'x' where 0 < x
189 * and x < NE_PROPS_STATE_TOP. */
190 #define NE_PROPS_STATE_TOP (NE_207_STATE_TOP + 100)
191
192 /* Return the request object for the given handler. You MUST NOT use
193 * ne_set_request_body_* on this request object. (this call is only
194 * needed if for instance, you want to add extra headers to the
195 * PROPFIND request). The result of using the request pointer after
196 * ne_propfind_destroy(handler) has been called is undefined. */
197 ne_request *ne_propfind_get_request(ne_propfind_handler *handler);
198
199 /* A "complex property" has a value which is structured XML. To handle
200 * complex properties, you must set up and register an XML handler
201 * which will understand the elements which make up such properties.
202 * The handler must be registered with the parser returned by
203 * 'ne_propfind_get_parser'.
204 *
205 * To store the parsed value of the property, a 'private' structure is
206 * allocated in each propset (i.e. one per resource). When parsing the
207 * property value elements, for each new resource encountered in the
208 * response, the 'creator' callback is called to retrieve a 'private'
209 * structure for this resource. When the private structure is no longer
210 * needed, the 'destructor' callback is called to deallocate any
211 * memory, if necessary.
212 *
213 * Whilst in XML element callbacks you will have registered to handle
214 * complex properties, you can use the 'ne_propfind_current_private'
215 * call to retrieve the pointer to this private structure.
216 *
217 * To retrieve this 'private' structure from the propset in the
218 * results callback, simply call 'ne_propset_private'.
219 * */
220 typedef void *(*ne_props_create_complex)(void *userdata, const ne_uri *uri);
221 typedef void (*ne_props_destroy_complex)(void *userdata, void *complex);
222
223 void ne_propfind_set_private(ne_propfind_handler *handler,
224 ne_props_create_complex creator,
225 ne_props_destroy_complex destructor,
226 void *userdata);
227
228 /* Fetch all properties.
229 *
230 * Returns NE_*. */
231 int ne_propfind_allprop(ne_propfind_handler *handler,
232 ne_props_result result, void *userdata);
233
234 /* Fetch all properties with names listed in array 'names', which is
235 * terminated by a property with a NULL name field. For each resource
236 * encountered, the result callback will be invoked, passing in
237 * 'userdata' as the first argument.
238 *
239 * Returns NE_*. */
240 int ne_propfind_named(ne_propfind_handler *handler,
241 const ne_propname *names,
242 ne_props_result result, void *userdata);
243
244 /* Destroy a propfind handler after use. */
245 void ne_propfind_destroy(ne_propfind_handler *handler);
246
247 NE_END_DECLS
248
249 #endif /* NE_PROPS_H */