granicus.if.org Git - apache/blob - modules/dav/main/mod_dav.h

   1 /* ====================================================================
   2  * The Apache Software License, Version 1.1
   3  *
   4  * Copyright (c) 2000 The Apache Software Foundation.  All rights
   5  * reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  *
  11  * 1. Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  *
  14  * 2. Redistributions in binary form must reproduce the above copyright
  15  *    notice, this list of conditions and the following disclaimer in
  16  *    the documentation and/or other materials provided with the
  17  *    distribution.
  18  *
  19  * 3. The end-user documentation included with the redistribution,
  20  *    if any, must include the following acknowledgment:
  21  *       "This product includes software developed by the
  22  *        Apache Software Foundation (http://www.apache.org/)."
  23  *    Alternately, this acknowledgment may appear in the software itself,
  24  *    if and wherever such third-party acknowledgments normally appear.
  25  *
  26  * 4. The names "Apache" and "Apache Software Foundation" must
  27  *    not be used to endorse or promote products derived from this
  28  *    software without prior written permission. For written
  29  *    permission, please contact apache@apache.org.
  30  *
  31  * 5. Products derived from this software may not be called "Apache",
  32  *    nor may "Apache" appear in their name, without prior written
  33  *    permission of the Apache Software Foundation.
  34  *
  35  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46  * SUCH DAMAGE.
  47  * ====================================================================
  48  *
  49  * This software consists of voluntary contributions made by many
  50  * individuals on behalf of the Apache Software Foundation.  For more
  51  * information on the Apache Software Foundation, please see
  52  * <http://www.apache.org/>.
  53  */
  54
  55 /*
  56 ** DAV extension module for Apache 2.0.*
  57 */
  58
  59 #ifndef _MOD_DAV_H_
  60 #define _MOD_DAV_H_
  61
  62 #include "httpd.h"
  63 #include "util_xml.h"
  64 #include "apr_hooks.h"
  65 #include "apr_hash.h"
  66 #include "apr_dbm.h"
  67
  68 #include <limits.h>     /* for INT_MAX */
  69
  70 #ifdef __cplusplus
  71 extern "C" {
  72 #endif
  73
  74
  75 #define DAV_VERSION             AP_SERVER_BASEREVISION
  76
  77 #define DAV_XML_HEADER          "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
  78 #define DAV_XML_CONTENT_TYPE    "text/xml; charset=\"utf-8\""
  79
  80 #define DAV_READ_BLOCKSIZE      2048    /* used for reading input blocks */
  81
  82 #define DAV_RESPONSE_BODY_1     "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<HTML><HEAD>\n<TITLE>"
  83 #define DAV_RESPONSE_BODY_2     "</TITLE>\n</HEAD><BODY>\n<H1>"
  84 #define DAV_RESPONSE_BODY_3     "</H1>\n"
  85 #define DAV_RESPONSE_BODY_4     "</BODY></HTML>\n"
  86
  87 #define DAV_DO_COPY             0
  88 #define DAV_DO_MOVE             1
  89
  90
  91 #if 1
  92 #define DAV_DEBUG 1
  93 #define DEBUG_CR        "\n"
  94 #define DBG0(f)         ap_log_error(APLOG_MARK, \
  95                                 APLOG_ERR|APLOG_NOERRNO, 0, NULL, (f))
  96 #define DBG1(f,a1)      ap_log_error(APLOG_MARK, \
  97                                 APLOG_ERR|APLOG_NOERRNO, 0, NULL, f, a1)
  98 #define DBG2(f,a1,a2)   ap_log_error(APLOG_MARK, \
  99                                 APLOG_ERR|APLOG_NOERRNO, 0, NULL, f, a1, a2)
 100 #define DBG3(f,a1,a2,a3) ap_log_error(APLOG_MARK, \
 101                                APLOG_ERR|APLOG_NOERRNO, 0, NULL, f, a1, a2, a3)
 102 #else
 103 #undef DAV_DEBUG
 104 #define DEBUG_CR        ""
 105 #endif
 106
 107 #define DAV_INFINITY    INT_MAX /* for the Depth: header */
 108
 109 /* Create a set of DAV_DECLARE(type), DAV_DECLARE_NONSTD(type) and
 110  * DAV_DECLARE_DATA with appropriate export and import tags for the platform
 111  */
 112 #if !defined(WIN32)
 113 #define DAV_DECLARE(type)            type
 114 #define DAV_DECLARE_NONSTD(type)     type
 115 #define DAV_DECLARE_DATA
 116 #elif defined(DAV_DECLARE_STATIC)
 117 #define DAV_DECLARE(type)            type __stdcall
 118 #define DAV_DECLARE_NONSTD(type)     type
 119 #define DAV_DECLARE_DATA
 120 #elif defined(DAV_DECLARE_EXPORT)
 121 #define DAV_DECLARE(type)            __declspec(dllexport) type __stdcall
 122 #define DAV_DECLARE_NONSTD(type)     __declspec(dllexport) type
 123 #define DAV_DECLARE_DATA             __declspec(dllexport)
 124 #else
 125 #define DAV_DECLARE(type)            __declspec(dllimport) type __stdcall
 126 #define DAV_DECLARE_NONSTD(type)     __declspec(dllimport) type
 127 #define DAV_DECLARE_DATA             __declspec(dllimport)
 128 #endif
 129
 130 /* --------------------------------------------------------------------
 131 **
 132 ** ERROR MANAGEMENT
 133 */
 134
 135 /*
 136 ** dav_error structure.
 137 **
 138 ** In most cases, mod_dav uses a pointer to a dav_error structure. If the
 139 ** pointer is NULL, then no error has occurred.
 140 **
 141 ** In certain cases, a dav_error structure is directly used. In these cases,
 142 ** a status value of 0 means that an error has not occurred.
 143 **
 144 ** Note: this implies that status != 0 whenever an error occurs.
 145 **
 146 ** The desc field is optional (it may be NULL). When NULL, it typically
 147 ** implies that Apache has a proper description for the specified status.
 148 */
 149 typedef struct dav_error {
 150     int status;                 /* suggested HTTP status (0 for no error) */
 151     int error_id;               /* DAV-specific error ID */
 152     const char *desc;           /* DAV:responsedescription and error log */
 153
 154     int save_errno;             /* copy of errno causing the error */
 155
 156     struct dav_error *prev;     /* previous error (in stack) */
 157
 158     /* deferred computation of the description */
 159     void (*compute_desc)(struct dav_error *err, apr_pool_t *p);
 160     int ctx_i;
 161     const char *ctx_s;
 162     void *ctx_p;
 163
 164 } dav_error;
 165
 166 /*
 167 ** Create a new error structure. save_errno will be filled with the current
 168 ** errno value.
 169 */
 170 DAV_DECLARE(dav_error*) dav_new_error(apr_pool_t *p, int status,
 171                                       int error_id, const char *desc);
 172
 173 /*
 174 ** Push a new error description onto the stack of errors.
 175 **
 176 ** This function is used to provide an additional description to an existing
 177 ** error.
 178 **
 179 ** <status> should contain the caller's view of what the current status is,
 180 ** given the underlying error. If it doesn't have a better idea, then the
 181 ** caller should pass prev->status.
 182 **
 183 ** <error_id> can specify a new error_id since the topmost description has
 184 ** changed.
 185 */
 186 DAV_DECLARE(dav_error*) dav_push_error(apr_pool_t *p, int status, int error_id,
 187                                        const char *desc, dav_error *prev);
 188
 189
 190 /* error ID values... */
 191
 192 /* IF: header errors */
 193 #define DAV_ERR_IF_PARSE                100     /* general parsing error */
 194 #define DAV_ERR_IF_MULTIPLE_NOT         101     /* multiple "Not" found */
 195 #define DAV_ERR_IF_UNK_CHAR             102     /* unknown char in header */
 196 #define DAV_ERR_IF_ABSENT               103     /* no locktokens given */
 197 #define DAV_ERR_IF_TAGGED               104     /* in parsing tagged-list */
 198 #define DAV_ERR_IF_UNCLOSED_PAREN       105     /* in no-tagged-list */
 199
 200 /* Prop DB errors */
 201 #define DAV_ERR_PROP_BAD_MAJOR          200     /* major version was wrong */
 202 #define DAV_ERR_PROP_READONLY           201     /* prop is read-only */
 203 #define DAV_ERR_PROP_NO_DATABASE        202     /* writable db not avail */
 204 #define DAV_ERR_PROP_NOT_FOUND          203     /* prop not found */
 205 #define DAV_ERR_PROP_BAD_LOCKDB         204     /* could not open lockdb */
 206 #define DAV_ERR_PROP_OPENING            205     /* problem opening propdb */
 207 #define DAV_ERR_PROP_EXEC               206     /* problem exec'ing patch */
 208
 209 /* Predefined DB errors */
 210 /* ### any to define?? */
 211
 212 /* Predefined locking system errors */
 213 #define DAV_ERR_LOCK_OPENDB             400     /* could not open lockdb */
 214 #define DAV_ERR_LOCK_NO_DB              401     /* no database defined */
 215 #define DAV_ERR_LOCK_CORRUPT_DB         402     /* DB is corrupt */
 216 #define DAV_ERR_LOCK_UNK_STATE_TOKEN    403     /* unknown State-token */
 217 #define DAV_ERR_LOCK_PARSE_TOKEN        404     /* bad opaquelocktoken */
 218 #define DAV_ERR_LOCK_SAVE_LOCK          405     /* err saving locks */
 219
 220 /*
 221 ** Some comments on Error ID values:
 222 **
 223 ** The numbers do not necessarily need to be unique. Uniqueness simply means
 224 ** that two errors that have not been predefined above can be distinguished
 225 ** from each other. At the moment, mod_dav does not use this distinguishing
 226 ** feature, but it could be used in the future to collapse <response> elements
 227 ** into groups based on the error ID (and associated responsedescription).
 228 **
 229 ** If a compute_desc is provided, then the error ID should be unique within
 230 ** the context of the compute_desc function (so the function can figure out
 231 ** what to filled into the desc).
 232 **
 233 ** Basically, subsystems can ignore defining new error ID values if they want
 234 ** to. The subsystems *do* need to return the predefined errors when
 235 ** appropriate, so that mod_dav can figure out what to do. Subsystems can
 236 ** simply leave the error ID field unfilled (zero) if there isn't an error
 237 ** that must be placed there.
 238 */
 239
 240
 241 /* --------------------------------------------------------------------
 242 **
 243 ** HOOK STRUCTURES
 244 **
 245 ** These are here for forward-declaration purposes. For more info, see
 246 ** the section title "HOOK HANDLING" for more information, plus each
 247 ** structure definition.
 248 */
 249
 250 /* forward-declare this structure */
 251 typedef struct dav_hooks_propdb dav_hooks_propdb;
 252 typedef struct dav_hooks_locks dav_hooks_locks;
 253 typedef struct dav_hooks_vsn dav_hooks_vsn;
 254 typedef struct dav_hooks_repository dav_hooks_repository;
 255 typedef struct dav_hooks_liveprop dav_hooks_liveprop;
 256 typedef struct dav_hooks_binding dav_hooks_binding;
 257
 258 /* ### deprecated name */
 259 typedef dav_hooks_propdb dav_hooks_db;
 260
 261
 262 /* --------------------------------------------------------------------
 263 **
 264 ** RESOURCE HANDLING
 265 */
 266
 267 /*
 268 ** Resource Types:
 269 ** The base protocol defines only file and collection resources.
 270 ** The versioning protocol defines several additional resource types
 271 ** to represent artifacts of a version control system.
 272 **
 273 ** This enumeration identifies the type of URL used to identify the
 274 ** resource. Since the same resource may have more than one type of
 275 ** URL which can identify it, dav_resource_type cannot be used
 276 ** alone to determine the type of the resource; attributes of the
 277 ** dav_resource object must also be consulted.
 278 */
 279 typedef enum {
 280     DAV_RESOURCE_TYPE_UNKNOWN,
 281
 282     DAV_RESOURCE_TYPE_REGULAR,          /* file or collection; could be
 283                                          * unversioned, or version selector,
 284                                          * or baseline selector */
 285
 286     DAV_RESOURCE_TYPE_VERSION,          /* version or baseline URL */
 287
 288     DAV_RESOURCE_TYPE_HISTORY,          /* version or baseline history URL */
 289
 290     DAV_RESOURCE_TYPE_WORKING,          /* working resource URL */
 291
 292     DAV_RESOURCE_TYPE_WORKSPACE,        /* workspace URL */
 293
 294     DAV_RESOURCE_TYPE_ACTIVITY,         /* activity URL */
 295
 296     DAV_RESOURCE_TYPE_PRIVATE           /* repository-private type */
 297
 298 } dav_resource_type;
 299
 300 /*
 301 ** Opaque, repository-specific information for a resource.
 302 */
 303 typedef struct dav_resource_private dav_resource_private;
 304
 305 /*
 306 ** Resource descriptor, generated by a repository provider.
 307 **
 308 ** Note: the lock-null state is not explicitly represented here,
 309 ** since it may be expensive to compute. Use dav_get_resource_state()
 310 ** to determine whether a non-existent resource is a lock-null resource.
 311 **
 312 ** A quick explanation of how the flags can apply to different resources:
 313 **
 314 ** unversioned file or collection:
 315 **     type       = DAV_RESOURCE_TYPE_REGULAR
 316 **     exists     = ? (1 if exists)
 317 **     collection = ? (1 if collection)
 318 **     versioned  = 0
 319 **     baselined  = 0
 320 **     working    = 0
 321 **
 322 ** version/baseline selector:
 323 **     type       = DAV_RESOURCE_TYPE_REGULAR
 324 **     exists     = 1
 325 **     collection = ? (1 if collection)
 326 **     versioned  = 1
 327 **     baselined  = ? (1 if baseline selector)
 328 **     working    = ? (1 if checked out)
 329 **
 330 ** version/baseline history:
 331 **     type       = DAV_RESOURCE_TYPE_HISTORY
 332 **     exists     = 1
 333 **     collection = 0
 334 **     versioned  = 0
 335 **     baselined  = 0
 336 **     working    = 0
 337 **
 338 ** version/baseline:
 339 **     type       = DAV_RESOURCE_TYPE_VERSION
 340 **     exists     = 1
 341 **     collection = ? (1 if collection)
 342 **     versioned  = 1
 343 **     baselined  = ? (1 if baseline)
 344 **     working    = 0
 345 **
 346 ** working resource:
 347 **     type       = DAV_RESOURCE_TYPE_WORKING
 348 **     exists     = 1
 349 **     collection = ? (1 if collection)
 350 **     versioned  = 1
 351 **     baselined  = 0
 352 **     working    = 1
 353 **
 354 ** workspace:
 355 **     type       = DAV_RESOURCE_TYPE_WORKSPACE
 356 **     exists     = ? (1 if exists)
 357 **     collection = 1
 358 **     versioned  = * (jvasta: I'm seeking clarification on whether a
 359 **     baselined  = *  workspace can be versioned or baselined)
 360 **     working    = *
 361 **
 362 ** activity:
 363 **     type       = DAV_RESOURCE_TYPE_ACTIVITY
 364 **     exists     = ? (1 if exists)
 365 **     collection = 0
 366 **     versioned  = 0
 367 **     baselined  = 0
 368 **     working    = 0
 369 */
 370 typedef struct dav_resource {
 371     dav_resource_type type;
 372
 373     int exists;         /* 0 => null resource */
 374
 375     int collection;     /* 0 => file; can be 1 for
 376                          * REGULAR, VERSION, and WORKING resources,
 377                          * and is always 1 for WORKSPACE */
 378
 379     int versioned;      /* 0 => unversioned; can be 1 for
 380                          * REGULAR and WORKSPACE resources,
 381                          * and is always 1 for VERSION and WORKING */
 382
 383     int baselined;      /* 0 => not baselined; can be 1 for
 384                          * REGULAR and VERSION resources;
 385                          * versioned == 1 when baselined == 1 */
 386
 387     int working;        /* 0 => not checked out; can be 1 for
 388                          * REGULAR and WORKSPACE resources,
 389                          * and is always 1 for WORKING */
 390
 391     const char *uri;    /* the URI for this resource */
 392
 393     dav_resource_private *info;         /* the provider's private info */
 394
 395     const dav_hooks_repository *hooks;  /* hooks used for this resource */
 396
 397     /* When allocating items related specifically to this resource, the
 398        following pool should be used. Its lifetime will be at least as
 399        long as the dav_resource structure. */
 400     apr_pool_t *pool;
 401
 402 } dav_resource;
 403
 404 /*
 405 ** Lock token type. Lock providers define the details of a lock token.
 406 ** However, all providers are expected to at least be able to parse
 407 ** the "opaquelocktoken" scheme, which is represented by a uuid_t.
 408 */
 409 typedef struct dav_locktoken dav_locktoken;
 410
 411
 412 /* --------------------------------------------------------------------
 413 **
 414 ** BUFFER HANDLING
 415 **
 416 ** These buffers are used as a lightweight buffer reuse mechanism. Apache
 417 ** provides sub-pool creation and destruction to much the same effect, but
 418 ** the sub-pools are a bit more general and heavyweight than these buffers.
 419 */
 420
 421 /* buffer for reuse; can grow to accomodate needed size */
 422 typedef struct
 423 {
 424     apr_size_t alloc_len;       /* how much has been allocated */
 425     apr_size_t cur_len;         /* how much is currently being used */
 426     char *buf;                  /* buffer contents */
 427 } dav_buffer;
 428 #define DAV_BUFFER_MINSIZE      256     /* minimum size for buffer */
 429 #define DAV_BUFFER_PAD          64      /* amount of pad when growing */
 430
 431 /* set the cur_len to the given size and ensure space is available */
 432 DAV_DECLARE(void) dav_set_bufsize(apr_pool_t *p, dav_buffer *pbuf,
 433                                   apr_size_t size);
 434
 435 /* initialize a buffer and copy the specified (null-term'd) string into it */
 436 DAV_DECLARE(void) dav_buffer_init(apr_pool_t *p, dav_buffer *pbuf,
 437                                   const char *str);
 438
 439 /* check that the buffer can accomodate <extra_needed> more bytes */
 440 DAV_DECLARE(void) dav_check_bufsize(apr_pool_t *p, dav_buffer *pbuf,
 441                                     apr_size_t extra_needed);
 442
 443 /* append a string to the end of the buffer, adjust length */
 444 DAV_DECLARE(void) dav_buffer_append(apr_pool_t *p, dav_buffer *pbuf,
 445                                     const char *str);
 446
 447 /* place a string on the end of the buffer, do NOT adjust length */
 448 DAV_DECLARE(void) dav_buffer_place(apr_pool_t *p, dav_buffer *pbuf,
 449                                    const char *str);
 450
 451 /* place some memory on the end of a buffer; do NOT adjust length */
 452 DAV_DECLARE(void) dav_buffer_place_mem(apr_pool_t *p, dav_buffer *pbuf,
 453                                        const void *mem, apr_size_t amt,
 454                                        apr_size_t pad);
 455
 456
 457 /* --------------------------------------------------------------------
 458 **
 459 ** HANDY UTILITIES
 460 */
 461
 462 /* contains results from one of the getprop functions */
 463 typedef struct
 464 {
 465     ap_text * propstats;        /* <propstat> element text */
 466     ap_text * xmlns;            /* namespace decls for <response> elem */
 467 } dav_get_props_result;
 468
 469 /* holds the contents of a <response> element */
 470 typedef struct dav_response
 471 {
 472     const char *href;           /* always */
 473     const char *desc;           /* optional description at <response> level */
 474
 475     /* use status if propresult.propstats is NULL. */
 476     dav_get_props_result propresult;
 477
 478     int status;
 479
 480     struct dav_response *next;
 481 } dav_response;
 482
 483 typedef struct
 484 {
 485     request_rec *rnew;          /* new subrequest */
 486     dav_error err;              /* potential error response */
 487 } dav_lookup_result;
 488
 489
 490 dav_lookup_result dav_lookup_uri(const char *uri, request_rec *r);
 491
 492 /* ### this stuff is private to dav/fs/repos.c; move it... */
 493 /* format a time string (buf must be at least DAV_TIMEBUF_SIZE chars) */
 494 #define DAV_STYLE_ISO8601       1
 495 #define DAV_STYLE_RFC822        2
 496 #define DAV_TIMEBUF_SIZE        30
 497
 498 int dav_get_depth(request_rec *r, int def_depth);
 499
 500 int dav_validate_root(const ap_xml_doc *doc, const char *tagname);
 501 ap_xml_elem *dav_find_child(const ap_xml_elem *elem, const char *tagname);
 502
 503
 504 /* --------------------------------------------------------------------
 505 **
 506 ** DAV PLUGINS
 507 */
 508
 509 /* ### docco ... */
 510
 511 /*
 512 ** dav_provider
 513 **
 514 ** This structure wraps up all of the hooks that a mod_dav provider can
 515 ** supply. The provider MUST supply <repos> and <propdb>. The rest are
 516 ** optional and should contain NULL if that feature is not supplied.
 517 **
 518 ** Note that a provider cannot pick and choose portions. There are too many
 519 ** dependencies between a dav_resource (defined by <repos>) and the other
 520 ** functionality.
 521 **
 522 ** Live properties are not part of the dav_provider structure because they
 523 ** are handled through the APR_HOOK interface (to allow for multiple liveprop
 524 ** providers). The core always provides some properties, and then a given
 525 ** provider will add more properties.
 526 */
 527 typedef struct {
 528     const dav_hooks_repository *repos;
 529     const dav_hooks_propdb *propdb;
 530     const dav_hooks_locks *locks;
 531     const dav_hooks_vsn *vsn;
 532     const dav_hooks_binding *binding;
 533
 534 } dav_provider;
 535
 536 /*
 537 ** gather_propsets: gather all live property propset-URIs
 538 **
 539 ** The hook implementor should push one or more URIs into the specified
 540 ** array. These URIs are returned in the DAV: header to let clients know
 541 ** what sets of live properties are supported by the installation. mod_dav
 542 ** will place open/close angle brackets around each value (much like
 543 ** a Coded-URL); quotes and brackets should not be in the value.
 544 **
 545 ** Example:    http://apache.org/dav/props/
 546 **
 547 ** (of course, use your own domain to ensure a unique value)
 548 */
 549 APR_DECLARE_EXTERNAL_HOOK(dav, DAV, void, gather_propsets,
 550                          (apr_array_header_t *uris))
 551
 552 /*
 553 ** find_liveprop: find a live property, returning a non-zero, unique,
 554 **                opaque identifier.
 555 **
 556 ** If the hook implementor determines the specified URI/name refers to
 557 ** one of its properties, then it should fill in HOOKS and return a
 558 ** non-zero value. The returned value is the "property ID" and will
 559 ** be passed to the various liveprop hook functions.
 560 **
 561 ** Return 0 if the property is not defined by the hook implementor.
 562 */
 563 APR_DECLARE_EXTERNAL_HOOK(dav, DAV, int, find_liveprop,
 564                          (const dav_resource *resource,
 565                           const char *ns_uri, const char *name,
 566                           const dav_hooks_liveprop **hooks))
 567
 568 /*
 569 ** insert_all_liveprops: insert all (known) live property names/values.
 570 **
 571 ** The hook implementor should append XML text to PHDR, containing liveprop
 572 ** names. If INSVALUE is true, then the property values should also be
 573 ** inserted into the output XML stream.
 574 **
 575 ** The liveprop provider should insert *all* known and *defined* live
 576 ** properties on the specified resource. If a particular liveprop is
 577 ** not defined for this resource, then it should not be inserted.
 578 */
 579 APR_DECLARE_EXTERNAL_HOOK(dav, DAV, void, insert_all_liveprops,
 580                          (request_rec *r, const dav_resource *resource,
 581                           int insvalue, ap_text_header *phdr))
 582
 583 /* ### make this internal to mod_dav.c ? */
 584 #define DAV_KEY_RESOURCE        "dav-resource"
 585
 586 const dav_hooks_locks *dav_get_lock_hooks(request_rec *r);
 587 const dav_hooks_propdb *dav_get_propdb_hooks(request_rec *r);
 588 const dav_hooks_vsn *dav_get_vsn_hooks(request_rec *r);
 589 const dav_hooks_binding *dav_get_binding_hooks(request_rec *r);
 590
 591 DAV_DECLARE(void) dav_register_provider(apr_pool_t *p, const char *name,
 592                                         const dav_provider *hooks);
 593 const dav_provider * dav_lookup_provider(const char *name);
 594
 595
 596 /* ### deprecated */
 597 #define DAV_GET_HOOKS_PROPDB(r)         dav_get_propdb_hooks(r)
 598 #define DAV_GET_HOOKS_LOCKS(r)          dav_get_lock_hooks(r)
 599 #define DAV_GET_HOOKS_VSN(r)            dav_get_vsn_hooks(r)
 600 #define DAV_GET_HOOKS_BINDING(r)        dav_get_binding_hooks(r)
 601
 602
 603 /* --------------------------------------------------------------------
 604 **
 605 ** IF HEADER PROCESSING
 606 **
 607 ** Here is the definition of the If: header from RFC 2518, S9.4:
 608 **
 609 **    If = "If" ":" (1*No-tag-list | 1*Tagged-list)
 610 **    No-tag-list = List
 611 **    Tagged-list = Resource 1*List
 612 **    Resource = Coded-URL
 613 **    List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")"
 614 **    State-token = Coded-URL
 615 **    Coded-URL = "<" absoluteURI ">"        ; absoluteURI from RFC 2616
 616 **
 617 ** List corresponds to dav_if_state_list. No-tag-list corresponds to
 618 ** dav_if_header with uri==NULL. Tagged-list corresponds to a sequence of
 619 ** dav_if_header structures with (duplicate) uri==Resource -- one
 620 ** dav_if_header per state_list. A second Tagged-list will start a new
 621 ** sequence of dav_if_header structures with the new URI.
 622 **
 623 ** A summary of the semantics, mapped into our structures:
 624 **    - Chained dav_if_headers: OR
 625 **    - Chained dav_if_state_lists: AND
 626 **    - NULL uri matches all resources
 627 */
 628
 629 typedef enum
 630 {
 631     dav_if_etag,
 632     dav_if_opaquelock
 633 } dav_if_state_type;
 634
 635 typedef struct dav_if_state_list
 636 {
 637     dav_if_state_type type;
 638
 639     int condition;
 640 #define DAV_IF_COND_NORMAL      0
 641 #define DAV_IF_COND_NOT         1       /* "Not" was applied */
 642
 643     const char *etag;   /* etag */
 644     dav_locktoken *locktoken;   /* locktoken */
 645
 646     struct dav_if_state_list *next;
 647 } dav_if_state_list;
 648
 649 typedef struct dav_if_header
 650 {
 651     const char *uri;
 652     apr_size_t uri_len;
 653     struct dav_if_state_list *state;
 654     struct dav_if_header *next;
 655
 656     int dummy_header;   /* used internally by the lock/etag validation */
 657 } dav_if_header;
 658
 659 typedef struct dav_locktoken_list
 660 {
 661     dav_locktoken *locktoken;
 662     struct dav_locktoken_list *next;
 663 } dav_locktoken_list;
 664
 665 dav_error * dav_get_locktoken_list(request_rec *r, dav_locktoken_list **ltl);
 666
 667
 668 /* --------------------------------------------------------------------
 669 **
 670 ** LIVE PROPERTY HANDLING
 671 */
 672
 673 typedef enum {
 674     DAV_PROP_INSERT_NOTDEF,     /* property is defined by this provider,
 675                                    but nothing was inserted because the
 676                                    (live) property is not defined for this
 677                                    resource (it may be present as a dead
 678                                    property). */
 679     DAV_PROP_INSERT_NAME,       /* a property name (empty elem) was
 680                                    inserted into the text block */
 681     DAV_PROP_INSERT_VALUE       /* a property name/value pair was inserted
 682                                    into the text block */
 683 } dav_prop_insert;
 684
 685 /* opaque type for PROPPATCH rollback information */
 686 typedef struct dav_liveprop_rollback dav_liveprop_rollback;
 687
 688 struct dav_hooks_liveprop
 689 {
 690     /*
 691     ** Insert a property name/value into a text block. The property to
 692     ** insert is identified by the propid value. If insvalue is true,
 693     ** then the property's value should be inserted; otherwise, an empty
 694     ** element (ie. just the prop's name) should be inserted.
 695     **
 696     ** Returns one of DAV_PROP_INSERT_* based on what happened.
 697     **
 698     ** ### we may need more context... ie. the lock database
 699     */
 700     dav_prop_insert (*insert_prop)(const dav_resource *resource,
 701                                    int propid, int insvalue,
 702                                    ap_text_header *phdr);
 703
 704     /*
 705     ** Determine whether a given property is writable.
 706     **
 707     ** ### we may want a different semantic. i.e. maybe it should be
 708     ** ### "can we write <value> into this property?"
 709     **
 710     ** Returns 1 if the live property can be written, 0 if read-only.
 711     */
 712     int (*is_writable)(const dav_resource *resource, int propid);
 713
 714     /*
 715     ** This member defines the set of namespace URIs that the provider
 716     ** uses for its properties. When insert_all is called, it will be
 717     ** passed a list of integers that map from indices into this list
 718     ** to namespace IDs for output generation.
 719     **
 720     ** The last entry in this list should be a NULL value (sentinel).
 721     */
 722     const char * const * namespace_uris;
 723
 724     /*
 725     ** ### this is not the final design. we want an open-ended way for
 726     ** ### liveprop providers to attach *new* properties. To this end,
 727     ** ### we'll have a "give me a list of the props you define", a way
 728     ** ### to check for a prop's existence, a way to validate a set/remove
 729     ** ### of a prop, and a way to execute/commit/rollback that change.
 730     */
 731
 732     /*
 733     ** Validate that the live property can be assigned a value, and that
 734     ** the provided value is valid.
 735     **
 736     ** elem will point to the XML element that names the property. For
 737     ** example:
 738     **     <lp1:executable>T</lp1:executable>
 739     **
 740     ** The provider can access the cdata fields and the child elements
 741     ** to extract the relevant pieces.
 742     **
 743     ** operation is one of DAV_PROP_OP_SET or _DELETE.
 744     **
 745     ** The provider may return a value in *context which will be passed
 746     ** to each of the exec/commit/rollback functions. For example, this
 747     ** may contain an internal value which has been processed from the
 748     ** input element.
 749     **
 750     ** The provider must set defer_to_dead to true (non-zero) or false.
 751     ** If true, then the set/remove is deferred to the dead property
 752     ** database. Note: it will be set to zero on entry.
 753     */
 754     dav_error * (*patch_validate)(const dav_resource *resource,
 755                                   const ap_xml_elem *elem,
 756                                   int operation,
 757                                   void **context,
 758                                   int *defer_to_dead);
 759
 760     /* ### doc... */
 761     dav_error * (*patch_exec)(dav_resource *resource,
 762                               const ap_xml_elem *elem,
 763                               int operation,
 764                               void *context,
 765                               dav_liveprop_rollback **rollback_ctx);
 766
 767     /* ### doc... */
 768     void (*patch_commit)(dav_resource *resource,
 769                          int operation,
 770                          void *context,
 771                          dav_liveprop_rollback *rollback_ctx);
 772
 773     /* ### doc... */
 774     dav_error * (*patch_rollback)(dav_resource *resource,
 775                                   int operation,
 776                                   void *context,
 777                                   dav_liveprop_rollback *rollback_ctx);
 778 };
 779
 780 /*
 781 ** dav_liveprop_spec: specify a live property
 782 **
 783 ** This structure is used as a standard way to determine if a particular
 784 ** property is a live property. Its use is not part of the mandated liveprop
 785 ** interface, but can be used by liveprop providers in conjuction with the
 786 ** utility routines below.
 787 */
 788 typedef struct {
 789     int ns;             /* provider-local namespace index */
 790     const char *name;   /* name of the property */
 791
 792     int propid;         /* provider-local property ID */
 793
 794     int is_writable;    /* is the property writable? */
 795
 796 } dav_liveprop_spec;
 797
 798 /*
 799 ** dav_liveprop_group: specify a group of liveprops
 800 **
 801 ** This structure specifies a group of live properties, their namespaces,
 802 ** and how to handle them.
 803 */
 804 typedef struct {
 805     const dav_liveprop_spec *specs;
 806     const char * const *namespace_uris;
 807     const dav_hooks_liveprop *hooks;
 808
 809 } dav_liveprop_group;
 810
 811 /* ### docco */
 812 DAV_DECLARE(int) dav_do_find_liveprop(const char *ns_uri, const char *name,
 813                                       const dav_liveprop_group *group,
 814                                       const dav_hooks_liveprop **hooks);
 815
 816 /* ### docco */
 817 DAV_DECLARE(int) dav_get_liveprop_info(int propid,
 818                                        const dav_liveprop_group *group,
 819                                        const dav_liveprop_spec **info);
 820
 821 /* ### docco */
 822 DAV_DECLARE(void) dav_register_liveprop_group(apr_pool_t *pool,
 823                                               const dav_liveprop_group *group);
 824
 825 /* ### docco */
 826 DAV_DECLARE(int) dav_get_liveprop_ns_index(const char *uri);
 827
 828 /* ### docco */
 829 int dav_get_liveprop_ns_count(void);
 830
 831 /* ### docco */
 832 void dav_add_all_liveprop_xmlns(apr_pool_t *p, ap_text_header *phdr);
 833
 834 /*
 835 ** The following three functions are part of mod_dav's internal handling
 836 ** for the core WebDAV properties. They are not part of mod_dav's API.
 837 */
 838 int dav_core_find_liveprop(const dav_resource *resource,
 839                            const char *ns_uri, const char *name,
 840                            const dav_hooks_liveprop **hooks);
 841 void dav_core_insert_all_liveprops(request_rec *r,
 842                                    const dav_resource *resource,
 843                                    int insvalue, ap_text_header *phdr);
 844 void dav_core_register_uris(apr_pool_t *p);
 845
 846
 847 /*
 848 ** Standard WebDAV Property Identifiers
 849 **
 850 ** A live property provider does not need to use these; they are simply
 851 ** provided for convenience.
 852 **
 853 ** Property identifiers need to be unique within a given provider, but not
 854 ** *across* providers (note: this uniqueness constraint was different in
 855 ** older versions of mod_dav).
 856 **
 857 ** The identifiers start at 20000 to make it easier for providers to avoid
 858 ** conflicts with the standard properties. The properties are arranged
 859 ** alphabetically, and may be reordered from time to time (as properties
 860 ** are introduced).
 861 **
 862 ** NOTE: there is no problem with reordering (e.g. binary compat) since the
 863 ** identifiers are only used within a given provider, which would pick up
 864 ** the entire set of changes upon a recompile.
 865 */
 866 enum {
 867     DAV_PROPID_BEGIN = 20000,
 868
 869     /* Standard WebDAV properties (RFC 2518 and DeltaV I-D) */
 870     DAV_PROPID_comment,                         /* from DeltaV I-D */
 871     DAV_PROPID_creationdate,
 872     DAV_PROPID_creator_displayname,             /* from DeltaV I-D */
 873     DAV_PROPID_displayname,
 874     DAV_PROPID_getcontentlanguage,
 875     DAV_PROPID_getcontentlength,
 876     DAV_PROPID_getcontenttype,
 877     DAV_PROPID_getetag,
 878     DAV_PROPID_getlastmodified,
 879     DAV_PROPID_lockdiscovery,
 880     DAV_PROPID_resourcetype,
 881     DAV_PROPID_source,
 882     DAV_PROPID_supportedlock,
 883     DAV_PROPID_supported_method_set,            /* from DeltaV I-D */
 884     DAV_PROPID_supported_live_property_set,     /* from DeltaV I-D */
 885     DAV_PROPID_supported_report_set,            /* from DeltaV I-D */
 886
 887     /* DeltaV properties (from the I-D) */
 888     DAV_PROPID_activity_collection_set,
 889     DAV_PROPID_activity_set,
 890     DAV_PROPID_auto_merge_set,
 891     DAV_PROPID_auto_version,
 892     DAV_PROPID_baseline_selector,
 893     DAV_PROPID_baselined_collection,
 894     DAV_PROPID_baselined_collection_set,
 895     DAV_PROPID_checked_out,
 896     DAV_PROPID_checkin_date,
 897     DAV_PROPID_checkin_fork,
 898     DAV_PROPID_checkout_fork,
 899     DAV_PROPID_checkout_set,
 900     DAV_PROPID_current_activity_set,
 901     DAV_PROPID_current_workspace_set,
 902     DAV_PROPID_initial_version,
 903     DAV_PROPID_label_name_set,
 904     DAV_PROPID_latest_version,
 905     DAV_PROPID_merge_set,
 906     DAV_PROPID_mutable,
 907     DAV_PROPID_predecessor_set,
 908     DAV_PROPID_subactivity_set,
 909     DAV_PROPID_successor_set,
 910     DAV_PROPID_target,
 911     DAV_PROPID_unreserved,
 912     DAV_PROPID_version,
 913     DAV_PROPID_version_history,
 914     DAV_PROPID_version_name,
 915     DAV_PROPID_version_set,
 916     DAV_PROPID_workspace,
 917     DAV_PROPID_workspace_checkout_set,
 918     DAV_PROPID_workspace_collection_set,
 919
 920     DAV_PROPID_END
 921 };
 922
 923 /*
 924 ** Property Identifier Registration
 925 **
 926 ** At the moment, mod_dav requires live property providers to ensure that
 927 ** each property returned has a unique value. For now, this is done through
 928 ** central registration (there are no known providers other than the default,
 929 ** so this remains manageable).
 930 **
 931 ** WARNING: the TEST ranges should never be "shipped".
 932 */
 933 #define DAV_PROPID_CORE         10000   /* ..10099. defined by mod_dav */
 934 #define DAV_PROPID_FS           10100   /* ..10299.
 935                                            mod_dav filesystem provider. */
 936 #define DAV_PROPID_TEST1        10300   /* ..10399 */
 937 #define DAV_PROPID_TEST2        10400   /* ..10499 */
 938 #define DAV_PROPID_TEST3        10500   /* ..10599 */
 939 /* Next: 10600 */
 940
 941
 942 /* --------------------------------------------------------------------
 943 **
 944 ** DATABASE FUNCTIONS
 945 */
 946
 947 typedef struct dav_db dav_db;
 948 typedef apr_datum_t dav_datum;
 949
 950 /* hook functions to enable pluggable databases */
 951 struct dav_hooks_propdb
 952 {
 953     dav_error * (*open)(apr_pool_t *p, const dav_resource *resource, int ro,
 954                         dav_db **pdb);
 955     void (*close)(dav_db *db);
 956
 957     /*
 958     ** Fetch the value from the database. If the value does not exist,
 959     ** then *pvalue should be zeroed.
 960     **
 961     ** Note: it is NOT an error for the key/value pair to not exist.
 962     */
 963     dav_error * (*fetch)(dav_db *db, dav_datum key, dav_datum *pvalue);
 964
 965     dav_error * (*store)(dav_db *db, dav_datum key, dav_datum value);
 966     dav_error * (*remove)(dav_db *db, dav_datum key);
 967
 968     /* returns 1 if the record specified by "key" exists; 0 otherwise */
 969     int (*exists)(dav_db *db, dav_datum key);
 970
 971     dav_error * (*firstkey)(dav_db *db, dav_datum *pkey);
 972     dav_error * (*nextkey)(dav_db *db, dav_datum *pkey);
 973
 974     void (*freedatum)(dav_db *db, dav_datum data);
 975 };
 976
 977
 978 /* --------------------------------------------------------------------
 979 **
 980 ** LOCK FUNCTIONS
 981 */
 982
 983 /* Used to represent a Timeout header of "Infinity" */
 984 #define DAV_TIMEOUT_INFINITE 0
 985
 986 time_t dav_get_timeout(request_rec *r);
 987
 988 /*
 989 ** Opaque, provider-specific information for a lock database.
 990 */
 991 typedef struct dav_lockdb_private dav_lockdb_private;
 992
 993 /*
 994 ** Opaque, provider-specific information for a lock record.
 995 */
 996 typedef struct dav_lock_private dav_lock_private;
 997
 998 /*
 999 ** Lock database type. Lock providers are urged to implement a "lazy" open, so
1000 ** doing an "open" is cheap until something is actually needed from the DB.
1001 */
1002 typedef struct
1003 {
1004     const dav_hooks_locks *hooks;       /* the hooks used for this lockdb */
1005     int ro;                             /* was it opened readonly? */
1006
1007     dav_lockdb_private *info;
1008
1009 } dav_lockdb;
1010
1011 typedef enum {
1012     DAV_LOCKSCOPE_UNKNOWN,
1013     DAV_LOCKSCOPE_EXCLUSIVE,
1014     DAV_LOCKSCOPE_SHARED
1015 } dav_lock_scope;
1016
1017 typedef enum {
1018     DAV_LOCKTYPE_UNKNOWN,
1019     DAV_LOCKTYPE_WRITE
1020 } dav_lock_type;
1021
1022 typedef enum {
1023     DAV_LOCKREC_DIRECT,                 /* lock asserted on this resource */
1024     DAV_LOCKREC_INDIRECT,               /* lock inherited from a parent */
1025     DAV_LOCKREC_INDIRECT_PARTIAL        /* most info is not filled in */
1026 } dav_lock_rectype;
1027
1028 /*
1029 ** dav_lock: hold information about a lock on a resource.
1030 **
1031 ** This structure is used for both direct and indirect locks. A direct lock
1032 ** is a lock applied to a specific resource by the client. An indirect lock
1033 ** is one that is inherited from a parent resource by virtue of a non-zero
1034 ** Depth: header when the lock was applied.
1035 **
1036 ** mod_dav records both types of locks in the lock database, managing their
1037 ** addition/removal as resources are moved about the namespace.
1038 **
1039 ** Note that the lockdb is free to marshal this structure in any form that
1040 ** it likes.
1041 **
1042 ** For a "partial" lock, the <rectype> and <locktoken> fields must be filled
1043 ** in. All other (user) fields should be zeroed. The lock provider will
1044 ** usually fill in the <info> field, and the <next> field may be used to
1045 ** construct a list of partial locks.
1046 **
1047 ** The lock provider MUST use the info field to store a value such that a
1048 ** dav_lock structure can locate itself in the underlying lock database.
1049 ** This requirement is needed for refreshing: when an indirect dav_lock is
1050 ** refreshed, its reference to the direct lock does not specify the direct's
1051 ** resource, so the only way to locate the (refreshed, direct) lock in the
1052 ** database is to use the info field.
1053 **
1054 ** Note that <is_locknull> only refers to the resource where this lock was
1055 ** found.
1056 ** ### hrm. that says the abstraction is wrong. is_locknull may disappear.
1057 */
1058 typedef struct dav_lock
1059 {
1060     dav_lock_rectype rectype;   /* type of lock record */
1061     int is_locknull;            /* lock establishes a locknull resource */
1062
1063     /* ### put the resource in here? */
1064
1065     dav_lock_scope scope;       /* scope of the lock */
1066     dav_lock_type type;         /* type of lock */
1067     int depth;                  /* depth of the lock */
1068     time_t timeout;             /* when the lock will timeout */
1069
1070     const dav_locktoken *locktoken;     /* the token that was issued */
1071
1072     const char *owner;          /* (XML) owner of the lock */
1073     const char *auth_user;      /* auth'd username owning lock */
1074
1075     dav_lock_private *info;     /* private to the lockdb */
1076
1077     struct dav_lock *next;      /* for managing a list of locks */
1078 } dav_lock;
1079
1080 /* Property-related public lock functions */
1081 const char *dav_lock_get_activelock(request_rec *r, dav_lock *locks,
1082                                     dav_buffer *pbuf);
1083
1084 /* LockDB-related public lock functions */
1085 dav_error * dav_lock_parse_lockinfo(request_rec *r,
1086                                     const dav_resource *resrouce,
1087                                     dav_lockdb *lockdb,
1088                                     const ap_xml_doc *doc,
1089                                     dav_lock **lock_request);
1090 int dav_unlock(request_rec *r, const dav_resource *resource,
1091                const dav_locktoken *locktoken);
1092 dav_error * dav_add_lock(request_rec *r, const dav_resource *resource,
1093                          dav_lockdb *lockdb, dav_lock *request,
1094                          dav_response **response);
1095 dav_error * dav_notify_created(request_rec *r,
1096                                dav_lockdb *lockdb,
1097                                const dav_resource *resource,
1098                                int resource_state,
1099                                int depth);
1100
1101 DAV_DECLARE(dav_error*) dav_lock_query(dav_lockdb *lockdb,
1102                                        const dav_resource *resource,
1103                                        dav_lock **locks);
1104
1105 dav_error * dav_validate_request(request_rec *r, dav_resource *resource,
1106                                  int depth, dav_locktoken *locktoken,
1107                                  dav_response **response, int flags,
1108                                  dav_lockdb *lockdb);
1109 /*
1110 ** flags:
1111 **    0x0F -- reserved for <dav_lock_scope> values
1112 **
1113 **    other flags, detailed below
1114 */
1115 #define DAV_VALIDATE_RESOURCE   0x0010  /* validate just the resource */
1116 #define DAV_VALIDATE_PARENT     0x0020  /* validate resource AND its parent */
1117 #define DAV_VALIDATE_ADD_LD     0x0040  /* add DAV:lockdiscovery into
1118                                            the 424 DAV:response */
1119 #define DAV_VALIDATE_USE_424    0x0080  /* return 424 status, not 207 */
1120 #define DAV_VALIDATE_IS_PARENT  0x0100  /* for internal use */
1121
1122 /* Lock-null related public lock functions */
1123 int dav_get_resource_state(request_rec *r, const dav_resource *resource);
1124
1125 /* Lock provider hooks. Locking is optional, so there may be no
1126  * lock provider for a given repository.
1127  */
1128 struct dav_hooks_locks
1129 {
1130     /* Return the supportedlock property for a resource */
1131     const char * (*get_supportedlock)(
1132         const dav_resource *resource
1133     );
1134
1135     /* Parse a lock token URI, returning a lock token object allocated
1136      * in the given pool.
1137      */
1138     dav_error * (*parse_locktoken)(
1139         apr_pool_t *p,
1140         const char *char_token,
1141         dav_locktoken **locktoken_p
1142     );
1143
1144     /* Format a lock token object into a URI string, allocated in
1145      * the given pool.
1146      *
1147      * Always returns non-NULL.
1148      */
1149     const char * (*format_locktoken)(
1150         apr_pool_t *p,
1151         const dav_locktoken *locktoken
1152     );
1153
1154     /* Compare two lock tokens.
1155      *
1156      * Result < 0  => lt1 < lt2
1157      * Result == 0 => lt1 == lt2
1158      * Result > 0  => lt1 > lt2
1159      */
1160     int (*compare_locktoken)(
1161         const dav_locktoken *lt1,
1162         const dav_locktoken *lt2
1163     );
1164
1165     /* Open the provider's lock database.
1166      *
1167      * The provider may or may not use a "real" database for locks
1168      * (a lock could be an attribute on a resource, for example).
1169      *
1170      * The provider may choose to use the value of the DAVLockDB directive
1171      * (as returned by dav_get_lockdb_path()) to decide where to place
1172      * any storage it may need.
1173      *
1174      * The request storage pool should be associated with the lockdb,
1175      * so it can be used in subsequent operations.
1176      *
1177      * If ro != 0, only readonly operations will be performed.
1178      * If force == 0, the open can be "lazy"; no subsequent locking operations
1179      * may occur.
1180      * If force != 0, locking operations will definitely occur.
1181      */
1182     dav_error * (*open_lockdb)(
1183         request_rec *r,
1184         int ro,
1185         int force,
1186         dav_lockdb **lockdb
1187     );
1188
1189     /* Indicates completion of locking operations */
1190     void (*close_lockdb)(
1191         dav_lockdb *lockdb
1192     );
1193
1194     /* Take a resource out of the lock-null state. */
1195     dav_error * (*remove_locknull_state)(
1196         dav_lockdb *lockdb,
1197         const dav_resource *resource
1198     );
1199
1200     /*
1201     ** Create a (direct) lock structure for the given resource. A locktoken
1202     ** will be created.
1203     **
1204     ** The lock provider may store private information into lock->info.
1205     */
1206     dav_error * (*create_lock)(dav_lockdb *lockdb,
1207                                const dav_resource *resource,
1208                                dav_lock **lock);
1209
1210     /*
1211     ** Get the locks associated with the specified resource.
1212     **
1213     ** If resolve_locks is true (non-zero), then any indirect locks are
1214     ** resolved to their actual, direct lock (i.e. the reference to followed
1215     ** to the original lock).
1216     **
1217     ** The locks, if any, are returned as a linked list in no particular
1218     ** order. If no locks are present, then *locks will be NULL.
1219     */
1220     dav_error * (*get_locks)(dav_lockdb *lockdb,
1221                              const dav_resource *resource,
1222                              int calltype,
1223                              dav_lock **locks);
1224
1225 #define DAV_GETLOCKS_RESOLVED   0       /* resolve indirects to directs */
1226 #define DAV_GETLOCKS_PARTIAL    1       /* leave indirects partially filled */
1227 #define DAV_GETLOCKS_COMPLETE   2       /* fill out indirect locks */
1228
1229     /*
1230     ** Find a particular lock on a resource (specified by its locktoken).
1231     **
1232     ** *lock will be set to NULL if the lock is not found.
1233     **
1234     ** Note that the provider can optimize the unmarshalling -- only one
1235     ** lock (or none) must be constructed and returned.
1236     **
1237     ** If partial_ok is true (non-zero), then an indirect lock can be
1238     ** partially filled in. Otherwise, another lookup is done and the
1239     ** lock structure will be filled out as a DAV_LOCKREC_INDIRECT.
1240     */
1241     dav_error * (*find_lock)(dav_lockdb *lockdb,
1242                              const dav_resource *resource,
1243                              const dav_locktoken *locktoken,
1244                              int partial_ok,
1245                              dav_lock **lock);
1246
1247     /*
1248     ** Quick test to see if the resource has *any* locks on it.
1249     **
1250     ** This is typically used to determine if a non-existent resource
1251     ** has a lock and is (therefore) a locknull resource.
1252     **
1253     ** WARNING: this function may return TRUE even when timed-out locks
1254     **          exist (i.e. it may not perform timeout checks).
1255     */
1256     dav_error * (*has_locks)(dav_lockdb *lockdb,
1257                              const dav_resource *resource,
1258                              int *locks_present);
1259
1260     /*
1261     ** Append the specified lock(s) to the set of locks on this resource.
1262     **
1263     ** If "make_indirect" is true (non-zero), then the specified lock(s)
1264     ** should be converted to an indirect lock (if it is a direct lock)
1265     ** before appending. Note that the conversion to an indirect lock does
1266     ** not alter the passed-in lock -- the change is internal the
1267     ** append_locks function.
1268     **
1269     ** Multiple locks are specified using the lock->next links.
1270     */
1271     dav_error * (*append_locks)(dav_lockdb *lockdb,
1272                                 const dav_resource *resource,
1273                                 int make_indirect,
1274                                 const dav_lock *lock);
1275
1276     /*
1277     ** Remove any lock that has the specified locktoken.
1278     **
1279     ** If locktoken == NULL, then ALL locks are removed.
1280     */
1281     dav_error * (*remove_lock)(dav_lockdb *lockdb,
1282                                const dav_resource *resource,
1283                                const dav_locktoken *locktoken);
1284
1285     /*
1286     ** Refresh all locks, found on the specified resource, which has a
1287     ** locktoken in the provided list.
1288     **
1289     ** If the lock is indirect, then the direct lock is referenced and
1290     ** refreshed.
1291     **
1292     ** Each lock that is updated is returned in the <locks> argument.
1293     ** Note that the locks will be fully resolved.
1294     */
1295     dav_error * (*refresh_locks)(dav_lockdb *lockdb,
1296                                  const dav_resource *resource,
1297                                  const dav_locktoken_list *ltl,
1298                                  time_t new_time,
1299                                  dav_lock **locks);
1300
1301     /*
1302     ** Look up the resource associated with a particular locktoken.
1303     **
1304     ** The search begins at the specified <start_resource> and the lock
1305     ** specified by <locktoken>.
1306     **
1307     ** If the resource/token specifies an indirect lock, then the direct
1308     ** lock will be looked up, and THAT resource will be returned. In other
1309     ** words, this function always returns the resource where a particular
1310     ** lock (token) was asserted.
1311     **
1312     ** NOTE: this function pointer is allowed to be NULL, indicating that
1313     **       the provider does not support this type of functionality. The
1314     **       caller should then traverse up the repository hierarchy looking
1315     **       for the resource defining a lock with this locktoken.
1316     */
1317     dav_error * (*lookup_resource)(dav_lockdb *lockdb,
1318                                    const dav_locktoken *locktoken,
1319                                    const dav_resource *start_resource,
1320                                    const dav_resource **resource);
1321 };
1322
1323 /* what types of resources can be discovered by dav_get_resource_state() */
1324 #define DAV_RESOURCE_LOCK_NULL  10      /* resource lock-null */
1325 #define DAV_RESOURCE_NULL       11      /* resource null */
1326 #define DAV_RESOURCE_EXISTS     12      /* resource exists */
1327 #define DAV_RESOURCE_ERROR      13      /* an error occurred */
1328
1329
1330 /* --------------------------------------------------------------------
1331 **
1332 ** PROPERTY HANDLING
1333 */
1334
1335 typedef struct dav_propdb dav_propdb;
1336
1337
1338 dav_error *dav_open_propdb(
1339     request_rec *r,
1340     dav_lockdb *lockdb,
1341     dav_resource *resource,
1342     int ro,
1343     apr_array_header_t *ns_xlate,
1344     dav_propdb **propdb);
1345
1346 void dav_close_propdb(dav_propdb *db);
1347
1348 dav_get_props_result dav_get_props(
1349     dav_propdb *db,
1350     ap_xml_doc *doc);
1351
1352 dav_get_props_result dav_get_allprops(
1353     dav_propdb *db,
1354     int getvals);
1355
1356 /*
1357 ** 3-phase property modification.
1358 **
1359 **   1) validate props. readable? unlocked? ACLs allow access?
1360 **   2) execute operation (set/delete)
1361 **   3) commit or rollback
1362 **
1363 ** ### eventually, auth must be available. a ref to the request_rec (which
1364 ** ### contains the auth info) should be in the shared context struct.
1365 **
1366 ** Each function may alter the error values and information contained within
1367 ** the context record. This should be done as an "increasing" level of
1368 ** error, rather than overwriting any previous error.
1369 **
1370 ** Note that commit() cannot generate errors. It should simply free the
1371 ** rollback information.
1372 **
1373 ** rollback() may generate additional errors because the rollback operation
1374 ** can sometimes fail(!).
1375 **
1376 ** The caller should allocate an array of these, one per operation. It should
1377 ** be zero-initialized, then the db, operation, and prop fields should be
1378 ** filled in before calling dav_prop_validate. Note that the set/delete
1379 ** operations are order-dependent. For a given (logical) context, the same
1380 ** pointer must be passed to each phase.
1381 **
1382 ** error_type is an internal value, but will have the same numeric value
1383 ** for each possible "desc" value. This allows the caller to group the
1384 ** descriptions via the error_type variable, rather than through string
1385 ** comparisons. Note that "status" does not provide enough granularity to
1386 ** differentiate/group the "desc" values.
1387 **
1388 ** Note that the propdb will maintain some (global) context across all
1389 ** of the property change contexts. This implies that you can have only
1390 ** one open transaction per propdb.
1391 */
1392 typedef struct dav_prop_ctx
1393 {
1394     dav_propdb *propdb;
1395
1396     int operation;
1397 #define DAV_PROP_OP_SET         1       /* set a property value */
1398 #define DAV_PROP_OP_DELETE      2       /* delete a prop value */
1399 /* ### add a GET? */
1400
1401     ap_xml_elem *prop;                  /* property to affect */
1402
1403     dav_error *err;                     /* error (if any) */
1404
1405     /* private items to the propdb */
1406     int is_liveprop;
1407     void *liveprop_ctx;
1408     struct dav_rollback_item *rollback; /* optional rollback info */
1409
1410     /* private to mod_dav.c */
1411     request_rec *r;
1412
1413 } dav_prop_ctx;
1414
1415 void dav_prop_validate(dav_prop_ctx *ctx);
1416 void dav_prop_exec(dav_prop_ctx *ctx);
1417 void dav_prop_commit(dav_prop_ctx *ctx);
1418 void dav_prop_rollback(dav_prop_ctx *ctx);
1419
1420 #define DAV_PROP_CTX_HAS_ERR(dpc)       ((dpc).err && (dpc).err->status >= 300)
1421
1422
1423 /* --------------------------------------------------------------------
1424 **
1425 ** WALKER STRUCTURE
1426 */
1427
1428 enum {
1429     DAV_CALLTYPE_MEMBER = 1,    /* called for a member resource */
1430     DAV_CALLTYPE_COLLECTION,    /* called for a collection */
1431     DAV_CALLTYPE_LOCKNULL,      /* called for a locknull resource */
1432 };
1433
1434 typedef struct
1435 {
1436     /* the client-provided context */
1437     void *walk_ctx;
1438
1439     /* pool to use for allocations in the callback */
1440     apr_pool_t *pool;
1441
1442     /* the current resource */
1443     const dav_resource *resource;
1444
1445     /* OUTPUT: add responses to this */
1446     dav_response *response;
1447
1448 } dav_walk_resource;
1449
1450 typedef struct
1451 {
1452     int walk_type;
1453 #define DAV_WALKTYPE_AUTH       0x0001  /* limit to authorized files */
1454 #define DAV_WALKTYPE_NORMAL     0x0002  /* walk normal files */
1455 #define DAV_WALKTYPE_LOCKNULL   0x0004  /* walk locknull resources */
1456
1457     /* callback function and a client context for the walk */
1458     dav_error * (*func)(dav_walk_resource *wres, int calltype);
1459     void *walk_ctx;
1460
1461     /* what pool to use for allocations needed by walk logic */
1462     apr_pool_t *pool;
1463
1464     /* beginning root of the walk */
1465     const dav_resource *root;
1466
1467     /* lock database to enable walking LOCKNULL resources */
1468     dav_lockdb *lockdb;
1469
1470 } dav_walk_params;
1471
1472 /* directory tree walking context */
1473 typedef struct dav_walker_ctx
1474 {
1475     /* input: */
1476     dav_walk_params w;
1477
1478
1479     /* ### client data... phasing out this big glom */
1480
1481     request_rec *r;                     /* original request */
1482
1483     /* for PROPFIND operations */
1484     ap_xml_doc *doc;
1485     int propfind_type;
1486 #define DAV_PROPFIND_IS_ALLPROP         1
1487 #define DAV_PROPFIND_IS_PROPNAME        2
1488 #define DAV_PROPFIND_IS_PROP            3
1489
1490     ap_text *propstat_404;      /* (cached) propstat giving a 404 error */
1491
1492     const dav_if_header *if_header;     /* for validation */
1493     const dav_locktoken *locktoken;     /* for UNLOCK */
1494     const dav_lock *lock;               /* for LOCK */
1495     int skip_root;                      /* for dav_inherit_locks() */
1496
1497     int flags;
1498
1499     dav_buffer work_buf;                /* for dav_validate_request() */
1500
1501 } dav_walker_ctx;
1502
1503 DAV_DECLARE(void) dav_add_response(dav_walk_resource *wres,
1504                                    int status,
1505                                    dav_get_props_result *propstats);
1506
1507
1508 /* --------------------------------------------------------------------
1509 **
1510 ** "STREAM" STRUCTURE
1511 **
1512 ** mod_dav uses this abstraction for interacting with the repository
1513 ** while fetching/storing resources. mod_dav views resources as a stream
1514 ** of bytes.
1515 **
1516 ** Note that the structure is opaque -- it is private to the repository
1517 ** that created the stream in the repository's "open" function.
1518 */
1519
1520 typedef struct dav_stream dav_stream;
1521
1522 typedef enum {
1523     DAV_MODE_READ,              /* open for reading */
1524     DAV_MODE_READ_SEEKABLE,     /* open for random access reading */
1525     DAV_MODE_WRITE_TRUNC,       /* truncate and open for writing */
1526     DAV_MODE_WRITE_SEEKABLE     /* open for writing; random access */
1527 } dav_stream_mode;
1528
1529
1530 /* --------------------------------------------------------------------
1531 **
1532 ** REPOSITORY FUNCTIONS
1533 */
1534
1535 /* Repository provider hooks */
1536 struct dav_hooks_repository
1537 {
1538     /* Flag for whether repository requires special GET handling.
1539      * If resources in the repository are not visible in the
1540      * filesystem location which URLs map to, then special handling
1541      * is required to first fetch a resource from the repository,
1542      * respond to the GET request, then free the resource copy.
1543      */
1544     int handle_get;
1545
1546     /* Get a resource descriptor for the URI in a request.
1547      * A descriptor is returned even if the resource does not exist.
1548      * The return value should only be NULL for some kind of fatal error.
1549      *
1550      * The root_dir is the root of the directory for which this repository
1551      * is configured.
1552      * The target is either a label, or a version URI, or NULL. If there
1553      * is a target, then is_label specifies whether the target is a label
1554      * or a URI.
1555      *
1556      * The provider may associate the request storage pool with the resource,
1557      * to use in other operations on that resource.
1558      */
1559     dav_resource * (*get_resource)(
1560         request_rec *r,
1561         const char *root_dir,
1562         const char *target,
1563         int is_label
1564     );
1565
1566     /* Get a resource descriptor for the parent of the given resource.
1567      * The resources need not exist.  NULL is returned if the resource
1568      * is the root collection.
1569      */
1570     dav_resource * (*get_parent_resource)(
1571         const dav_resource *resource
1572     );
1573
1574     /* Determine whether two resource descriptors refer to the same resource.
1575     *
1576      * Result != 0 => the resources are the same.
1577      */
1578     int (*is_same_resource)(
1579         const dav_resource *res1,
1580         const dav_resource *res2
1581     );
1582
1583     /* Determine whether one resource is a parent (immediate or otherwise)
1584      * of another.
1585      *
1586      * Result != 0 => res1 is a parent of res2.
1587      */
1588     int (*is_parent_resource)(
1589         const dav_resource *res1,
1590         const dav_resource *res2
1591     );
1592
1593     /*
1594     ** Open a stream for this resource, using the specified mode. The
1595     ** stream will be returned in *stream.
1596     */
1597     dav_error * (*open_stream)(const dav_resource *resource,
1598                                dav_stream_mode mode,
1599                                dav_stream **stream);
1600
1601     /*
1602     ** Close the specified stream.
1603     **
1604     ** mod_dav will (ideally) make sure to call this. For safety purposes,
1605     ** a provider should (ideally) register a cleanup function with the
1606     ** request pool to get this closed and cleaned up.
1607     **
1608     ** Note the possibility of an error from the close -- it is entirely
1609     ** feasible that the close does a "commit" of some kind, which can
1610     ** produce an error.
1611     **
1612     ** commit should be TRUE (non-zero) or FALSE (0) if the stream was
1613     ** opened for writing. This flag states whether to retain the file
1614     ** or not.
1615     ** Note: the commit flag is ignored for streams opened for reading.
1616     */
1617     dav_error * (*close_stream)(dav_stream *stream, int commit);
1618
1619     /*
1620     ** Read data from the stream.
1621     **
1622     ** The size of the buffer is passed in *bufsize, and the amount read
1623     ** is returned in *bufsize.
1624     **
1625     ** *bufsize should be set to zero when the end of file is reached.
1626     ** As a corollary, this function should always read at least one byte
1627     ** on each call, until the EOF condition is met.
1628     */
1629     dav_error * (*read_stream)(dav_stream *stream,
1630                                void *buf, apr_size_t *bufsize);
1631
1632     /*
1633     ** Write data to the stream.
1634     **
1635     ** All of the bytes must be written, or an error should be returned.
1636     */
1637     dav_error * (*write_stream)(dav_stream *stream,
1638                                 const void *buf, apr_size_t bufsize);
1639
1640     /*
1641     ** Seek to an absolute position in the stream. This is used to support
1642     ** Content-Range in a GET/PUT.
1643     **
1644     ** NOTE: if this function is NULL (which is allowed), then any
1645     **       operations using Content-Range will be refused.
1646     */
1647     dav_error * (*seek_stream)(dav_stream *stream, apr_off_t abs_position);
1648
1649     /*
1650     ** If a GET is processed using a stream (open_stream, read_stream)
1651     ** rather than via a sub-request (on get_pathname), then this function
1652     ** is used to provide the repository with a way to set the headers
1653     ** in the response.
1654     **
1655     ** It may be NULL if get_pathname is provided.
1656     */
1657     dav_error * (*set_headers)(request_rec *r,
1658                                const dav_resource *resource);
1659
1660     /* Get a pathname for the file represented by the resource descriptor.
1661      * A provider may need to create a temporary copy of the file, if it is
1662      * not directly accessible in a filesystem. free_handle_p will be set by
1663      * the provider to point to information needed to clean up any temporary
1664      * storage used.
1665      *
1666      * Returns NULL if the file could not be made accessible.
1667      */
1668     const char * (*get_pathname)(
1669         const dav_resource *resource,
1670         void **free_handle_p
1671     );
1672
1673     /* Free any temporary storage associated with a file made accessible by
1674      * get_pathname().
1675      */
1676     void (*free_file)(
1677         void *free_handle
1678     );
1679
1680     /* Create a collection resource. The resource must not already exist.
1681      *
1682      * Result == NULL if the collection was created successfully. Also, the
1683      * resource object is updated to reflect that the resource exists, and
1684      * is a collection.
1685      */
1686     dav_error * (*create_collection)(
1687         dav_resource *resource
1688     );
1689
1690     /* Copy one resource to another. The destination must not exist.
1691      * Handles both files and collections. Properties are copied as well.
1692      * The depth argument is ignored for a file, and can be either 0 or
1693      * DAV_INFINITY for a collection.
1694      * If an error occurs in a child resource, then the return value is
1695      * non-NULL, and *response is set to a multistatus response.
1696      * If the copy is successful, the dst resource object is
1697      * updated to reflect that the resource exists.
1698      */
1699     dav_error * (*copy_resource)(
1700         const dav_resource *src,
1701         dav_resource *dst,
1702         int depth,
1703         dav_response **response
1704     );
1705
1706     /* Move one resource to another. The destination must not exist.
1707      * Handles both files and collections. Properties are moved as well.
1708      * If an error occurs in a child resource, then the return value is
1709      * non-NULL, and *response is set to a multistatus response.
1710      * If the move is successful, the src and dst resource objects are
1711      * updated to reflect that the source no longer exists, and the
1712      * destination does.
1713      */
1714     dav_error * (*move_resource)(
1715         dav_resource *src,
1716         dav_resource *dst,
1717         dav_response **response
1718     );
1719
1720     /* Remove a resource. Handles both files and collections.
1721      * Removes any associated properties as well.
1722      * If an error occurs in a child resource, then the return value is
1723      * non-NULL, and *response is set to a multistatus response.
1724      * If the delete is successful, the resource object is updated to
1725      * reflect that the resource no longer exists.
1726      */
1727     dav_error * (*remove_resource)(
1728         dav_resource *resource,
1729         dav_response **response
1730     );
1731
1732     /* Walk a resource hierarchy.
1733      *
1734      * Iterates over the resource hierarchy specified by params->root.
1735      * Control of the walk and the callback are specified by 'params'.
1736      *
1737      * An error may be returned. *response will contain multistatus
1738      * responses (if any) suitable for the body of the error. It is also
1739      * possible to return NULL, yet still have multistatus responses.
1740      * In this case, typically the caller should return a 207 (Multistatus)
1741      * and the responses (in the body) as the HTTP response.
1742      */
1743     dav_error * (*walk)(const dav_walk_params *params, int depth,
1744                         dav_response **response);
1745
1746     /* Get the entity tag for a resource */
1747     const char * (*getetag)(const dav_resource *resource);
1748 };
1749
1750
1751 /* --------------------------------------------------------------------
1752 **
1753 ** VERSIONING FUNCTIONS
1754 */
1755
1756
1757 /*
1758  * dav_get_target_selector
1759  *
1760  * If a DAV:version or DAV:label-name element is provided,
1761  * then it is assumed to provide the target version.
1762  * If no element is provided (version==NULL), then the
1763  * request headers are examined for a Target-Selector header.
1764  *
1765  * The target version, if any, is then returned. If the version
1766  * was specified by a label, then *is_label is set to 1.
1767  * Otherwise, the target is a version URI.
1768  *
1769  * (used by versioning clients)
1770  */
1771 int dav_get_target_selector(request_rec *r,
1772                             const ap_xml_elem *version,
1773                             const char **target,
1774                             int *is_label);
1775
1776 /* dav_add_vary_header
1777  *
1778  * If there were any headers in the request which require a Vary header
1779  * in the response, add it.
1780  */
1781 void dav_add_vary_header(request_rec *in_req,
1782                          request_rec *out_req,
1783                          const dav_resource *resource);
1784
1785 /*
1786 ** This structure is used to record what auto-versioning operations
1787 ** were done to make a resource writable, so that they can be undone
1788 ** at the end of a request.
1789 */
1790 typedef struct {
1791     int resource_created;               /* 0 => resource existed previously */
1792     int resource_checkedout;            /* 0 => resource was checked out */
1793     int parent_checkedout;              /* 0 => parent was checked out */
1794     dav_resource *parent_resource;      /* parent resource, if it was needed */
1795 } dav_auto_version_info;
1796
1797 /* Ensure that a resource is writable. If there is no versioning
1798  * provider, then this is essentially a no-op. Versioning repositories
1799  * require explicit resource creation and checkout before they can
1800  * be written to. If a new resource is to be created, or an existing
1801  * resource deleted, the parent collection must be checked out as well.
1802  *
1803  * Set the parent_only flag to only make the parent collection writable.
1804  * Otherwise, both parent and child are made writable as needed. If the
1805  * child does not exist, then a new versioned resource is created and
1806  * checked out.
1807  *
1808  * The dav_auto_version_info structure is filled in with enough information
1809  * to restore both parent and child resources to the state they were in
1810  * before the auto-versioning operations occurred.
1811  */
1812 dav_error *dav_ensure_resource_writable(request_rec *r,
1813                                         dav_resource *resource,
1814                                         int parent_only,
1815                                         dav_auto_version_info *av_info);
1816
1817 /* Revert the writability of resources back to what they were
1818  * before they were modified. If undo == 0, then the resource
1819  * modifications are maintained (i.e. they are checked in).
1820  * If undo != 0, then resource modifications are discarded
1821  * (i.e. they are unchecked out).
1822  *
1823  * The resource argument may be NULL if only the parent resource
1824  * was made writable (i.e. the parent_only was != 0 in the
1825  * dav_ensure_resource_writable call).
1826  */
1827 dav_error *dav_revert_resource_writability(
1828     request_rec *r,
1829     dav_resource *resource,
1830     int undo,
1831     const dav_auto_version_info *av_info);
1832
1833 /*
1834 ** This structure is used to describe available reports
1835 **
1836 ** "nmspace" should be valid XML and URL-quoted. mod_dav will place
1837 ** double-quotes around it and use it in an xmlns declaration.
1838 */
1839 typedef struct {
1840     const char *nmspace;        /* namespace of the XML report element */
1841     const char *name;           /* element name for the XML report */
1842 } dav_report_elem;
1843
1844
1845 /* Versioning provider hooks */
1846 struct dav_hooks_vsn
1847 {
1848     /*
1849     ** MANDATORY HOOKS
1850     ** The following hooks are mandatory for all versioning providers;
1851     ** they define the functionality needed to implement "core" versioning.
1852     */
1853
1854     /* Return supported versioning level
1855      * for the Versioning header
1856      */
1857     const char * (*get_vsn_header)(void);
1858
1859     /* Put a resource under version control. If the resource already
1860      * exists unversioned, then it becomes the initial version of the
1861      * new version history, and it is replaced by a version selector
1862      * which targets the new version.
1863      *
1864      * If the resource does not exist, then a new version selector
1865      * is created which either targets an existing version (if the
1866      * "target" argument is not NULL), or the initial, empty version
1867      * in a new history resource (if the "target" argument is NULL).
1868      *
1869      * If successful, the resource object state is updated appropriately
1870      * (that is, changed to refer to the new version selector resource).
1871      */
1872     dav_error * (*vsn_control)(dav_resource *resource,
1873                                const char *target);
1874
1875     /* Checkout a resource. If successful, the resource
1876      * object state is updated appropriately.
1877      *
1878      * If the working resource has a different URL from the
1879      * target resource, a dav_resource descriptor is returned
1880      * for the new working resource. Otherwise, the original
1881      * resource descriptor will refer to the working resource.
1882      * The working_resource argument can be NULL if the caller
1883      * is not interested in the working resource.
1884      */
1885     dav_error * (*checkout)(dav_resource *resource,
1886                             dav_resource **working_resource);
1887
1888     /* Uncheckout a resource. If successful, the resource
1889      * object state is updated appropriately.
1890      */
1891     dav_error * (*uncheckout)(dav_resource *resource);
1892
1893     /* Checkin a working resource. If successful, the resource
1894      * object state is updated appropriately, and the
1895      * version_resource descriptor will refer to the new version.
1896      * The version_resource argument can be NULL if the caller
1897      * is not interested in the new version resource.
1898      */
1899     dav_error * (*checkin)(dav_resource *resource,
1900                            dav_resource **version_resource);
1901
1902     /*
1903     ** Set the default target of a version selector or
1904     ** baseline selector resource.
1905     ** The target argument specifies the new target, which
1906     ** can be a label, if is_label != 0, or a version URI,
1907     ** if is_label == 0.
1908     */
1909     dav_error * (*set_target)(const dav_resource *resource,
1910                               const char *target,
1911                               int is_label);
1912
1913     /* Determine whether a non-versioned (or non-existent) resource
1914      * is versionable. Returns != 0 if resource can be versioned.
1915      */
1916     int (*versionable)(const dav_resource *resource);
1917
1918     /* Determine whether auto-versioning is enabled for a resource
1919      * (which may not exist, or may not be versioned).
1920      * Returns != 0 if auto-versioning is enabled.
1921      */
1922     int (*auto_version_enabled)(const dav_resource *resource);
1923
1924     /*
1925     ** Return the set of reports available at this resource.
1926     **
1927     ** An array of report elements should be returned, with an end-marker
1928     ** element containing namespace==NULL. The value of the
1929     ** DAV:supported-report-set property will be constructed and
1930     ** returned.
1931     */
1932     dav_error * (*avail_reports)(const dav_resource *resource,
1933                                  const dav_report_elem **reports);
1934
1935     /*
1936     ** Determine whether a Target-Selector header can be used
1937     ** with a particular report. The dav_xml_doc structure
1938     ** contains the parsed report request body.
1939     ** Returns 0 if Target-Selector is not allowed.
1940     */
1941     int (*report_target_selector_allowed)(const ap_xml_doc *doc);
1942
1943     /*
1944     ** Generate a report on a resource. Since a provider is free
1945     ** to define its own reports, and the value of request headers
1946     ** may affect the interpretation of a report, the request record
1947     ** must be passed to this routine.
1948     **
1949     ** The dav_xml_doc structure contains the parsed report request
1950     ** body. The report response is generated into the dav_text_header
1951     ** structure.
1952     **
1953     ** ### shouldn't generate large responses to memory ###
1954     */
1955     dav_error * (*get_report)(request_rec *r,
1956                               const dav_resource *resource,
1957                               const ap_xml_doc *doc,
1958                               ap_text_header *report);
1959
1960     /*
1961     ** OPTIONAL HOOKS
1962     ** The following hooks are optional; if not defined, then the
1963     ** corresponding protocol methods will be unsupported.
1964     */
1965
1966     /*
1967     ** Add a label to a version. The resource is either a specific
1968     ** version, or a version selector, in which case the label should
1969     ** be added to the current target of the version selector. The
1970     ** version selector cannot be checked out.
1971     **
1972     ** If replace != 0, any existing label by the same name is
1973     ** effectively deleted first. Otherwise, it is an error to
1974     ** attempt to add a label which already exists on some version
1975     ** of the same history resource.
1976     **
1977     ** This hook is optional; if not defined, then the LABEL method
1978     ** will not be supported. If it is defined, then the remove_label
1979     ** hook must be defined also.
1980     */
1981     dav_error * (*add_label)(const dav_resource *resource,
1982                              const char *label,
1983                              int replace);
1984
1985     /*
1986     ** Remove a label from a version. The resource is either a specific
1987     ** version, or a version selector, in which case the label should
1988     ** be added to the current target of the version selector. The
1989     ** version selector cannot be checked out.
1990     **
1991     ** It is an error if no such label exists on the specified version.
1992     **
1993     ** This hook is optional, but if defined, the add_label hook
1994     ** must be defined also.
1995     */
1996     dav_error * (*remove_label)(const dav_resource *resource,
1997                                 const char *label);
1998
1999     /*
2000     ** Determine whether a null resource can be created as a workspace.
2001     ** The provider may restrict workspaces to certain locations.
2002     ** Returns 0 if the resource cannot be a workspace.
2003     **
2004     ** This hook is optional; if the provider does not support workspaces,
2005     ** it should be set to NULL.
2006     */
2007     int (*can_be_workspace)(const dav_resource *resource);
2008
2009     /*
2010     ** Create a workspace resource. The resource must not already
2011     ** exist. Any <DAV:mkworkspace> element is passed to the provider
2012     ** in the "doc" structure; it may be empty.
2013     **
2014     ** If workspace creation is succesful, the state of the resource
2015     ** object is updated appropriately.
2016     **
2017     ** This hook is optional; if the provider does not support workspaces,
2018     ** it should be set to NULL.
2019     */
2020     dav_error * (*make_workspace)(dav_resource *resource,
2021                                   ap_xml_doc *doc);
2022 };
2023
2024
2025 /* --------------------------------------------------------------------
2026 **
2027 ** BINDING FUNCTIONS
2028 */
2029
2030 /* binding provider hooks */
2031 struct dav_hooks_binding {
2032
2033     /* Determine whether a resource can be the target of a binding.
2034      * Returns 0 if the resource cannot be a binding target.
2035      */
2036     int (*is_bindable)(const dav_resource *resource);
2037
2038     /* Create a binding to a resource.
2039      * The resource argument is the target of the binding;
2040      * the binding argument must be a resource which does not already
2041      * exist.
2042      */
2043     dav_error * (*bind_resource)(const dav_resource *resource,
2044                                  dav_resource *binding);
2045
2046 };
2047
2048
2049 /* --------------------------------------------------------------------
2050 **
2051 ** MISCELLANEOUS STUFF
2052 */
2053
2054 /* allow providers access to the per-directory parameters */
2055 apr_table_t *dav_get_dir_params(const request_rec *r);
2056
2057 /* fetch the "LimitXMLRequestBody" in force for this resource */
2058 apr_size_t dav_get_limit_xml_body(const request_rec *r);
2059
2060 typedef struct {
2061     int propid;                         /* live property ID */
2062     const dav_hooks_liveprop *provider; /* the provider defining this prop */
2063 } dav_elem_private;
2064
2065 #ifdef __cplusplus
2066 }
2067 #endif
2068
2069 #endif /* _MOD_DAV_H_ */