246 lines
9.7 KiB
Plaintext
246 lines
9.7 KiB
Plaintext
/*
|
|
WebDAV Properties manipulation
|
|
Copyright (C) 1999-2004, Joe Orton <joe@manyfish.co.uk>
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Library General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Library General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Library General Public
|
|
License along with this library; if not, write to the Free
|
|
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
|
|
MA 02111-1307, USA
|
|
|
|
*/
|
|
|
|
#ifndef NE_PROPS_H
|
|
#define NE_PROPS_H
|
|
|
|
#include "ne_request.h"
|
|
#include "ne_207.h"
|
|
|
|
BEGIN_NEON_DECLS
|
|
|
|
/* There are two interfaces for fetching properties. The first is
|
|
* 'ne_simple_propfind', which is relatively simple, and easy to use,
|
|
* but only lets you fetch FLAT properties, i.e. properties which are
|
|
* just a string of bytes. The complex interface is 'ne_propfind_*',
|
|
* which is complicated, and hard to use, but lets you parse
|
|
* structured properties, i.e. properties which have XML content. */
|
|
|
|
/* The 'ne_simple_propfind' interface. ***
|
|
*
|
|
* ne_simple_propfind allows you to fetch a set of properties for a
|
|
* single resource, or a tree of resources. You set the operation
|
|
* going by passing these arguments:
|
|
*
|
|
* - the session which should be used.
|
|
* - the URI and the depth of the operation (0, 1, infinite)
|
|
* - the names of the properties which you want to fetch
|
|
* - a results callback, and the userdata for the callback.
|
|
*
|
|
* For each resource found, the results callback is called, passing
|
|
* you two things along with the userdata you passed in originally:
|
|
*
|
|
* - the URI of the resource (const char *href)
|
|
* - the properties results set (const ne_prop_result_set *results)
|
|
* */
|
|
|
|
/* The name of a WebDAV property. 'nspace' may be NULL. */
|
|
typedef struct {
|
|
const char *nspace, *name;
|
|
} ne_propname;
|
|
|
|
typedef struct ne_prop_result_set_s ne_prop_result_set;
|
|
|
|
/* Get the value of a given property. Will return NULL if there was an
|
|
* error fetching this property on this resource. Call
|
|
* ne_propset_result to get the response-status if so. */
|
|
const char *ne_propset_value(const ne_prop_result_set *set,
|
|
const ne_propname *propname);
|
|
|
|
/* Returns the status structure for fetching the given property on
|
|
* this resource. This function will return NULL if the server did not
|
|
* return the property (which is a server error). */
|
|
const ne_status *ne_propset_status(const ne_prop_result_set *set,
|
|
const ne_propname *propname);
|
|
|
|
/* Returns the private pointer for the given propset. */
|
|
void *ne_propset_private(const ne_prop_result_set *set);
|
|
|
|
/* Return language string of property (may be NULL). */
|
|
const char *ne_propset_lang(const ne_prop_result_set *set,
|
|
const ne_propname *pname);
|
|
|
|
/* ne_propset_iterate iterates over a properties result set,
|
|
* calling the callback for each property in the set. userdata is
|
|
* passed as the first argument to the callback. value may be NULL,
|
|
* indicating an error occurred fetching this property: look at
|
|
* status for the error in that case.
|
|
*
|
|
* If the iterator returns non-zero, ne_propset_iterate will return
|
|
* immediately with that value.
|
|
*/
|
|
typedef int (*ne_propset_iterator)(void *userdata,
|
|
const ne_propname *pname,
|
|
const char *value,
|
|
const ne_status *status);
|
|
|
|
/* Iterate over all the properties in 'set', calling 'iterator'
|
|
* for each, passing 'userdata' as the first argument to callback.
|
|
*
|
|
* Returns:
|
|
* whatever value iterator returns.
|
|
*/
|
|
int ne_propset_iterate(const ne_prop_result_set *set,
|
|
ne_propset_iterator iterator, void *userdata);
|
|
|
|
/* Callback for handling the results of fetching properties for a
|
|
* single resource (named by 'href'). The results are stored in the
|
|
* result set 'results': use ne_propset_* to examine this object. */
|
|
typedef void (*ne_props_result)(void *userdata, const char *href,
|
|
const ne_prop_result_set *results);
|
|
|
|
/* Fetch properties for a resource (if depth == NE_DEPTH_ZERO),
|
|
* or a tree of resources (if depth == NE_DEPTH_ONE or _INFINITE).
|
|
*
|
|
* Names of the properties required must be given in 'props',
|
|
* or if props is NULL, *all* properties are fetched.
|
|
*
|
|
* 'results' is called for each resource in the response, userdata is
|
|
* passed as the first argument to the callback. It is important to
|
|
* note that the callback is called as the response is read off the
|
|
* socket, so don't do anything silly in it (e.g. sleep(100), or call
|
|
* any functions which use this session).
|
|
*
|
|
* Note that if 'depth' is NE_DEPTH_INFINITY, some servers may refuse
|
|
* the request.
|
|
*
|
|
* Returns NE_*. */
|
|
int ne_simple_propfind(ne_session *sess, const char *path, int depth,
|
|
const ne_propname *props,
|
|
ne_props_result results, void *userdata);
|
|
|
|
/* The properties of a resource can be manipulated using ne_proppatch.
|
|
* A single proppatch request may include any number of individual
|
|
* "set" and "remove" operations, and is defined to have
|
|
* "all-or-nothing" semantics, so either all the operations succeed,
|
|
* or none do. */
|
|
|
|
/* A proppatch operation may either set a property to have a new
|
|
* value, in which case 'type' must be ne_propset, and 'value' must be
|
|
* non-NULL; or it can remove a property; in which case 'type' must be
|
|
* ne_propremove, and 'value' is ignored. In both cases, 'name' must
|
|
* be set to the name of the property to alter. */
|
|
enum ne_proppatch_optype {
|
|
ne_propset,
|
|
ne_propremove
|
|
};
|
|
typedef struct {
|
|
const ne_propname *name;
|
|
enum ne_proppatch_optype type;
|
|
const char *value;
|
|
} ne_proppatch_operation;
|
|
|
|
/* Execute a set of property operations 'ops' on 'path'. 'ops' is an
|
|
* array terminated by an operation with a NULL 'name' field. Returns
|
|
* NE_*. */
|
|
int ne_proppatch(ne_session *sess, const char *path,
|
|
const ne_proppatch_operation *ops);
|
|
|
|
/* Retrieve property names for the resources at 'path'. 'results'
|
|
* callback is called for each resource. Use 'ne_propset_iterate' on
|
|
* the passed results object to retrieve the list of property names.
|
|
* */
|
|
int ne_propnames(ne_session *sess, const char *path, int depth,
|
|
ne_props_result results, void *userdata);
|
|
|
|
/* The complex, you-do-all-the-work, property fetch interface:
|
|
*/
|
|
|
|
struct ne_propfind_handler_s;
|
|
typedef struct ne_propfind_handler_s ne_propfind_handler;
|
|
|
|
/* Retrieve the 'private' pointer for the current propset for the
|
|
* given handler, as returned by the ne_props_create_complex callback
|
|
* installed using 'ne_propfind_set_private'. If this callback was
|
|
* not registered, this function will return NULL. */
|
|
void *ne_propfind_current_private(ne_propfind_handler *handler);
|
|
|
|
/* Create a PROPFIND handler, for the given resource or set of
|
|
* resources.
|
|
*
|
|
* Depth must be one of NE_DEPTH_*. */
|
|
ne_propfind_handler *
|
|
ne_propfind_create(ne_session *sess, const char *path, int depth);
|
|
|
|
/* Return the XML parser for the given handler (only need if you want
|
|
* to handle complex properties). */
|
|
ne_xml_parser *ne_propfind_get_parser(ne_propfind_handler *handler);
|
|
|
|
/* This interface reserves the state integer range 'x' where 0 < x
|
|
* and x < NE_PROPS_STATE_TOP. */
|
|
#define NE_PROPS_STATE_TOP (NE_207_STATE_TOP + 100)
|
|
|
|
/* Return the request object for the given handler. You MUST NOT use
|
|
* ne_set_request_body_* on this request object. (this call is only
|
|
* needed if for instance, you want to add extra headers to the
|
|
* PROPFIND request). The result of using the request pointer after
|
|
* ne_propfind_destroy(handler) has been called is undefined. */
|
|
ne_request *ne_propfind_get_request(ne_propfind_handler *handler);
|
|
|
|
/* A "complex property" has a value which is structured XML. To handle
|
|
* complex properties, you must set up and register an XML handler
|
|
* which will understand the elements which make up such properties.
|
|
* The handler must be registered with the parser returned by
|
|
* 'ne_propfind_get_parser'.
|
|
*
|
|
* To store the parsed value of the property, a 'private' structure is
|
|
* allocated in each propset (i.e. one per resource). When parsing the
|
|
* property value elements, for each new resource encountered in the
|
|
* response, the 'creator' callback is called to retrieve a 'private'
|
|
* structure for this resource.
|
|
*
|
|
* Whilst in XML element callbacks you will have registered to handle
|
|
* complex properties, you can use the 'ne_propfind_current_private'
|
|
* call to retrieve the pointer to this private structure.
|
|
*
|
|
* To retrieve this 'private' structure from the propset in the
|
|
* results callback, simply call 'ne_propset_private'.
|
|
* */
|
|
typedef void *(*ne_props_create_complex)(void *userdata,
|
|
const char *href);
|
|
|
|
void ne_propfind_set_private(ne_propfind_handler *handler,
|
|
ne_props_create_complex creator,
|
|
void *userdata);
|
|
|
|
/* Fetch all properties.
|
|
*
|
|
* Returns NE_*. */
|
|
int ne_propfind_allprop(ne_propfind_handler *handler,
|
|
ne_props_result result, void *userdata);
|
|
|
|
/* Fetch all properties with names listed in array 'names', which is
|
|
* terminated by a property with a NULL name field. For each resource
|
|
* encountered, the result callback will be invoked, passing in
|
|
* 'userdata' as the first argument.
|
|
*
|
|
* Returns NE_*. */
|
|
int ne_propfind_named(ne_propfind_handler *handler,
|
|
const ne_propname *names,
|
|
ne_props_result result, void *userdata);
|
|
|
|
/* Destroy a propfind handler after use. */
|
|
void ne_propfind_destroy(ne_propfind_handler *handler);
|
|
|
|
END_NEON_DECLS
|
|
|
|
#endif /* NE_PROPS_H */
|