rubbos/app/apache2/include/mod_dav.h

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