include/neon/ne_props.h

   1 /*
   2    WebDAV Properties manipulation
   3    Copyright (C) 1999-2004, Joe Orton <joe@manyfish.co.uk>
   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 BEGIN_NEON_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 char *href)
  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 (named by 'href').  The results are stored in the
 106  * result set 'results': use ne_propset_* to examine this object.  */
 107 typedef void (*ne_props_result)(void *userdata, const char *href,
 108                                  const ne_prop_result_set *results);
 109
 110 /* Fetch properties for a resource (if depth == NE_DEPTH_ZERO),
 111  * or a tree of resources (if depth == NE_DEPTH_ONE or _INFINITE).
 112  *
 113  * Names of the properties required must be given in 'props',
 114  * or if props is NULL, *all* properties are fetched.
 115  *
 116  * 'results' is called for each resource in the response, userdata is
 117  * passed as the first argument to the callback. It is important to
 118  * note that the callback is called as the response is read off the
 119  * socket, so don't do anything silly in it (e.g. sleep(100), or call
 120  * any functions which use this session).
 121  *
 122  * Note that if 'depth' is NE_DEPTH_INFINITY, some servers may refuse
 123  * the request.
 124  *
 125  * Returns NE_*.  */
 126 int ne_simple_propfind(ne_session *sess, const char *path, int depth,
 127                         const ne_propname *props,
 128                         ne_props_result results, void *userdata);
 129
 130 /* The properties of a resource can be manipulated using ne_proppatch.
 131  * A single proppatch request may include any number of individual
 132  * "set" and "remove" operations, and is defined to have
 133  * "all-or-nothing" semantics, so either all the operations succeed,
 134  * or none do. */
 135
 136 /* A proppatch operation may either set a property to have a new
 137  * value, in which case 'type' must be ne_propset, and 'value' must be
 138  * non-NULL; or it can remove a property; in which case 'type' must be
 139  * ne_propremove, and 'value' is ignored.  In both cases, 'name' must
 140  * be set to the name of the property to alter. */
 141 enum ne_proppatch_optype {
 142     ne_propset,
 143     ne_propremove
 144 };
 145 typedef struct {
 146     const ne_propname *name;
 147     enum ne_proppatch_optype type;
 148     const char *value;
 149 } ne_proppatch_operation;
 150
 151 /* Execute a set of property operations 'ops' on 'path'. 'ops' is an
 152  * array terminated by an operation with a NULL 'name' field. Returns
 153  * NE_*. */
 154 int ne_proppatch(ne_session *sess, const char *path,
 155                  const ne_proppatch_operation *ops);
 156
 157 /* Retrieve property names for the resources at 'path'.  'results'
 158  * callback is called for each resource.  Use 'ne_propset_iterate' on
 159  * the passed results object to retrieve the list of property names.
 160  * */
 161 int ne_propnames(ne_session *sess, const char *path, int depth,
 162                  ne_props_result results, void *userdata);
 163
 164 /* The complex, you-do-all-the-work, property fetch interface:
 165  */
 166
 167 struct ne_propfind_handler_s;
 168 typedef struct ne_propfind_handler_s ne_propfind_handler;
 169
 170 /* Retrieve the 'private' pointer for the current propset for the
 171  * given handler, as returned by the ne_props_create_complex callback
 172  * installed using 'ne_propfind_set_private'.  If this callback was
 173  * not registered, this function will return NULL.  */
 174 void *ne_propfind_current_private(ne_propfind_handler *handler);
 175
 176 /* Create a PROPFIND handler, for the given resource or set of
 177  * resources.
 178  *
 179  * Depth must be one of NE_DEPTH_*. */
 180 ne_propfind_handler *
 181 ne_propfind_create(ne_session *sess, const char *path, int depth);
 182
 183 /* Return the XML parser for the given handler (only need if you want
 184  * to handle complex properties). */
 185 ne_xml_parser *ne_propfind_get_parser(ne_propfind_handler *handler);
 186
 187 /* This interface reserves the state integer range 'x' where 0 < x
 188  * and x < NE_PROPS_STATE_TOP. */
 189 #define NE_PROPS_STATE_TOP (NE_207_STATE_TOP + 100)
 190
 191 /* Return the request object for the given handler.  You MUST NOT use
 192  * ne_set_request_body_* on this request object.  (this call is only
 193  * needed if for instance, you want to add extra headers to the
 194  * PROPFIND request).  The result of using the request pointer after
 195  * ne_propfind_destroy(handler) has been called is undefined. */
 196 ne_request *ne_propfind_get_request(ne_propfind_handler *handler);
 197
 198 /* A "complex property" has a value which is structured XML. To handle
 199  * complex properties, you must set up and register an XML handler
 200  * which will understand the elements which make up such properties.
 201  * The handler must be registered with the parser returned by
 202  * 'ne_propfind_get_parser'.
 203  *
 204  * To store the parsed value of the property, a 'private' structure is
 205  * allocated in each propset (i.e. one per resource). When parsing the
 206  * property value elements, for each new resource encountered in the
 207  * response, the 'creator' callback is called to retrieve a 'private'
 208  * structure for this resource.
 209  *
 210  * Whilst in XML element callbacks you will have registered to handle
 211  * complex properties, you can use the 'ne_propfind_current_private'
 212  * call to retrieve the pointer to this private structure.
 213  *
 214  * To retrieve this 'private' structure from the propset in the
 215  * results callback, simply call 'ne_propset_private'.
 216  * */
 217 typedef void *(*ne_props_create_complex)(void *userdata,
 218                                          const char *href);
 219
 220 void ne_propfind_set_private(ne_propfind_handler *handler,
 221                              ne_props_create_complex creator,
 222                              void *userdata);
 223
 224 /* Fetch all properties.
 225  *
 226  * Returns NE_*. */
 227 int ne_propfind_allprop(ne_propfind_handler *handler,
 228                         ne_props_result result, void *userdata);
 229
 230 /* Fetch all properties with names listed in array 'names', which is
 231  * terminated by a property with a NULL name field.  For each resource
 232  * encountered, the result callback will be invoked, passing in
 233  * 'userdata' as the first argument.
 234  *
 235  * Returns NE_*. */
 236 int ne_propfind_named(ne_propfind_handler *handler,
 237                       const ne_propname *names,
 238                       ne_props_result result, void *userdata);
 239
 240 /* Destroy a propfind handler after use. */
 241 void ne_propfind_destroy(ne_propfind_handler *handler);
 242
 243 END_NEON_DECLS
 244
 245 #endif /* NE_PROPS_H */