mod_dav.h revision f4c310fd2555c6faca1f980f00b161eadb089023
/*
** Copyright (C) 1998-2000 Greg Stein. All Rights Reserved.
**
** By using this file, you agree to the terms and conditions set forth in
** the LICENSE.html file which can be found at the top level of the mod_dav
** distribution or at http://www.webdav.org/mod_dav/license-1.html.
**
** Contact information:
** Greg Stein, PO Box 760, Palo Alto, CA, 94302
** gstein@lyra.org, http://www.webdav.org/mod_dav/
*/
/*
** DAV extension module for Apache 1.3.*
**
** Written by Greg Stein, gstein@lyra.org, http://www.lyra.org/
*/
#ifndef _MOD_DAV_H_
#define _MOD_DAV_H_
#ifdef __cplusplus
extern "C" {
#endif
#include "httpd.h"
#define DAV_VERSION "1.0.1"
#define DAV_XML_HEADER "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
#define DAV_XML_CONTENT_TYPE "text/xml; charset=\"utf-8\""
#ifdef WIN32
#include <limits.h>
typedef int ssize_t;
#endif /* WIN32 */
#define DAV_RESPONSE_BODY_1 "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<HTML><HEAD>\n<TITLE>"
#define DAV_RESPONSE_BODY_2 "</TITLE>\n</HEAD><BODY>\n<H1>"
#define DAV_RESPONSE_BODY_3 "</H1>\n"
#define DAV_RESPONSE_BODY_4 "</BODY></HTML>\n"
#define DAV_DO_COPY 0
#define DAV_DO_MOVE 1
#if 1
#define DAV_DEBUG 1
#define DEBUG_CR "\n"
#else
#define DEBUG_CR ""
#endif
/* --------------------------------------------------------------------
**
** ERROR MANAGEMENT
*/
/*
** dav_error structure.
**
** In most cases, mod_dav uses a pointer to a dav_error structure. If the
** pointer is NULL, then no error has occurred.
**
** In certain cases, a dav_error structure is directly used. In these cases,
** a status value of 0 means that an error has not occurred.
**
** Note: this implies that status != 0 whenever an error occurs.
**
** The desc field is optional (it may be NULL). When NULL, it typically
** implies that Apache has a proper description for the specified status.
*/
typedef struct dav_error {
int status; /* suggested HTTP status (0 for no error) */
int error_id; /* DAV-specific error ID */
const char *desc; /* DAV:responsedescription and error log */
int save_errno; /* copy of errno causing the error */
/* deferred computation of the description */
int ctx_i;
const char *ctx_s;
void *ctx_p;
} dav_error;
/*
** Create a new error structure. save_errno will be filled with the current
** errno value.
*/
/*
** Push a new error description onto the stack of errors.
**
** This function is used to provide an additional description to an existing
** error.
**
** <status> should contain the caller's view of what the current status is,
** given the underlying error. If it doesn't have a better idea, then the
** caller should pass prev->status.
**
** <error_id> can specify a new error_id since the topmost description has
** changed.
*/
/* error ID values... */
/* IF: header errors */
/* Prop DB errors */
/* Predefined DB errors */
/* ### any to define?? */
/* Predefined locking system errors */
/*
** Some comments on Error ID values:
**
** The numbers do not necessarily need to be unique. Uniqueness simply means
** that two errors that have not been predefined above can be distinguished
** from each other. At the moment, mod_dav does not use this distinguishing
** feature, but it could be used in the future to collapse <response> elements
** into groups based on the error ID (and associated responsedescription).
**
** If a compute_desc is provided, then the error ID should be unique within
** the context of the compute_desc function (so the function can figure out
** what to filled into the desc).
**
** Basically, subsystems can ignore defining new error ID values if they want
** to. The subsystems *do* need to return the predefined errors when
** appropriate, so that mod_dav can figure out what to do. Subsystems can
** simply leave the error ID field unfilled (zero) if there isn't an error
** that must be placed there.
*/
/* --------------------------------------------------------------------
**
** HOOK STRUCTURES
**
** These are here for forward-declaration purposes. For more info, see
** the section title "HOOK HANDLING" for more information, plus each
** structure definition.
*/
/* forward-declare this structure */
typedef struct dav_hooks_db dav_hooks_db;
typedef struct dav_hooks_locks dav_hooks_locks;
typedef struct dav_hooks_vsn dav_hooks_vsn;
typedef struct dav_hooks_repository dav_hooks_repository;
typedef struct dav_hooks_liveprop dav_hooks_liveprop;
/* --------------------------------------------------------------------
**
** RESOURCE HANDLING
*/
/*
** Resource Types:
** The base protocol defines only file and collection resources.
** The versioning protocol defines several additional resource types
** to represent artifacts of a version control system.
*/
typedef enum {
DAV_RESOURCE_TYPE_REGULAR, /* file or collection, working resource
or revision */
DAV_RESOURCE_TYPE_REVISION, /* explicit revision-id */
DAV_RESOURCE_TYPE_HISTORY, /* explicit history-id */
DAV_RESOURCE_TYPE_WORKSPACE, /* workspace */
DAV_RESOURCE_TYPE_ACTIVITY, /* activity */
DAV_RESOURCE_TYPE_CONFIGURATION /* configuration */
/*
** Opaque, repository-specific information for a resource.
*/
typedef struct dav_resource_private dav_resource_private;
/* Resource descriptor, generated by a repository provider.
* Note: the lock-null state is not explicitly represented here,
* since it may be expensive to compute. Use dav_get_resource_state()
* to determine whether a non-existent resource is a lock-null resource.
*/
typedef struct dav_resource {
int exists; /* 0 => null resource */
int collection; /* 0 => file (if type == DAV_RESOURCE_TYPE_REGULAR) */
int versioned; /* 0 => unversioned */
int working; /* 0 => revision (if versioned) */
int baselined; /* 0 => not baselined */
const char *uri; /* the URI for this resource */
} 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
{
char *buf; /* buffer contents */
} dav_buffer;
/* set the cur_len to the given size and ensure space is available */
/* initialize a buffer and copy the specified (null-term'd) string into it */
/* check that the buffer can accomodate <extra_needed> more bytes */
/* append a string to the end of the buffer, adjust length */
/* place a string on the end of the buffer, do NOT adjust length */
/* place some memory on the end of a buffer; do NOT adjust length */
/* --------------------------------------------------------------------
**
** HANDY UTILITIES
*/
/* simple strutures to keep a linked list of pieces of text */
typedef struct dav_text
{
const char *text;
} dav_text;
typedef struct
{
/* contains results from one of the getprop functions */
typedef struct
{
/* 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. */
int status;
struct dav_response *next;
} dav_response;
typedef struct
{
/* 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
/* --------------------------------------------------------------------
**
** DYNAMIC EXTENSIONS
*/
/* ### docco goes here... */
/*
** This structure is used to define the runtime, per-directory/location
** operating context for a single provider.
*/
typedef struct
{
int id; /* provider ID */
void *m_context; /* module-level context (i.e. managed globals) */
void *d_context; /* per-directory context */
int *ns_map; /* for LIVEPROP, map provider URI to global URI */
/*
** This structure is used to specify a set of hooks and its associated
** context, on a per-directory/location basis.
**
** Note: the context is assembled from various sources. dav_dyn_hooks
** structures will typically have the same pointer values within the
** context (e.g. ctx.m_context is shared across all providers in a module).
*/
typedef struct dav_dyn_hooks
{
const void *hooks; /* the type-specific hooks */
/*
** These enumerated values define the different types of functionality that
** a provider can implement.
*/
enum
{
DAV_DYN_TYPE_PROPDB, /* property database (1 per dir) */
DAV_DYN_TYPE_LOCKS, /* lock handling (1 per dir) */
DAV_DYN_TYPE_QUERY_GRAMMAR, /* DASL search grammar (N per dir) */
DAV_DYN_TYPE_ACL, /* ACL handling (1 per dir) */
DAV_DYN_TYPE_VSN, /* versioning (1 per dir) */
DAV_DYN_TYPE_REPOSITORY, /* resource repository (1 per dir) */
DAV_DYN_TYPE_LIVEPROP, /* live property handler (N per dir) */
};
/*
** This structure defines a provider for a particular type of functionality.
**
** The ID is private to a provider and can be used to differentiate between
** different subclasses of functionality which are implemented using the
** same set of hooks. For example, a hook function could perform two entirely
** different operations based on the ID which is passed.
**
** is_active() is used by the system to determine whether a particular
** provider is "active" for the given context. It is possible that a provider
** is configured for a directory, but has not been enabled -- the is_active()
** function is used to determine that information.
**
** ### is_active is not used right now
**
** Note: dav_dyn_provider structures are always treated as "const" by mod_dav.
*/
typedef struct dav_dyn_provider
{
int id; /* provider ID */
int type; /* provider's functionality type */
const void *hooks; /* pointer to type-specific hooks */
/*
** This structure defines a module (a set of providers).
**
** The friendly name should be a single word. It is used with the "DAV"
**
** The module_open/close functions are used to initialize per-module "global"
** data. The functions are expected to update ctx->m_context.
**
** ### module_open/close are not used at the moment
** ### dir_* are not well-defined, nor are they used
**
** Note: The DAV_DYN_VERSION specifies the version of the dav_dyn_module
** structure itself. It will be updated if changes in the structure
** are made. There are no provisions for forward or backward
** compatible changes.
**
** Note: dav_dyn_module structures are always treated as "const" by mod_dav.
*/
typedef struct
{
int magic;
int version;
const char *name; /* friendly name */
const char *param_value);
const char *filename);
/*
** Various management functions.
**
** NOTE: the pool should be the "configuration pool"
*/
void dav_process_builtin_modules(pool *p);
extern array_header *dav_liveprop_uris;
int dav_scan_providers(void *ctx,
const dav_dyn_provider **provider,
/* handy macros to assist with dav_dyn_hooks.hooks usage */
/* get provider hooks, given a request record */
#define DAV_GET_HOOKS_QUERY_GRAMMAR(r) DAV_AS_HOOKS_QUERY_GRAMMAR(dav_get_provider_hooks(r, DAV_DYN_TYPE_QUERY_GRAMMAR))
#define DAV_GET_HOOKS_REPOSITORY(r) DAV_AS_HOOKS_REPOSITORY(dav_get_provider_hooks(r, DAV_DYN_TYPE_REPOSITORY))
#define DAV_GET_HOOKS_LIVEPROP(r) DAV_AS_HOOKS_LIVEPROP(dav_get_provider_hooks(r, DAV_DYN_TYPE_LIVEPROP))
/* --------------------------------------------------------------------
**
** 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
{
typedef struct dav_if_state_list
{
int condition;
#define DAV_IF_COND_NORMAL 0
const char *etag; /* etag */
struct dav_if_state_list *next;
typedef struct dav_if_header
{
const char *uri;
struct dav_if_state_list *state;
struct dav_if_header *next;
int dummy_header; /* used internally by the lock/etag validation */
typedef struct dav_locktoken_list
{
struct dav_locktoken_list *next;
/* --------------------------------------------------------------------
**
** XML PARSING
*/
/*
** Qualified namespace values
**
** DAV_NS_DAV_ID
** We always insert the "DAV:" namespace URI at the head of the
** namespace array. This means that it will always be at ID==0,
** making it much easier to test for.
**
** DAV_NS_NONE
** This special ID is used for two situations:
**
** 1) The namespace prefix begins with "xml" (and we do not know
** what it means). Namespace prefixes with "xml" (any case) as
** their first three characters are reserved by the XML Namespaces
** specification for future use. mod_dav will pass these through
** unchanged. When this identifier is used, the prefix is LEFT in
** prepend another prefix.
**
**
** a) No prefix was used, and a default namespace has not been
** defined.
** b) No prefix was used, and the default namespace was specified
** to mean "no namespace". This is done with a namespace
** declaration of: xmlns=""
** (this declaration is typically used to override a previous
** specification for the default namespace)
**
** namespace so that we will not attempt to prepend a prefix.
** All namespaces that are used will have a prefix assigned to
** them -- mod_dav will never set or use the default namespace
** when generating XML. This means that "no prefix" will always
** mean "no namespace".
**
** In both cases, the XML generation will avoid prepending a prefix.
** inserted into the output stream. For the latter case, it means
** the name will have no prefix, and since we never define a default
** namespace, this means it will have no namespace.
**
** Note: currently, mod_dav understands the "xmlns" prefix and the
** "xml:lang" attribute. These are handled specially (they aren't
** left within the XML tree), so the DAV_NS_NONE value won't ever
** really apply to these values.
*/
#define DAV_NS_DAV_ID 0 /* namespace ID for "DAV:" */
#define DAV_NS_IS_ERROR(e) ((e) <= DAV_NS_ERROR_BASE)
/*
** dav_xml_doc: holds a parsed XML document
** dav_xml_elem: holds a parsed XML element
** dav_xml_attr: holds a parsed XML attribute
**
** dav_xml_ns_scope: internal struct used during processing to scope
** namespace declarations
*/
typedef struct dav_xml_attr
{
const char *name; /* attribute name */
int ns; /* index into namespace array */
const char *value; /* attribute value */
} dav_xml_attr;
typedef struct dav_xml_elem
{
const char *name; /* element name */
int ns; /* index into namespace array */
/* used only during parsing */
/* used during request processing */
int propid; /* live property ID */
const int *ns_map; /* ns map for this provider */
} dav_xml_elem;
typedef struct dav_xml_doc
{
} dav_xml_doc;
const dav_xml_elem *elem,
const char *tagname);
void dav_xml2text(
pool *p,
const dav_xml_elem *elem,
int style,
int *ns_map,
const char **pbuf,
);
#define DAV_X2T_FULL 0 /* start tag, contents, end tag */
/* --------------------------------------------------------------------
**
** LIVE PROPERTY HANDLING
*/
typedef enum {
DAV_PROP_INSERT_NOTME, /* prop not defined by this provider */
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_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 */
typedef enum {
DAV_PROP_RW_NOTME, /* not my property */
DAV_PROP_RW_NO, /* property is NOT writeable */
DAV_PROP_RW_YES /* property IS writeable */
} dav_prop_rw;
/* opaque type for PROPPATCH rollback information */
typedef struct dav_liveprop_rollback dav_liveprop_rollback;
struct dav_hooks_liveprop
{
/*
** This URI is returned in the DAV: header to let clients know what
** sets of live properties are supported by the installation. mod_dav
** 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)
*/
const char * propset_uri;
/*
** Find a property, returning a non-zero, unique, opaque identifier.
**
** NOTE: Providers must ensure this identifier is universally unique.
** See the registration table below.
** ### it would be nice to avoid this uniqueness constraint. however,
** ### that would mean our xml_elem annotation concept would need to
** ### change (w.r.t. the fact that it acts as a cache for find_prop).
**
** Returns 0 if the property is not defined by this provider.
*/
/*
** insert is identified by the propid value. Providers should return
** DAV_PROP_INSERT_NOTME if they do not define the specified propid.
** If insvalue is true, then the property's value should be inserted;
** otherwise, an empty element (ie. just the prop's name) should be
** inserted.
**
** Returns one of DAV_PROP_INSERT_* based on what happened.
**
** ### we may need more context... ie. the lock database
*/
/*
** similar to insert_prop, but *all* properties will be inserted
** rather than specific, individual properties.
*/
/*
** Determine whether a given property is writeable.
**
** ### we may want a different semantic. i.e. maybe it should be
** ### "can we write <value> into this property?"
**
*/
/*
** 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
*/
/*
** Validate that the live property can be assigned a value, and that
** the provided value is valid.
**
** elem will point to the XML element that names the property. For
** example:
** <lp1:executable>T</lp1:executable>
**
** The provider can access the cdata fields and the child elements
** to extract the relevant pieces.
**
** operation is one of DAV_PROP_OP_SET or _DELETE.
**
** The provider may return a value in *context which will be passed
** may contain an internal value which has been processed from the
** input element.
**
** The provider must set defer_to_dead to true (non-zero) or false.
** database. Note: it will be set to zero on entry.
*/
const dav_xml_elem *elem,
int operation,
void **context,
int *defer_to_dead);
/* ### doc... */
const dav_xml_elem *elem,
int operation,
void *context,
/* ### doc... */
int operation,
void *context,
/* ### doc... */
int operation,
void *context,
};
/*
** Property Identifier Registration
**
** At the moment, mod_dav requires live property providers to ensure that
** each property returned has a unique value. For now, this is done through
** central registration (there are no known providers other than the default,
** so this remains manageable).
**
** WARNING: the TEST ranges should never be "shipped".
*/
mod_dav filesystem provider. */
/* Next: 10600 */
/* --------------------------------------------------------------------
**
** DATABASE FUNCTIONS
*/
typedef struct
{
char *dptr;
} dav_datum;
/* hook functions to enable pluggable databases */
struct dav_hooks_db
{
/*
** Fetch the value from the database. If the value does not exist,
** then *pvalue should be zeroed.
**
*/
/* returns 1 if the record specified by "key" exists; 0 otherwise */
};
/* --------------------------------------------------------------------
**
** LOCK FUNCTIONS
*/
/* Used to represent a Timeout header of "Infinity" */
#define DAV_TIMEOUT_INFINITE 0
/*
** Opaque, repository-specific information for a lock database.
*/
typedef struct dav_lockdb_private dav_lockdb_private;
/*
** Opaque, repository-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
{
int ro; /* was it opened readonly? */
} dav_lockdb;
typedef enum {
typedef enum {
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: 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
**
** 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
{
int is_locknull; /* lock establishes a locknull resource */
/* ### put the resource in here? */
int depth; /* depth of the lock */
const char *owner; /* (XML) owner of the lock */
const char *auth_user; /* auth'd username owning lock */
} dav_lock;
/* Property-related public lock functions */
dav_buffer *pbuf);
/* LockDB-related public lock functions */
const char *dav_get_lockdb_path(const request_rec *r);
const dav_resource *resrouce,
const dav_xml_doc *doc,
dav_lock **lock_request);
const dav_locktoken *locktoken);
dav_response **response);
const dav_resource *resource,
int resource_state,
int depth);
dav_lockdb *lockdb);
/*
** flags:
** 0x0F -- reserved for <dav_lock_scope> values
**
** other flags, detailed below
*/
the 424 DAV:response */
/* Lock-null related public lock functions */
/* 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 this provider */
/* ### maybe this should take a resource argument? */
const char * (*get_supportedlock)(void);
/* Parse a lock token URI, returning a lock token object allocated
* in the given pool.
*/
dav_error * (*parse_locktoken)(
pool *p,
const char *char_token,
);
/* Format a lock token object into a URI string, allocated in
* the given pool.
*
* Always returns non-NULL.
*/
const char * (*format_locktoken)(
pool *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,
);
/* Indicates completion of locking operations */
void (*close_lockdb)(
);
/* Take a resource out of the lock-null state. */
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.
*/
const dav_resource *resource,
/*
** 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.
*/
const dav_resource *resource,
int calltype,
#define DAV_GETLOCKS_RESOLVED 0 /* resolve indirects to directs */
/*
** 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
** lock structure will be filled out as a DAV_LOCKREC_INDIRECT.
*/
const dav_resource *resource,
const dav_locktoken *locktoken,
int partial_ok,
/*
** Quick test to see if the resource has *any* locks on it.
**
** This is typically used to determine if a non-existent resource
** has a lock and is (therefore) a locknull resource.
**
** WARNING: this function may return TRUE even when timed-out locks
** exist (i.e. it may not perform timeout checks).
*/
const dav_resource *resource,
int *locks_present);
/*
** Append the specified lock(s) to the set of locks on this resource.
**
** If "make_indirect" is true (non-zero), then the specified lock(s)
** should be converted to an indirect lock (if it is a direct lock)
** before appending. Note that the conversion to an indirect lock does
** not alter the passed-in lock -- the change is internal the
** append_locks function.
**
** Multiple locks are specified using the lock->next links.
*/
const dav_resource *resource,
int make_indirect,
/*
** Remove any lock that has the specified locktoken.
**
** If locktoken == NULL, then ALL locks are removed.
*/
const dav_resource *resource,
const dav_locktoken *locktoken);
/*
** Refresh all locks, found on the specified resource, which has a
** locktoken in the provided list.
**
** If the lock is indirect, then the direct lock is referenced and
** refreshed.
**
** Each lock that is updated is returned in the <locks> argument.
** Note that the locks will be fully resolved.
*/
const dav_resource *resource,
const dav_locktoken_list *ltl,
/*
** Look up the resource associated with a particular locktoken.
**
** The search begins at the specified <start_resource> and the lock
** specified by <locktoken>.
**
** lock will be looked up, and THAT resource will be returned. In other
** words, this function always returns the resource where a particular
** 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.
*/
const dav_locktoken *locktoken,
const dav_resource *start_resource,
const dav_resource **resource);
};
/* what types of resources can be discovered by dav_get_resource_state() */
/* --------------------------------------------------------------------
**
** PROPERTY HANDLING
*/
typedef struct dav_propdb dav_propdb;
request_rec *r,
int ro,
dav_propdb **propdb);
dav_propdb *db,
dav_xml_doc *doc);
dav_propdb *db,
int getvals);
/*
** 3-phase property modification.
**
** 1) validate props. readable? unlocked? ACLs allow access?
** 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
** 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
{
int operation;
/* ### add a GET? */
/* private items to the propdb */
int is_liveprop;
void *liveprop_ctx;
/* private to mod_dav.c */
request_rec *r;
} dav_prop_ctx;
/* --------------------------------------------------------------------
**
** WALKER STRUCTURE
*/
/* private, opaque info structure for repository walking context */
typedef struct dav_walker_private dav_walker_private;
/* directory tree walking context */
typedef struct dav_walker_ctx
{
int walk_type;
int postfix; /* call func for dirs after files */
request_rec *r; /* original request */
/* for PROPFIND operations */
int propfind_type;
#define DAV_PROPFIND_IS_ALLPROP 1
#define DAV_PROPFIND_IS_PROPNAME 2
#define DAV_PROPFIND_IS_PROP 3
/* for COPY and MOVE operations */
int is_move;
int skip_root; /* for dav_inherit_locks() */
int flags;
/* --------------------------------------------------------------------
**
** "STREAM" STRUCTURE
**
** mod_dav uses this abstraction for interacting with the repository
** 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 */
/* --------------------------------------------------------------------
**
** 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 is returned even if the resource does not exist.
* The return value should only be NULL for some kind of fatal error.
*
* The root_dir is the root of the directory for which this repository
* is configured.
* The workspace is the value of any Target-Selector header, or NULL
* if there is none.
*
* The provider may associate the request storage pool with the resource,
* to use in other operations on that resource.
*/
dav_resource * (*get_resource)(
request_rec *r,
const char *root_dir,
const char *workspace
);
/* 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.
*/
const dav_resource *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_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.
*/
/*
** 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.
*/
/*
** Write data to the stream.
**
** All of the bytes must be written, or an error should be returned.
*/
/*
** Seek to an absolute position in the stream. This is used to support
**
** NOTE: if this function is NULL (which is allowed), then any
** operations using Content-Range will be refused.
*/
/*
** 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.
*/
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)(
);
/* 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,
int depth,
);
/* 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)(
);
/* 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)(
);
/* Walk a resource hierarchy.
*
* Iterates over the resource hierarchy specified by wctx->resource.
* Parameter for control of the walk and the callback are specified
* by wctx.
*
* An HTTP_* status code is returned if an error occurs during the
* walk or the callback indicates an error. OK is returned on success.
*/
/* Get the entity tag for a resource */
};
/* --------------------------------------------------------------------
**
** VERSIONING FUNCTIONS
*/
/* dav_get_target_selector:
*
* Returns any Target-Selector header in a request
* (used by versioning clients)
*/
const char *dav_get_target_selector(request_rec *r);
/* 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 parent_resource and parent_was_writable arguments are optional
* (i.e. they may be NULL). If parent_only is set, then the
* resource_existed and resource_was_writable arguments are ignored.
*
* The previous states of the resources are returned, so they can be
* restored after the operation completes (see
* dav_revert_resource_writability())
*/
int parent_only,
int *resource_existed,
int *resource_was_writable,
int *parent_was_writable);
/* 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 and parent_resource arguments are optional
* (i.e. they may be NULL).
*/
int undo,
int resource_existed,
int parent_was_writable);
/* Versioning provider hooks */
struct dav_hooks_vsn
{
/* Return supported versioning level
* for the Versioning header
*/
const char * (*get_vsn_header)(void);
/* Create a new (empty) resource. If successful,
* the resource object state is updated appropriately.
*/
/* Checkout a resource. If successful, the resource
* object state is updated appropriately.
*/
/* Uncheckout a resource. If successful, the resource
* object state is updated appropriately.
*/
/* Checkin a working resource. If successful, the resource
* object state is updated appropriately.
*/
/* Determine whether a non-versioned (or non-existent) resource
* is versionable. Returns != 0 if resource can be versioned.
*/
/* Determine whether auto-versioning is enabled for a resource
* (which may not exist, or may not be versioned).
* Returns != 0 if auto-versioning is enabled.
*/
};
/* --------------------------------------------------------------------
**
** MISCELLANEOUS STUFF
*/
/* allow providers access to the per-directory parameters */
/* fetch the "LimitXMLRequestBody" in force for this resource */
/* manage an array of unique URIs: dav_insert_uri() and DAV_GET_URI_ITEM() */
/* return the URI's (existing) index, or insert it and return a new index */
#ifdef __cplusplus
}
#endif
#endif /* _MOD_DAV_H_ */