| 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 */ |