mod_dav.h

Apache 2.0.63 is the current stable version of the 2.0 series, and is recommended over any previous

    ** the value into *phdr). Set *found based on whether the name/value
    ** was found in the propdb.
    **
    ** Note: it is NOT an error for the key/value pair to not exist.
    **
    ** The dav_xmlns_info passed to define_namespaces() is also passed to
    ** each output_value() call so that namespaces can be added on-demand.
    ** It can also be used to look up prefixes or URIs during the output
    ** process.
    */
    dav_error * (*output_value)(dav_db *db, const dav_prop_name *name,
                                dav_xmlns_info *xi,
                                apr_text_header *phdr, int *found);

    /*
    ** Build a mapping from "global" namespaces (stored in apr_xml_*)
    ** into provider-local namespace identifiers.
    **
    ** This mapping should be done once per set of namespaces, and the
    ** resulting mapping should be passed into the store() hook function.
    **
    ** Note: usually, there is just a single document/namespaces for all
    ** elements passed. However, the generality of creating multiple
    ** mappings and passing them to store() is provided here.
    **
    ** Note: this is only in preparation for a series of store() calls.
    ** As a result, the propdb must be open for read/write access when
    ** this function is called.
    */
    dav_error * (*map_namespaces)(dav_db *db,
                                  const apr_array_header_t *namespaces,
                                  dav_namespace_map **mapping);
    
    /*
    ** Store a property value for a given name. The value->combined field
    ** MUST be set for this call.
    **
    ** ### WARNING: current providers will quote the text within ELEM.
    ** ### this implies you can call this function only once with a given
    ** ### element structure (a second time will quote it again).
    */
    dav_error * (*store)(dav_db *db, const dav_prop_name *name,
                         const apr_xml_elem *elem,
                         dav_namespace_map *mapping);

    /* remove a given property */
    dav_error * (*remove)(dav_db *db, const dav_prop_name *name);

    /* returns 1 if the record specified by "key" exists; 0 otherwise */
    int (*exists)(dav_db *db, const dav_prop_name *name);

    /*
    ** Iterate over the property names in the database.
    **
    ** iter->name.ns == iter->name.name == NULL when there are no more names.
    **
    ** Note: only one iteration may occur over the propdb at a time.
    */
    dav_error * (*first_name)(dav_db *db, dav_prop_name *pname);
    dav_error * (*next_name)(dav_db *db, dav_prop_name *pname);

    /*
    ** Rollback support: get rollback context, and apply it.
    **
    ** struct dav_deadprop_rollback is a provider-private structure; it
    ** should remember the name, and the name's old value (or the fact that
    ** the value was not present, and should be deleted if a rollback occurs).
    */
    dav_error * (*get_rollback)(dav_db *db, const dav_prop_name *name,
                                dav_deadprop_rollback **prollback);
    dav_error * (*apply_rollback)(dav_db *db,
                                  dav_deadprop_rollback *rollback);

    /*
    ** If a provider needs a context to associate with this hooks structure,
    ** then this field may be used. In most cases, it will just be NULL.
    */
    void *ctx;
};


/* --------------------------------------------------------------------
**
** LOCK FUNCTIONS
*/

/* Used to represent a Timeout header of "Infinity" */
#define DAV_TIMEOUT_INFINITE 0

DAV_DECLARE(time_t) dav_get_timeout(request_rec *r);

/*
** Opaque, provider-specific information for a lock database.
*/
typedef struct dav_lockdb_private dav_lockdb_private;

/*
** Opaque, provider-specific information for a lock record.
*/
typedef struct dav_lock_private dav_lock_private;

/*
** Lock database type. Lock providers are urged to implement a "lazy" open, so
** doing an "open" is cheap until something is actually needed from the DB.
*/
typedef struct
{
    const dav_hooks_locks *hooks;   /* the hooks used for this lockdb */
    int ro;                         /* was it opened readonly? */

    dav_lockdb_private *info;

} dav_lockdb;

typedef enum {
    DAV_LOCKSCOPE_UNKNOWN,
    DAV_LOCKSCOPE_EXCLUSIVE,
    DAV_LOCKSCOPE_SHARED
} dav_lock_scope;

typedef enum {
    DAV_LOCKTYPE_UNKNOWN,
    DAV_LOCKTYPE_WRITE
} dav_lock_type;

typedef enum {
    DAV_LOCKREC_DIRECT,             /* lock asserted on this resource */
    DAV_LOCKREC_INDIRECT,           /* lock inherited from a parent */
    DAV_LOCKREC_INDIRECT_PARTIAL    /* most info is not filled in */
} dav_lock_rectype;

/*
** dav_lock: hold information about a lock on a resource.
**
** This structure is used for both direct and indirect locks. A direct lock
** is a lock applied to a specific resource by the client. An indirect lock
** is one that is inherited from a parent resource by virtue of a non-zero
** Depth: header when the lock was applied.
**
** mod_dav records both types of locks in the lock database, managing their
** addition/removal as resources are moved about the namespace.
**
** Note that the lockdb is free to marshal this structure in any form that
** it likes.
**
** For a "partial" lock, the <rectype> and <locktoken> fields must be filled
** in. All other (user) fields should be zeroed. The lock provider will
** usually fill in the <info> field, and the <next> field may be used to
** construct a list of partial locks.
**
** The lock provider MUST use the info field to store a value such that a
** dav_lock structure can locate itself in the underlying lock database.
** This requirement is needed for refreshing: when an indirect dav_lock is
** refreshed, its reference to the direct lock does not specify the direct's
** resource, so the only way to locate the (refreshed, direct) lock in the
** database is to use the info field.
**
** Note that <is_locknull> only refers to the resource where this lock was
** found.
** ### hrm. that says the abstraction is wrong. is_locknull may disappear.
*/
typedef struct dav_lock
{
    dav_lock_rectype rectype;   /* type of lock record */
    int is_locknull;            /* lock establishes a locknull resource */

    /* ### put the resource in here? */

    dav_lock_scope scope;       /* scope of the lock */
    dav_lock_type type;         /* type of lock */
    int depth;                  /* depth of the lock */
    time_t timeout;             /* when the lock will timeout */

    const dav_locktoken *locktoken;  /* the token that was issued */

    const char *owner;          /* (XML) owner of the lock */
    const char *auth_user;      /* auth'd username owning lock */

    dav_lock_private *info;     /* private to the lockdb */

    struct dav_lock *next;      /* for managing a list of locks */
} dav_lock;

/* Property-related public lock functions */
DAV_DECLARE(const char *)dav_lock_get_activelock(request_rec *r,
                                                 dav_lock *locks,
                                                 dav_buffer *pbuf);

/* LockDB-related public lock functions */
DAV_DECLARE(dav_error *) dav_lock_parse_lockinfo(request_rec *r,
                                                 const dav_resource *resrouce,
                                                 dav_lockdb *lockdb,
                                                 const apr_xml_doc *doc,
                                                 dav_lock **lock_request);
DAV_DECLARE(int) dav_unlock(request_rec *r,
                            const dav_resource *resource,
                            const dav_locktoken *locktoken);
DAV_DECLARE(dav_error *) dav_add_lock(request_rec *r,
                                      const dav_resource *resource,
                                      dav_lockdb *lockdb, dav_lock *request,
                                      dav_response **response);
DAV_DECLARE(dav_error *) dav_notify_created(request_rec *r,
                                            dav_lockdb *lockdb,
                                            const dav_resource *resource,
                                            int resource_state,
                                            int depth);

DAV_DECLARE(dav_error*) dav_lock_query(dav_lockdb *lockdb, 
                                       const dav_resource *resource,
                                       dav_lock **locks);

DAV_DECLARE(dav_error *) dav_validate_request(request_rec *r,
                                              dav_resource *resource,
                                              int depth,
                                              dav_locktoken *locktoken,
                                              dav_response **response,
                                              int flags,
                                              dav_lockdb *lockdb);
/*
** flags:
**    0x0F -- reserved for <dav_lock_scope> values
**
**    other flags, detailed below
*/
#define DAV_VALIDATE_RESOURCE   0x0010  /* validate just the resource */
#define DAV_VALIDATE_PARENT     0x0020  /* validate resource AND its parent */
#define DAV_VALIDATE_ADD_LD     0x0040  /* add DAV:lockdiscovery into
                                           the 424 DAV:response */
#define DAV_VALIDATE_USE_424    0x0080  /* return 424 status, not 207 */
#define DAV_VALIDATE_IS_PARENT  0x0100  /* for internal use */

/* Lock-null related public lock functions */
DAV_DECLARE(int) dav_get_resource_state(request_rec *r,
                                        const dav_resource *resource);

/* Lock provider hooks. Locking is optional, so there may be no
 * lock provider for a given repository.
 */
struct dav_hooks_locks
{
    /* Return the supportedlock property for a resource */
    const char * (*get_supportedlock)(
        const dav_resource *resource
    );

    /* Parse a lock token URI, returning a lock token object allocated
     * in the given pool.
     */
    dav_error * (*parse_locktoken)(
        apr_pool_t *p,
        const char *char_token,
        dav_locktoken **locktoken_p
    );

    /* Format a lock token object into a URI string, allocated in
     * the given pool.
     *
     * Always returns non-NULL.
     */
    const char * (*format_locktoken)(
        apr_pool_t *p,
        const dav_locktoken *locktoken
    );

    /* Compare two lock tokens.
     *
     * Result < 0  => lt1 < lt2
     * Result == 0 => lt1 == lt2
     * Result > 0  => lt1 > lt2
     */
    int (*compare_locktoken)(
        const dav_locktoken *lt1,
        const dav_locktoken *lt2
    );

    /* Open the provider's lock database.
     *
     * The provider may or may not use a "real" database for locks
     * (a lock could be an attribute on a resource, for example).
     *
     * The provider may choose to use the value of the DAVLockDB directive
     * (as returned by dav_get_lockdb_path()) to decide where to place
     * any storage it may need.
     *
     * The request storage pool should be associated with the lockdb,
     * so it can be used in subsequent operations.
     *
     * If ro != 0, only readonly operations will be performed.
     * If force == 0, the open can be "lazy"; no subsequent locking operations
     * may occur.
     * If force != 0, locking operations will definitely occur.
     */
    dav_error * (*open_lockdb)(
        request_rec *r,
        int ro,
        int force,
        dav_lockdb **lockdb
    );

    /* Indicates completion of locking operations */
    void (*close_lockdb)(
        dav_lockdb *lockdb
    );

    /* Take a resource out of the lock-null state. */
    dav_error * (*remove_locknull_state)(
        dav_lockdb *lockdb,
        const dav_resource *resource
    );

    /*
    ** Create a (direct) lock structure for the given resource. A locktoken
    ** will be created.
    **
    ** The lock provider may store private information into lock->info.
    */
    dav_error * (*create_lock)(dav_lockdb *lockdb,
                               const dav_resource *resource,
                               dav_lock **lock);

    /*
    ** Get the locks associated with the specified resource.
    **
    ** If resolve_locks is true (non-zero), then any indirect locks are
    ** resolved to their actual, direct lock (i.e. the reference to followed
    ** to the original lock).
    **
    ** The locks, if any, are returned as a linked list in no particular
    ** order. If no locks are present, then *locks will be NULL.
    */
    dav_error * (*get_locks)(dav_lockdb *lockdb,
                             const dav_resource *resource,
                             int calltype,
                             dav_lock **locks);

#define DAV_GETLOCKS_RESOLVED   0    /* resolve indirects to directs */
#define DAV_GETLOCKS_PARTIAL    1    /* leave indirects partially filled */
#define DAV_GETLOCKS_COMPLETE   2    /* fill out indirect locks */

    /*
    ** Find a particular lock on a resource (specified by its locktoken).
    **
    ** *lock will be set to NULL if the lock is not found.
    **
    ** Note that the provider can optimize the unmarshalling -- only one
    ** lock (or none) must be constructed and returned.
    **
    ** If partial_ok is true (non-zero), then an indirect lock can be
    ** partially filled in. Otherwise, another lookup is done and the