mod_dav.h

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

#define DAV_PROPFIND_IS_PROPNAME	2
#define DAV_PROPFIND_IS_PROP		3

    ap_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.
*/

typedef struct dav_stream dav_stream;

typedef enum {
    DAV_MODE_READ,		/* open for reading */
    DAV_MODE_READ_SEEKABLE,	/* open for random access reading */
    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);

    /*
    ** Read data from the stream.
    **
    ** The size of the buffer is passed in *bufsize, and the amount read
    ** is returned in *bufsize.
    **
    ** *bufsize should be set to zero when the end of file is reached.
    ** As a corollary, this function should always read at least one byte
    ** on each call, until the EOF condition is met.
    */
    dav_error * (*read_stream)(dav_stream *stream,
			       void *buf, apr_size_t *bufsize);

    /*
    ** 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 stream (open_stream, read_stream)
    ** rather than via a sub-request (on get_pathname), then this function
    ** is used to provide the repository with a way to set the headers
    ** in the response.
    **
    ** It may be NULL if get_pathname is provided.
    */
    dav_error * (*set_headers)(request_rec *r,
			       const dav_resource *resource);

    /* Get a pathname for the file represented by the resource descriptor.
     * A provider may need to create a temporary copy of the file, if it is
     * not directly accessible in a filesystem. free_handle_p will be set by
     * the provider to point to information needed to clean up any temporary
     * storage used.
     *
     * Returns NULL if the file could not be made accessible.
     */
    const char * (*get_pathname)(
        const dav_resource *resource,
        void **free_handle_p
    );

    /* Free any temporary storage associated with a file made accessible by
     * get_pathname().
     */
    void (*free_file)(
        void *free_handle
    );

    /* Create a collection resource. The resource must not already exist.
     *
     * Result == NULL if the collection was created successfully. Also, the
     * resource object is updated to reflect that the resource exists, and
     * is a collection.
     */
    dav_error * (*create_collection)(
        dav_resource *resource
    );

    /* Copy one resource to another. The destination must not exist.
     * Handles both files and collections. Properties are copied as well.
     * The depth argument is ignored for a file, and can be either 0 or
     * DAV_INFINITY for a collection.
     * If an error occurs in a child resource, then the return value is
     * non-NULL, and *response is set to a multistatus response.
     * If the copy is successful, the dst resource object is
     * updated to reflect that the resource exists.
     */
    dav_error * (*copy_resource)(
        const dav_resource *src,
        dav_resource *dst,
	int depth,
        dav_response **response
    );

    /* Move one resource to another. The destination must not exist.
     * Handles both files and collections. Properties are moved as well.
     * If an error occurs in a child resource, then the return value is
     * non-NULL, and *response is set to a multistatus response.
     * If the move is successful, the src and dst resource objects are
     * updated to reflect that the source no longer exists, and the
     * destination does.
     */
    dav_error * (*move_resource)(
        dav_resource *src,
        dav_resource *dst,
        dav_response **response
    );

    /* Remove a resource. Handles both files and collections.
     * Removes any associated properties as well.
     * If an error occurs in a child resource, then the return value is
     * non-NULL, and *response is set to a multistatus response.
     * If the delete is successful, the resource object is updated to
     * reflect that the resource no longer exists.
     */
    dav_error * (*remove_resource)(
        dav_resource *resource,
        dav_response **response
    );

    /* Walk a resource hierarchy.
     *
     * Iterates over the resource hierarchy specified by params->root.
     * Control of the walk and the callback are specified by 'params'.
     *
     * An error may be returned. *response will contain multistatus
     * responses (if any) suitable for the body of the error. It is also
     * possible to return NULL, yet still have multistatus responses.
     * In this case, typically the caller should return a 207 (Multistatus)
     * and the responses (in the body) as the HTTP response.
     */
    dav_error * (*walk)(const dav_walk_params *params, int depth,
                        dav_response **response);

    /* Get the entity tag for a resource */
    const char * (*getetag)(const dav_resource *resource);
};


/* --------------------------------------------------------------------
**
** VERSIONING FUNCTIONS
*/


/* dav_add_vary_header
 *
 * If there were any headers in the request which require a Vary header
 * in the response, add it.
 */
void dav_add_vary_header(request_rec *in_req,
			 request_rec *out_req,
			 const dav_resource *resource);

/*
** This structure is used to record what auto-versioning operations
** were done to make a resource writable, so that they can be undone
** at the end of a request.
*/
typedef struct {
    int resource_created;               /* 0 => resource existed previously */
    int resource_checkedout;            /* 0 => resource was checked out */
    int parent_checkedout;              /* 0 => parent was checked out */
    dav_resource *parent_resource;      /* parent resource, if it was needed */
} dav_auto_version_info;

/* Ensure that a resource is writable. If there is no versioning
 * provider, then this is essentially a no-op. Versioning repositories
 * require explicit resource creation and checkout before they can
 * be written to. If a new resource is to be created, or an existing
 * resource deleted, the parent collection must be checked out as well.
 *
 * Set the parent_only flag to only make the parent collection writable.
 * Otherwise, both parent and child are made writable as needed. If the
 * child does not exist, then a new versioned resource is created and
 * checked out.
 *
 * The dav_auto_version_info structure is filled in with enough information
 * to restore both parent and child resources to the state they were in
 * before the auto-versioning operations occurred.
 */
dav_error *dav_ensure_resource_writable(request_rec *r,
					dav_resource *resource,
                                        int parent_only,
                                        dav_auto_version_info *av_info);

/* Revert the writability of resources back to what they were
 * before they were modified. If undo == 0, then the resource
 * modifications are maintained (i.e. they are checked in).
 * If undo != 0, then resource modifications are discarded
 * (i.e. they are unchecked out).
 *
 * The resource argument may be NULL if only the parent resource
 * was made writable (i.e. the parent_only was != 0 in the
 * dav_ensure_resource_writable call).
 */
dav_error *dav_revert_resource_writability(
    request_rec *r,
    dav_resource *resource,
    int undo,
    const dav_auto_version_info *av_info);

/*
** This structure is used to describe available reports
**
** "nmspace" should be valid XML and URL-quoted. mod_dav will place
** double-quotes around it and use it in an xmlns declaration.
*/
typedef struct {
    const char *nmspace;        /* namespace of the XML report element */
    const char *name;           /* element name for the XML report */
} dav_report_elem;


/* Versioning provider hooks */
struct dav_hooks_vsn
{
    /*
    ** MANDATORY HOOKS
    ** The following hooks are mandatory for all versioning providers;
    ** they define the functionality needed to implement "core" versioning.
    */

    /* Return supported versioning options.
     * Each dav_text item in the list will be returned as a separate
     * DAV header. Providers are advised to limit the length of an
     * individual text item to 63 characters, to conform to the limit
     * used by MS Web Folders.
     */
    void (*get_vsn_options)(apr_pool_t *p, ap_text_header *phdr);

    /* Get the value of a specific option for an OPTIONS request.
     * The option being requested is given by the parsed XML
     * element object "elem". The value of the option should be
     * appended to the "option" text object.