mod_dav.h revision 5a47cad1aef57039cd47eb34ebbc2959c610f326
/* -------------------------------------------------------------------- ** 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. 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 */ ** Create a new error structure. save_errno will be filled with the current ** Push a new error description onto the stack of errors. ** This function is used to provide an additional description to an existing ** <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 /* 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. /* -------------------------------------------------------------------- ** These are here for forward-declaration purposes. For more info, see ** the section title "HOOK HANDLING" for more information, plus each /* forward-declare this structure */ /* ### deprecated name */ /* -------------------------------------------------------------------- ** 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. ** Opaque, repository-specific information for a resource. /* 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. int exists;
/* 0 => null resource */ int collection;
/* 0 => file (if type == DAV_RESOURCE_TYPE_REGULAR) */ int working;
/* 0 => revision (if versioned) */ const char *
uri;
/* the URI for this 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. /* -------------------------------------------------------------------- ** 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 */ char *
buf;
/* buffer contents */ /* 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 */ /* -------------------------------------------------------------------- /* contains results from one of the getprop functions */ /* holds the contents of a <response> element */ const char *
href;
/* always */ const char *
desc;
/* optional description at <response> level */ /* use status if propresult.propstats is NULL. */ /* ### this stuff is private to dav/fs/repos.c; move it... */ /* format a time string (buf must be at least DAV_TIMEBUF_SIZE chars) */ /* -------------------------------------------------------------------- /* -------------------------------------------------------------------- ** Here is the definition of the If: header from RFC 2518, S9.4: ** If = "If" ":" (1*No-tag-list | 1*Tagged-list) ** Tagged-list = Resource 1*List ** 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 const char *
etag;
/* etag */ /* -------------------------------------------------------------------- ** LIVE PROPERTY HANDLING but nothing was inserted because the (live) property is not defined for this resource (it may be present as a dead inserted into the text block */ /* opaque type for PROPPATCH rollback information */ ** This URI is 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 this value (much like ** a Coded-URL); quotes and brackets should not be in the value. ** (of course, use your own domain to ensure a unique value) ** 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 a property name/value into a text block. The property to ** 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 ** Returns one of DAV_PROP_INSERT_* based on what happened. ** ### we may need more context... ie. the lock database ** Insert all known/defined property names (and values). This is ** 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). ** ### 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 ** 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 ** <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 ** The provider must set defer_to_dead to true (non-zero) or false. ** If true, then the set/remove is deferred to the dead property ** database. Note: it will be set to zero on entry. ** 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. */ /* -------------------------------------------------------------------- /* hook functions to enable pluggable databases */ ** Fetch the value from the database. If the value does not exist, ** then *pvalue should be zeroed. ** Note: it is NOT an error for the key/value pair to not exist. /* returns 1 if the record specified by "key" exists; 0 otherwise */ /* -------------------------------------------------------------------- /* Used to represent a Timeout header of "Infinity" */ ** Opaque, provider-specific information for a lock database. ** Opaque, provider-specific information for a lock record. ** 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. int ro;
/* was it opened readonly? */ ** 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 ** 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 ** ### hrm. that says the abstraction is wrong. is_locknull may disappear. 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 */ /* Property-related public lock functions */ /* LockDB-related public lock functions */ ** 0x0F -- reserved for <dav_lock_scope> values ** other flags, detailed below /* Lock-null related public lock functions */ /* Lock provider hooks. Locking is optional, so there may be no * lock provider for a given repository. /* Return the supportedlock property for this provider */ /* ### maybe this should take a resource argument? */ /* Parse a lock token URI, returning a lock token object allocated /* Format a lock token object into a URI string, allocated in * Always returns non-NULL. /* Compare two lock tokens. * Result < 0 => lt1 < lt2 * Result == 0 => lt1 == lt2 * Result > 0 => lt1 > 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 * If force != 0, locking operations will definitely occur. /* Indicates completion of locking operations */ /* Take a resource out of the lock-null state. */ ** Create a (direct) lock structure for the given resource. A locktoken ** The lock provider may store private information into lock->info. ** 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. ** 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. ** 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). ** 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. ** Remove any lock that has the specified locktoken. ** If locktoken == NULL, then ALL locks are removed. ** 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 ** Each lock that is updated is returned in the <locks> argument. ** Note that the locks will be fully resolved. ** Look up the resource associated with a particular locktoken. ** The search begins at the specified <start_resource> and the lock ** specified by <locktoken>. ** If the resource/token specifies an indirect lock, then the direct ** 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. /* what types of resources can be discovered by dav_get_resource_state() */ /* -------------------------------------------------------------------- ** 3-phase property modification. ** 1) validate props. readable? unlocked? ACLs allow access? ** ### 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() 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 ** 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. /* private items to the propdb */ /* -------------------------------------------------------------------- /* private, opaque info structure for repository walking context */ /* directory tree walking context */ int postfix;
/* call func for dirs after files */ /* for PROPFIND operations */ /* for COPY and MOVE operations */ /* -------------------------------------------------------------------- ** mod_dav uses this abstraction for interacting with the repository ** Note that the structure is opaque -- it is private to the repository ** that created the stream in the repository's "open" function. /* -------------------------------------------------------------------- /* Repository provider hooks */ /* 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. /* 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 * The workspace is the value of any Target-Selector header, or NULL * The provider may associate the request storage pool with the resource, * to use in other operations on that 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. /* Determine whether two resource descriptors refer to the same resource. * Result != 0 => the resources are the same. /* Determine whether one resource is a parent (immediate or otherwise) * Result != 0 => res1 is a parent of res2. ** Open a stream for this resource, using the specified mode. The ** stream will be returned in *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 ** commit should be TRUE (non-zero) or FALSE (0) if the stream was ** opened for writing. This flag states whether to retain the file ** 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 ** Content-Range in a GET/PUT. ** 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 ** It may be NULL if get_pathname is provided. /* 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 * Returns NULL if the file could not be made accessible. /* Free any temporary storage associated with a file made accessible by /* 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 /* 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. /* 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 /* 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. /* Walk a resource hierarchy. * Iterates over the resource hierarchy specified by wctx->resource. * Parameter for control of the walk and the callback are specified * 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 */ /* -------------------------------------------------------------------- /* dav_get_target_selector: * If a DAV:version element is provided, then it is assumed to provide the * target version. If no element is provided (version==NULL), then the * request headers are examined for a Target-Selector header. * The target version, if any, is then returned. * (used by versioning clients) /* 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 * 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()) /* 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). ** This structure is used to describe available reports ** "namespace" should be valid XML and URL-quoted. mod_dav will place ** double-quotes around it and use it in an xmlns declaration. const char *
namespace;
/* namespace of the XML report element */ const char *
name;
/* element name for the XML report */ /* Versioning provider hooks */ /* Return supported versioning level * for the Versioning header /* 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. * The location of the working resource should be returned in *location. /* 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. ** Return the set of reports available at this resource. ** An array of report elements should be returned, with an end-marker ** element containing namespace==NULL. The report response will be ** constructed and returned. ** DAV:available-report should not be returned; the mod_dav core will /* -------------------------------------------------------------------- /* allow providers access to the per-directory parameters */ /* fetch the "LimitXMLRequestBody" in force for this resource */ int propid;
/* live property ID */