mod_dav.h

Apache HTTP Server 是一个功能强大的灵活的与HTTP/1.1相兼容的web服务器.这里给出的是Apache HTTP服务器的源码。

    ** lock (token) was asserted.
    **
    ** NOTE: this function pointer is allowed to be NULL, indicating that
    **       the provider does not support this type of functionality. The
    **       caller should then traverse up the repository hierarchy looking
    **       for the resource defining a lock with this locktoken.
    */
    dav_error * (*lookup_resource)(dav_lockdb *lockdb,
                                   const dav_locktoken *locktoken,
                                   const dav_resource *start_resource,
                                   const dav_resource **resource);

    /*
    ** 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;
};

/* what types of resources can be discovered by dav_get_resource_state() */
#define DAV_RESOURCE_LOCK_NULL  10    /* resource lock-null */
#define DAV_RESOURCE_NULL       11    /* resource null */
#define DAV_RESOURCE_EXISTS     12    /* resource exists */
#define DAV_RESOURCE_ERROR      13    /* an error occurred */


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

typedef struct dav_propdb dav_propdb;


dav_error *dav_open_propdb(
    request_rec *r,
    dav_lockdb *lockdb,
    const dav_resource *resource,
    int ro,
    apr_array_header_t *ns_xlate,
    dav_propdb **propdb);

void dav_close_propdb(dav_propdb *db);

dav_get_props_result dav_get_props(
    dav_propdb *db,
    apr_xml_doc *doc);

dav_get_props_result dav_get_allprops(
    dav_propdb *db,
    dav_prop_insert what);

void dav_get_liveprop_supported(
    dav_propdb *propdb,
    const char *ns_uri,
    const char *propname,
    apr_text_header *body);

/*
** 3-phase property modification.
**
**   1) validate props. readable? unlocked? ACLs allow access?
**   2) execute operation (set/delete)
**   3) commit or rollback
**
** ### eventually, auth must be available. a ref to the request_rec (which
** ### contains the auth info) should be in the shared context struct.
**
** Each function may alter the error values and information contained within
** the context record. This should be done as an "increasing" level of
** error, rather than overwriting any previous error.
**
** Note that commit() cannot generate errors. It should simply free the
** rollback information.
**
** rollback() may generate additional errors because the rollback operation
** can sometimes fail(!).
**
** The caller should allocate an array of these, one per operation. It should
** be zero-initialized, then the db, operation, and prop fields should be
** filled in before calling dav_prop_validate. Note that the set/delete
** operations are order-dependent. For a given (logical) context, the same
** pointer must be passed to each phase.
**
** error_type is an internal value, but will have the same numeric value
** for each possible "desc" value. This allows the caller to group the
** descriptions via the error_type variable, rather than through string
** comparisons. Note that "status" does not provide enough granularity to
** differentiate/group the "desc" values.
**
** Note that the propdb will maintain some (global) context across all
** of the property change contexts. This implies that you can have only
** one open transaction per propdb.
*/
typedef struct dav_prop_ctx
{
    dav_propdb *propdb;

    int operation;
#define DAV_PROP_OP_SET        1    /* set a property value */
#define DAV_PROP_OP_DELETE     2    /* delete a prop value */
/* ### add a GET? */

    apr_xml_elem *prop;             /* property to affect */

    dav_error *err;                 /* error (if any) */

    /* private items to the propdb */
    int is_liveprop;
    void *liveprop_ctx;
    struct dav_rollback_item *rollback;  /* optional rollback info */

    /* private to mod_dav.c */
    request_rec *r;

} dav_prop_ctx;

void dav_prop_validate(dav_prop_ctx *ctx);
void dav_prop_exec(dav_prop_ctx *ctx);
void dav_prop_commit(dav_prop_ctx *ctx);
void dav_prop_rollback(dav_prop_ctx *ctx);

#define DAV_PROP_CTX_HAS_ERR(dpc)  ((dpc).err && (dpc).err->status >= 300)


/* --------------------------------------------------------------------
**
** WALKER STRUCTURE
*/

enum {
    DAV_CALLTYPE_MEMBER = 1,    /* called for a member resource */
    DAV_CALLTYPE_COLLECTION,    /* called for a collection */
    DAV_CALLTYPE_LOCKNULL       /* called for a locknull resource */
};

typedef struct
{
    /* the client-provided context */
    void *walk_ctx;

    /* pool to use for allocations in the callback */
    apr_pool_t *pool;

    /* the current resource */
    const dav_resource *resource;

    /* OUTPUT: add responses to this */
    dav_response *response;

} dav_walk_resource;

typedef struct
{
    int walk_type;
#define DAV_WALKTYPE_AUTH       0x0001  /* limit to authorized files */
#define DAV_WALKTYPE_NORMAL     0x0002  /* walk normal files */
#define DAV_WALKTYPE_LOCKNULL   0x0004  /* walk locknull resources */

    /* callback function and a client context for the walk */
    dav_error * (*func)(dav_walk_resource *wres, int calltype);
    void *walk_ctx;

    /* what pool to use for allocations needed by walk logic */
    apr_pool_t *pool;

    /* beginning root of the walk */
    const dav_resource *root;

    /* lock database to enable walking LOCKNULL resources */
    dav_lockdb *lockdb;

} dav_walk_params;

/* directory tree walking context */
typedef struct dav_walker_ctx
{
    /* input: */
    dav_walk_params w;


    /* ### client data... phasing out this big glom */

    /* this brigade buffers data being sent to r->output_filters */ 
    apr_bucket_brigade *bb;

    /* a scratch pool, used to stream responses and iteratively cleared. */
    apr_pool_t *scratchpool;

    request_rec *r;                 /* original request */

    /* for PROPFIND operations */
    apr_xml_doc *doc;
    int propfind_type;
#define DAV_PROPFIND_IS_ALLPROP     1
#define DAV_PROPFIND_IS_PROPNAME    2
#define DAV_PROPFIND_IS_PROP        3

    apr_text *propstat_404;         /* (cached) propstat giving a 404 error */

    const dav_if_header *if_header; /* for validation */
    const dav_locktoken *locktoken; /* for UNLOCK */
    const dav_lock *lock;           /* for LOCK */
    int skip_root;                  /* for dav_inherit_locks() */

    int flags;

    dav_buffer work_buf;            /* for dav_validate_request() */

} dav_walker_ctx;

DAV_DECLARE(void) dav_add_response(dav_walk_resource *wres,
                                   int status,
                                   dav_get_props_result *propstats);


/* --------------------------------------------------------------------
**
** "STREAM" STRUCTURE
**
** mod_dav uses this abstraction for interacting with the repository
** while fetching/storing resources. mod_dav views resources as a stream
** of bytes.
**
** Note that the structure is opaque -- it is private to the repository
** that created the stream in the repository's "open" function.
**
** ### THIS STUFF IS GOING AWAY ... GET/read requests are handled by
** ### having the provider jam stuff straight into the filter stack.
** ### this is only left for handling PUT/write requests.
*/

typedef struct dav_stream dav_stream;

typedef enum {
    DAV_MODE_WRITE_TRUNC,      /* truncate and open for writing */
    DAV_MODE_WRITE_SEEKABLE    /* open for writing; random access */
} dav_stream_mode;


/* --------------------------------------------------------------------
**
** REPOSITORY FUNCTIONS
*/

/* Repository provider hooks */
struct dav_hooks_repository
{
    /* Flag for whether repository requires special GET handling.
     * If resources in the repository are not visible in the
     * filesystem location which URLs map to, then special handling
     * is required to first fetch a resource from the repository,
     * respond to the GET request, then free the resource copy.
     */
    int handle_get;

    /* Get a resource descriptor for the URI in a request. A descriptor
     * should always be returned even if the resource does not exist. This
     * repository has been identified as handling the resource given by
     * the URI, so an answer must be given. If there is a problem with the
     * URI or accessing the resource or whatever, then an error should be
     * returned.
     *
     * root_dir:
     *   the root of the directory for which this repository is configured.
     *
     * label:
     *   if a Label: header is present (and allowed), this is the label
     *   to use to identify a version resource from the resource's
     *   corresponding version history. Otherwise, it will be NULL.
     *
     * use_checked_in:
     *   use the DAV:checked-in property of the resource identified by the
     *   Request-URI to identify and return a version resource
     *
     * The provider may associate the request storage pool with the resource
     * (in the resource->pool field), to use in other operations on that
     * resource. 
     */
    dav_error * (*get_resource)(
        request_rec *r,
        const char *root_dir,
        const char *label,
        int use_checked_in,
        dav_resource **resource
    );

    /* Get a resource descriptor for the parent of the given resource.
     * The resources need not exist.  NULL is returned if the resource 
     * is the root collection.
     *
     * An error should be returned only if there is a fatal error in
     * fetching information about the parent resource.
     */
    dav_error * (*get_parent_resource)(
        const dav_resource *resource,
        dav_resource **parent_resource
    );

    /* Determine whether two resource descriptors refer to the same resource.
    *
     * Result != 0 => the resources are the same.
     */
    int (*is_same_resource)(
        const dav_resource *res1,
        const dav_resource *res2
    );

    /* Determine whether one resource is a parent (immediate or otherwise)
     * of another.
     *
     * Result != 0 => res1 is a parent of res2.
     */
    int (*is_parent_resource)(
        const dav_resource *res1,
        const dav_resource *res2
    );

    /*
    ** Open a stream for this resource, using the specified mode. The
    ** stream will be returned in *stream.
    */
    dav_error * (*open_stream)(const dav_resource *resource,
                               dav_stream_mode mode,
                               dav_stream **stream);

    /*
    ** Close the specified stream.
    **
    ** mod_dav will (ideally) make sure to call this. For safety purposes,
    ** a provider should (ideally) register a cleanup function with the
    ** request pool to get this closed and cleaned up.
    **
    ** Note the possibility of an error from the close -- it is entirely
    ** feasible that the close does a "commit" of some kind, which can
    ** produce an error.
    **
    ** commit should be TRUE (non-zero) or FALSE (0) if the stream was
    ** opened for writing. This flag states whether to retain the file
    ** or not.
    ** Note: the commit flag is ignored for streams opened for reading.
    */
    dav_error * (*close_stream)(dav_stream *stream, int commit);

    /*
    ** Write data to the stream.
    **
    ** All of the bytes must be written, or an error should be returned.
    */
    dav_error * (*write_stream)(dav_stream *stream,
                                const void *buf, apr_size_t bufsize);

    /*
    ** Seek to an absolute position in the stream. This is used to support
    ** Content-Range in a GET/PUT.
    **
    ** NOTE: if this function is NULL (which is allowed), then any
    **       operations using Content-Range will be refused.
    */
    dav_error * (*seek_stream)(dav_stream *stream, apr_off_t abs_position);

    /*
    ** If a GET is processed using a st