Back to index

avfs  1.0.1
dav_props.h
Go to the documentation of this file.
00001 /* 
00002    WebDAV Properties manipulation
00003    Copyright (C) 1999-2001, Joe Orton <joe@light.plus.com>
00004 
00005    This library is free software; you can redistribute it and/or
00006    modify it under the terms of the GNU Library General Public
00007    License as published by the Free Software Foundation; either
00008    version 2 of the License, or (at your option) any later version.
00009    
00010    This library is distributed in the hope that it will be useful,
00011    but WITHOUT ANY WARRANTY; without even the implied warranty of
00012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013    Library General Public License for more details.
00014 
00015    You should have received a copy of the GNU Library General Public
00016    License along with this library; if not, write to the Free
00017    Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
00018    MA 02111-1307, USA
00019 
00020 */
00021 
00022 #ifndef DAV_PROPS_H
00023 #define DAV_PROPS_H
00024 
00025 #include "http_request.h"
00026 #include "dav_207.h"
00027 
00028 BEGIN_NEON_DECLS
00029 
00030 /* There are two interfaces for fetching properties. The first is
00031  * 'dav_simple_propfind', which is relatively simple, and easy to use,
00032  * but only lets you fetch FLAT properties, i.e. properties which are
00033  * just a string of bytes.  The complex interface is 'dav_propfind_*',
00034  * which is complicated, and hard to use, but lets you parse
00035  * structured properties, i.e.  properties which have XML content.  */
00036 
00037 /* The 'dav_simple_propfind' interface. ***
00038  *
00039  * dav_get_props allows you to fetch a set of properties for a single
00040  * resource, or a tree of resources.  You set the operation going by
00041  * passing these arguments:
00042  *
00043  *  - the session which should be used.
00044  *  - the URI and the depth of the operation (0, 1, infinite)
00045  *  - the names of the properties which you want to fetch
00046  *  - a results callback, and the userdata for the callback.
00047  *
00048  * For each resource found, the results callback is called, passing
00049  * you two things along with the userdata you passed in originally:
00050  *
00051  *   - the URI of the resource (const char *href)
00052  *   - the properties results set (const dav_prop_result_set *results)
00053  *
00054  */
00055 
00056 typedef struct dav_prop_result_set_s dav_prop_result_set;
00057 
00058 /* Get the value of a given property. Will return NULL if there was an
00059  * error fetching this property on this resource.  Call
00060  * dav_propset_result to get the response-status if so.  */
00061 const char *dav_propset_value(const dav_prop_result_set *set,
00062                            const dav_propname *propname);
00063 
00064 /* Returns the status structure for fetching the given property on
00065  * this resource. This function will return NULL if the server did not
00066  * return the property (which is a server error). */
00067 const http_status *dav_propset_status(const dav_prop_result_set *set,
00068                                   const dav_propname *propname);
00069 
00070 /* Returns the private pointer for the given propset. */
00071 void *dav_propset_private(const dav_prop_result_set *set);
00072 
00073 /* dav_propset_iterate iterates over a properties result set,
00074  * calling the callback for each property in the set. userdata is
00075  * passed as the first argument to the callback. value may be NULL,
00076  * indicating an error occurred fetching this property: look at 
00077  * status for the error in that case.
00078  *
00079  * If the iterator returns non-zero, dav_propset_iterate will return
00080  * immediately with that value.
00081  */
00082 typedef int (*dav_propset_iterator)(void *userdata,
00083                                 const dav_propname *pname,
00084                                 const char *value,
00085                                 const http_status *status);
00086 
00087 /* Iterate over all the properties in 'set', calling 'iterator'
00088  * for each, passing 'userdata' as the first argument to callback.
00089  * 
00090  * Returns:
00091  *   whatever value iterator returns.
00092  */
00093 int dav_propset_iterate(const dav_prop_result_set *set,
00094                      dav_propset_iterator iterator, void *userdata);
00095 
00096 typedef void (*dav_props_result)(void *userdata, const char *href,
00097                              const dav_prop_result_set *results);
00098 
00099 /* Fetch properties for a resource (if depth == DAV_DEPTH_ZERO),
00100  * or a tree of resources (if depth == DAV_DEPTH_ONE or _INFINITE).
00101  *
00102  * Names of the properties required must be given in 'props',
00103  * or if props is NULL, *all* properties are fetched.
00104  *
00105  * 'results' is called for each resource in the response, userdata is
00106  * passed as the first argument to the callback. It is important to
00107  * note that the callback is called as the response is read off the
00108  * socket, so don't do anything silly in it (e.g. sleep(100), or call
00109  * any functions which use this session).
00110  *
00111  * Returns HTTP_*.  */
00112 int dav_simple_propfind(http_session *sess, const char *uri, int depth,
00113                      const dav_propname *props,
00114                      dav_props_result results, void *userdata);
00115 
00116 /* A PROPPATCH request may include any number of operations. Pass an
00117  * array of these operations to dav_proppatch, with the last item
00118  * having the name element being NULL.  If the type is propset, the
00119  * property of the given name is set to the new value.  If the type is
00120  * propremove, the property of the given name is deleted, and the
00121  * value is ignored.  */
00122 typedef struct {
00123     const dav_propname *name;
00124     enum {
00125        dav_propset,
00126        dav_propremove
00127     } type;
00128     const char *value;
00129 } dav_proppatch_operation;
00130 
00131 int dav_proppatch(http_session *sess, const char *uri,
00132                 const dav_proppatch_operation *items);
00133 
00134 /* The complex, you-do-all-the-work, property fetch interface:
00135  */
00136 
00137 struct dav_propfind_handler_s;
00138 typedef struct dav_propfind_handler_s dav_propfind_handler;
00139 
00140 /* Retrieve the 'private' pointer for the current propset for the
00141  * given handler, as returned by the dav_props_create_complex
00142  * callback.  */
00143 void *dav_propfind_current_private(dav_propfind_handler *handler);
00144 
00145 /* Create a PROPFIND handler, for the given URI.
00146  * Depth must be one of DAV_DEPTH_*. */
00147 dav_propfind_handler *
00148 dav_propfind_create(http_session *sess, const char *uri, int depth);
00149 
00150 /* Return the XML parser for the given handler. */
00151 hip_xml_parser *dav_propfind_get_parser(dav_propfind_handler *handler);
00152 
00153 /* A "complex property" has a value which is structured XML. To handle
00154  * complex properties, you must set up and register an XML handler
00155  * using the 'dav_propfind_get_parser' call, which will understand the
00156  * elements which make up such properties.
00157  *
00158  * To tell the PROPFIND handler to add the list of complex properties
00159  * to the list of properties to request from the server, use the
00160  * 'dav_propfind_set_complex' call below, and pass it a list of
00161  * properties. The list must be terminated by a property whose name is
00162  * NULL.
00163  *
00164  * To store the parsed value of the property, a 'private' structure is
00165  * allocated in each propset. When parsing the property value
00166  * elements, for each new resource encountered in the response, the
00167  * 'creator' callback is called to retrieve a 'private' structure for
00168  * this resource.
00169  *
00170  * Whilst in XML element callbacks you will have registered to handle
00171  * complex properties, you can use the 'dav_propfind_current_private'
00172  * call to retrieve the pointer to this private structure.
00173  *
00174  * To retrieve this 'private' structure from the propset in the
00175  * results callback, simply call 'dav_propset_private'.
00176  *
00177  * If more than one call to dav_propfind_set_complex is made for a given
00178  * handler, the result is undefined.
00179  * */
00180 
00181 typedef void *(*dav_props_create_complex)(void *userdata,
00182                                      const char *uri);
00183 
00184 void dav_propfind_set_complex(dav_propfind_handler *handler,
00185                            const dav_propname *proplist,
00186                            dav_props_create_complex creator,
00187                            void *userdata);
00188 
00189 /* A "simple property" is a flat string of bytes, and requires
00190  * no special handling by the XML parser.
00191  *
00192  * To tell the PROPFIND handler to retrieve a set of flat properties,
00193  * call 'dav_propfind_set_flat' with the properties. 
00194  *
00195  * If more than one call to dav_propfind_set_flat is made for a given
00196  * handler, the result is undefined.
00197  * */ 
00198 void dav_propfind_set_flat(dav_propfind_handler *handler,
00199                      const dav_propname *prop);
00200 
00201 /* Note that the call:
00202  * 
00203  *  ret = dav_simple_propfind(sess, uri, depth, props, callback, ud);
00204  * 
00205  * is equivalent to:
00206  *
00207  *  hdl = dav_propfind_create(sess, uri, depth);
00208  *  dav_propfind_set_flat(hdl, props);
00209  *  ret = dav_propfind_named(hdl, callback, ud);
00210  *  dav_propfind_destroy(hdl);
00211  *
00212  */
00213 
00214 /* Find all properties.  Calls to dav_propfind_set_flat and
00215  * dav_propfind_set_complex are ignored: all properties are treated
00216  * as flat.
00217  *
00218  * Returns HTTP_*. */
00219 int dav_propfind_allprop(dav_propfind_handler *handler, 
00220                       dav_props_result result, void *userdata);
00221 
00222 /* Find properties named in a call to dav_propfind_set_flat and/or
00223  * dav_propfind_set_complex.
00224  *
00225  * Returns HTTP_*. */
00226 int dav_propfind_named(dav_propfind_handler *handler, 
00227                      dav_props_result result, void *userdata);
00228 
00229 /* Destroy a propfind handler after use. */
00230 void dav_propfind_destroy(dav_propfind_handler *handler);
00231 
00232 /* TODO: this API doesn't cope with complex properties in an allprop
00233  * request. But:
00234  *
00235  * 1. allprops is probably a bad thing, and might go away in a future
00236  * spec revision anyway.
00237  *
00238  * 2. the use case for complex properties and allprop is pretty
00239  * thin. If you know what properties are defined, you fetch a named
00240  * sets. If you don't know what props are defined on a resource, you
00241  * have know way of knowing what their XML values "mean", anyway. 
00242  * */
00243 
00244 END_NEON_DECLS
00245 
00246 #endif /* DAV_PROPS_H */