mod_dav.h

Apache V2.0.15 Alpha For Linuxhttpd-2_0_15-alpha.tar.Z

                         * and is always 1 for WORKSPACE */

    int versioned;	/* 0 => unversioned; can be 1 for
                         * REGULAR and WORKSPACE resources,
                         * and is always 1 for VERSION and WORKING */

    int baselined;      /* 0 => not baselined; can be 1 for
                         * REGULAR and VERSION resources;
                         * versioned == 1 when baselined == 1 */

    int working;	/* 0 => not checked out; can be 1 for
                         * REGULAR and WORKSPACE resources,
                         * and is always 1 for WORKING */

    const char *uri;	/* the URI for this resource */

    dav_resource_private *info;         /* the provider's private info */

    const dav_hooks_repository *hooks;	/* hooks used for this resource */

    /* When allocating items related specifically to this resource, the
       following pool should be used. Its lifetime will be at least as
       long as the dav_resource structure. */
    apr_pool_t *pool;

} dav_resource;

/*
** Lock token type. Lock providers define the details of a lock token.
** However, all providers are expected to at least be able to parse
** the "opaquelocktoken" scheme, which is represented by a uuid_t.
*/
typedef struct dav_locktoken dav_locktoken;


/* --------------------------------------------------------------------
**
** BUFFER HANDLING
**
** These buffers are used as a lightweight buffer reuse mechanism. Apache
** provides sub-pool creation and destruction to much the same effect, but
** the sub-pools are a bit more general and heavyweight than these buffers.
*/

/* buffer for reuse; can grow to accomodate needed size */
typedef struct
{
    apr_size_t alloc_len;	/* how much has been allocated */
    apr_size_t cur_len;		/* how much is currently being used */
    char *buf;			/* buffer contents */
} dav_buffer;
#define DAV_BUFFER_MINSIZE	256	/* minimum size for buffer */
#define DAV_BUFFER_PAD		64	/* amount of pad when growing */

/* set the cur_len to the given size and ensure space is available */
DAV_DECLARE(void) dav_set_bufsize(apr_pool_t *p, dav_buffer *pbuf, 
                                  apr_size_t size);

/* initialize a buffer and copy the specified (null-term'd) string into it */
DAV_DECLARE(void) dav_buffer_init(apr_pool_t *p, dav_buffer *pbuf, 
                                  const char *str);

/* check that the buffer can accomodate <extra_needed> more bytes */
DAV_DECLARE(void) dav_check_bufsize(apr_pool_t *p, dav_buffer *pbuf, 
                                    apr_size_t extra_needed);

/* append a string to the end of the buffer, adjust length */
DAV_DECLARE(void) dav_buffer_append(apr_pool_t *p, dav_buffer *pbuf, 
                                    const char *str);

/* place a string on the end of the buffer, do NOT adjust length */
DAV_DECLARE(void) dav_buffer_place(apr_pool_t *p, dav_buffer *pbuf, 
                                   const char *str);

/* place some memory on the end of a buffer; do NOT adjust length */
DAV_DECLARE(void) dav_buffer_place_mem(apr_pool_t *p, dav_buffer *pbuf, 
                                       const void *mem, apr_size_t amt, 
                                       apr_size_t pad);


/* --------------------------------------------------------------------
**
** HANDY UTILITIES
*/

/* contains results from one of the getprop functions */
typedef struct
{
    ap_text * propstats;	/* <propstat> element text */
    ap_text * xmlns;		/* namespace decls for <response> elem */
} dav_get_props_result;

/* holds the contents of a <response> element */
typedef struct dav_response
{
    const char *href;		/* always */
    const char *desc;		/* optional description at <response> level */

    /* use status if propresult.propstats is NULL. */
    dav_get_props_result propresult;

    int status;

    struct dav_response *next;
} dav_response;

typedef struct
{
    request_rec *rnew;		/* new subrequest */
    dav_error err;		/* potential error response */
} dav_lookup_result;


dav_lookup_result dav_lookup_uri(const char *uri, request_rec *r);

/* defines type of property info a provider is to return */
typedef enum {
    DAV_PROP_INSERT_NOTDEF,	/* property is defined by this provider,
				   but nothing was inserted because the
				   (live) property is not defined for this
				   resource (it may be present as a dead
				   property). */
    DAV_PROP_INSERT_NOTSUPP,    /* property is recognized by this provider,
                                   but it is not supported, and cannot be
                                   treated as a dead property */
    DAV_PROP_INSERT_NAME,	/* a property name (empty elem) was
				   inserted into the text block */
    DAV_PROP_INSERT_VALUE,	/* a property name/value pair was inserted
				   into the text block */
    DAV_PROP_INSERT_SUPPORTED   /* a supported live property was added to
                                   the text block as a
                                   <DAV:supported-live-property> element */
} dav_prop_insert;

/* ### this stuff is private to dav/fs/repos.c; move it... */
/* format a time string (buf must be at least DAV_TIMEBUF_SIZE chars) */
#define DAV_STYLE_ISO8601	1
#define DAV_STYLE_RFC822	2
#define DAV_TIMEBUF_SIZE	30

int dav_get_depth(request_rec *r, int def_depth);

int dav_validate_root(const ap_xml_doc *doc, const char *tagname);
ap_xml_elem *dav_find_child(const ap_xml_elem *elem, const char *tagname);

/* gather up all the CDATA into a single string */
const char *dav_xml_get_cdata(const ap_xml_elem *elem, apr_pool_t *pool,
                              int strip_white);


/* --------------------------------------------------------------------
**
** DAV PLUGINS
*/

/* ### docco ... */

/*
** dav_provider
**
** This structure wraps up all of the hooks that a mod_dav provider can
** supply. The provider MUST supply <repos> and <propdb>. The rest are
** optional and should contain NULL if that feature is not supplied.
**
** Note that a provider cannot pick and choose portions. There are too many
** dependencies between a dav_resource (defined by <repos>) and the other
** functionality.
**
** Live properties are not part of the dav_provider structure because they
** are handled through the APR_HOOK interface (to allow for multiple liveprop
** providers). The core always provides some properties, and then a given
** provider will add more properties.
*/
typedef struct {
    const dav_hooks_repository *repos;
    const dav_hooks_propdb *propdb;
    const dav_hooks_locks *locks;
    const dav_hooks_vsn *vsn;
    const dav_hooks_binding *binding;

} dav_provider;

/*
** gather_propsets: gather all live property propset-URIs
**
** The hook implementor should push one or more URIs into the specified
** array. These URIs are returned in the DAV: header to let clients know
** what sets of live properties are supported by the installation. mod_dav
** will place open/close angle brackets around each value (much like
** a Coded-URL); quotes and brackets should not be in the value.
**
** Example:    http://apache.org/dav/props/
**
** (of course, use your own domain to ensure a unique value)
*/
APR_DECLARE_EXTERNAL_HOOK(dav, DAV, void, gather_propsets, 
                         (apr_array_header_t *uris))

/*
** find_liveprop: find a live property, returning a non-zero, unique,
**                opaque identifier.
**
** If the hook implementor determines the specified URI/name refers to
** one of its properties, then it should fill in HOOKS and return a
** non-zero value. The returned value is the "property ID" and will
** be passed to the various liveprop hook functions.
**
** Return 0 if the property is not defined by the hook implementor.
*/
APR_DECLARE_EXTERNAL_HOOK(dav, DAV, int, find_liveprop,
                         (const dav_resource *resource,
                          const char *ns_uri, const char *name,
                          const dav_hooks_liveprop **hooks))

/*
** insert_all_liveprops: insert all (known) live property names/values.
**
** The hook implementor should append XML text to PHDR, containing liveprop
** names. If INSVALUE is true, then the property values should also be
** inserted into the output XML stream.
**
** The liveprop provider should insert *all* known and *defined* live
** properties on the specified resource. If a particular liveprop is
** not defined for this resource, then it should not be inserted.
*/
APR_DECLARE_EXTERNAL_HOOK(dav, DAV, void, insert_all_liveprops, 
                         (request_rec *r, const dav_resource *resource,
                          dav_prop_insert what, ap_text_header *phdr))

const dav_hooks_locks *dav_get_lock_hooks(request_rec *r);
const dav_hooks_propdb *dav_get_propdb_hooks(request_rec *r);
const dav_hooks_vsn *dav_get_vsn_hooks(request_rec *r);
const dav_hooks_binding *dav_get_binding_hooks(request_rec *r);

DAV_DECLARE(void) dav_register_provider(apr_pool_t *p, const char *name,
                                        const dav_provider *hooks);
const dav_provider * dav_lookup_provider(const char *name);


/* ### deprecated */
#define DAV_GET_HOOKS_PROPDB(r)         dav_get_propdb_hooks(r)
#define DAV_GET_HOOKS_LOCKS(r)          dav_get_lock_hooks(r)
#define DAV_GET_HOOKS_VSN(r)            dav_get_vsn_hooks(r)
#define DAV_GET_HOOKS_BINDING(r)        dav_get_binding_hooks(r)


/* --------------------------------------------------------------------
**
** IF HEADER PROCESSING
**
** Here is the definition of the If: header from RFC 2518, S9.4:
**
**    If = "If" ":" (1*No-tag-list | 1*Tagged-list)
**    No-tag-list = List
**    Tagged-list = Resource 1*List
**    Resource = Coded-URL
**    List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")"
**    State-token = Coded-URL
**    Coded-URL = "<" absoluteURI ">"        ; absoluteURI from RFC 2616
**
** List corresponds to dav_if_state_list. No-tag-list corresponds to
** dav_if_header with uri==NULL. Tagged-list corresponds to a sequence of
** dav_if_header structures with (duplicate) uri==Resource -- one
** dav_if_header per state_list. A second Tagged-list will start a new
** sequence of dav_if_header structures with the new URI.
**
** A summary of the semantics, mapped into our structures:
**    - Chained dav_if_headers: OR
**    - Chained dav_if_state_lists: AND
**    - NULL uri matches all resources
*/

typedef enum
{
    dav_if_etag,
    dav_if_opaquelock
} dav_if_state_type;

typedef struct dav_if_state_list
{
    dav_if_state_type type;

    int condition;
#define DAV_IF_COND_NORMAL	0
#define DAV_IF_COND_NOT		1	/* "Not" was applied */

    const char *etag;	/* etag */
    dav_locktoken *locktoken;   /* locktoken */

    struct dav_if_state_list *next;
} dav_if_state_list;

typedef struct dav_if_header
{
    const char *uri;
    apr_size_t uri_len;
    struct dav_if_state_list *state;
    struct dav_if_header *next;

    int dummy_header;	/* used internally by the lock/etag validation */
} dav_if_header;

typedef struct dav_locktoken_list 
{
    dav_locktoken *locktoken;
    struct dav_locktoken_list *next;
} dav_locktoken_list;

dav_error * dav_get_locktoken_list(request_rec *r, dav_locktoken_list **ltl);


/* --------------------------------------------------------------------
**
** LIVE PROPERTY HANDLING
*/

/* opaque type for PROPPATCH rollback information */
typedef struct dav_liveprop_rollback dav_liveprop_rollback;

struct dav_hooks_liveprop
{
    /*
    ** Insert property information into a text block. The property to
    ** insert is identified by the propid value. The information to insert
    ** is identified by the "what" argument, as follows:
    **   DAV_PROP_INSERT_NAME
    **      property name, as an empty XML element
    **   DAV_PROP_INSERT_VALUE
    **      property name/value, as an XML element
    **   DAV_PROP_INSERT_SUPPORTED
    **      if the property is defined on the resource, then
    **      a DAV:supported-live-property element, as defined
    **      by the DeltaV extensions to RFC2518.
    **                      
    ** Providers should return DAV_PROP_INSERT_NOTDEF if the property is
    ** known and not defined for this resource, so should be handled as a
    ** dead property. If a provider recognizes, but does not support, a
    ** property, and does not want it handled as a dead property, it should
    ** return DAV_PROP_INSERT_NOTSUPP.
    **
    ** Returns one of DAV_PROP_INSERT_* based on what happened.
    **
    ** ### we may need more context... ie. the lock database
    */
    dav_prop_insert (*insert_prop)(const dav_resource *resource,
				   int propid, dav_prop_insert what,
				   ap_text_header *phdr);

    /*
    ** Determine whether a given property is writable.
    **
    ** ### we may want a different semantic. i.e. maybe it should be
    ** ### "can we write <value> into this property?"
    **
    ** Returns 1 if the live property can be written, 0 if read-only.
    */
    int (*is_writable)(const dav_resource *resource, int propid);

    /*
    ** This member defines the set of namespace URIs that the provider
    ** uses for its properties. When insert_all is called, it will be
    ** passed a list of integers that map from indices into this list
    ** to namespace IDs for output generation.
    **
    ** The last entry in this list should be a NULL value (sentinel).
    */
    const char * const * namespace_uris;

    /*
    ** ### this is not the final design. we want an open-ended way for
    ** ### liveprop providers to attach *new* properties. To this end,
    ** ### we'll have a "give me a list of the props you define", a way
    ** ### to check for a prop's existence, a way to validate a set/remove
    ** ### of a prop, and a way to execute/commit/rollback that change.
    */

    /*
    ** Validate that the live property can be assigned a value, and that