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

   1 /* ====================================================================
   2  * The Apache Software License, Version 1.1
   3  *
   4  * Copyright (c) 2000 The Apache Software Foundation.  All rights
   5  * reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  *
  11  * 1. Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  *
  14  * 2. Redistributions in binary form must reproduce the above copyright
  15  *    notice, this list of conditions and the following disclaimer in
  16  *    the documentation and/or other materials provided with the
  17  *    distribution.
  18  *
  19  * 3. The end-user documentation included with the redistribution,
  20  *    if any, must include the following acknowledgment:
  21  *       "This product includes software developed by the
  22  *        Apache Software Foundation (http://www.apache.org/)."
  23  *    Alternately, this acknowledgment may appear in the software itself,
  24  *    if and wherever such third-party acknowledgments normally appear.
  25  *
  26  * 4. The names "Apache" and "Apache Software Foundation" must
  27  *    not be used to endorse or promote products derived from this
  28  *    software without prior written permission. For written
  29  *    permission, please contact apache@apache.org.
  30  *
  31  * 5. Products derived from this software may not be called "Apache",
  32  *    nor may "Apache" appear in their name, without prior written
  33  *    permission of the Apache Software Foundation.
  34  *
  35  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46  * SUCH DAMAGE.
  47  * ====================================================================
  48  *
  49  * This software consists of voluntary contributions made by many
  50  * individuals on behalf of the Apache Software Foundation.  For more
  51  * information on the Apache Software Foundation, please see
  52  * <http://www.apache.org/>.
  53  */
  54
  55 /*
  56 ** DAV extension module for Apache 2.0.*
  57 */
  58
  59 #ifndef _MOD_DAV_H_
  60 #define _MOD_DAV_H_
  61
  62 #ifdef __cplusplus
  63 extern "C" {
  64 #endif
  65
  66 #include "httpd.h"
  67 #include "util_xml.h"
  68
  69 #include <limits.h>     /* for INT_MAX */
  70
  71
  72 #define DAV_VERSION             "1.0.1"
  73
  74 #define DAV_XML_HEADER          "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
  75 #define DAV_XML_CONTENT_TYPE    "text/xml; charset=\"utf-8\""
  76
  77 #define DAV_READ_BLOCKSIZE      2048    /* used for reading input blocks */
  78
  79 #ifdef WIN32
  80 typedef int ssize_t;
  81 #endif /* WIN32 */
  82
  83 #define DAV_RESPONSE_BODY_1     "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<HTML><HEAD>\n<TITLE>"
  84 #define DAV_RESPONSE_BODY_2     "</TITLE>\n</HEAD><BODY>\n<H1>"
  85 #define DAV_RESPONSE_BODY_3     "</H1>\n"
  86 #define DAV_RESPONSE_BODY_4     "</BODY></HTML>\n"
  87
  88 #define DAV_DO_COPY             0
  89 #define DAV_DO_MOVE             1
  90
  91
  92 #if 1
  93 #define DAV_DEBUG 1
  94 #define DEBUG_CR        "\n"
  95 #define DBG0(f)         ap_log_error(APLOG_MARK, \
  96                                 APLOG_ERR|APLOG_NOERRNO, 0, NULL, (f))
  97 #define DBG1(f,a1)      ap_log_error(APLOG_MARK, \
  98                                 APLOG_ERR|APLOG_NOERRNO, 0, NULL, f, a1)
  99 #define DBG2(f,a1,a2)   ap_log_error(APLOG_MARK, \
 100                                 APLOG_ERR|APLOG_NOERRNO, 0, NULL, f, a1, a2)
 101 #define DBG3(f,a1,a2,a3) ap_log_error(APLOG_MARK, \
 102                                APLOG_ERR|APLOG_NOERRNO, 0, NULL, f, a1, a2, a3)
 103 #else
 104 #undef DAV_DEBUG
 105 #define DEBUG_CR        ""
 106 #endif
 107
 108 #define DAV_INFINITY    INT_MAX /* for the Depth: header */
 109
 110
 111 /* --------------------------------------------------------------------
 112 **
 113 ** ERROR MANAGEMENT
 114 */
 115
 116 /*
 117 ** dav_error structure.
 118 **
 119 ** In most cases, mod_dav uses a pointer to a dav_error structure. If the
 120 ** pointer is NULL, then no error has occurred.
 121 **
 122 ** In certain cases, a dav_error structure is directly used. In these cases,
 123 ** a status value of 0 means that an error has not occurred.
 124 **
 125 ** Note: this implies that status != 0 whenever an error occurs.
 126 **
 127 ** The desc field is optional (it may be NULL). When NULL, it typically
 128 ** implies that Apache has a proper description for the specified status.
 129 */
 130 typedef struct dav_error {
 131     int status;                 /* suggested HTTP status (0 for no error) */
 132     int error_id;               /* DAV-specific error ID */
 133     const char *desc;           /* DAV:responsedescription and error log */
 134
 135     int save_errno;             /* copy of errno causing the error */
 136
 137     struct dav_error *prev;     /* previous error (in stack) */
 138
 139     /* deferred computation of the description */
 140     void (*compute_desc)(struct dav_error *err, ap_pool_t *p);
 141     int ctx_i;
 142     const char *ctx_s;
 143     void *ctx_p;
 144
 145 } dav_error;
 146
 147 /*
 148 ** Create a new error structure. save_errno will be filled with the current
 149 ** errno value.
 150 */
 151 dav_error *dav_new_error(ap_pool_t *p, int status, int error_id, const char *desc);
 152
 153 /*
 154 ** Push a new error description onto the stack of errors.
 155 **
 156 ** This function is used to provide an additional description to an existing
 157 ** error.
 158 **
 159 ** <status> should contain the caller's view of what the current status is,
 160 ** given the underlying error. If it doesn't have a better idea, then the
 161 ** caller should pass prev->status.
 162 **
 163 ** <error_id> can specify a new error_id since the topmost description has
 164 ** changed.
 165 */
 166 dav_error *dav_push_error(ap_pool_t *p, int status, int error_id, const char *desc,
 167                           dav_error *prev);
 168
 169
 170 /* error ID values... */
 171
 172 /* IF: header errors */
 173 #define DAV_ERR_IF_PARSE                100     /* general parsing error */
 174 #define DAV_ERR_IF_MULTIPLE_NOT         101     /* multiple "Not" found */
 175 #define DAV_ERR_IF_UNK_CHAR             102     /* unknown char in header */
 176 #define DAV_ERR_IF_ABSENT               103     /* no locktokens given */
 177 #define DAV_ERR_IF_TAGGED               104     /* in parsing tagged-list */
 178 #define DAV_ERR_IF_UNCLOSED_PAREN       105     /* in no-tagged-list */
 179
 180 /* Prop DB errors */
 181 #define DAV_ERR_PROP_BAD_MAJOR          200     /* major version was wrong */
 182 #define DAV_ERR_PROP_READONLY           201     /* prop is read-only */
 183 #define DAV_ERR_PROP_NO_DATABASE        202     /* writeable db not avail */
 184 #define DAV_ERR_PROP_NOT_FOUND          203     /* prop not found */
 185 #define DAV_ERR_PROP_BAD_LOCKDB         204     /* could not open lockdb */
 186 #define DAV_ERR_PROP_OPENING            205     /* problem opening propdb */
 187 #define DAV_ERR_PROP_EXEC               206     /* problem exec'ing patch */
 188
 189 /* Predefined DB errors */
 190 /* ### any to define?? */
 191
 192 /* Predefined locking system errors */
 193 #define DAV_ERR_LOCK_OPENDB             400     /* could not open lockdb */
 194 #define DAV_ERR_LOCK_NO_DB              401     /* no database defined */
 195 #define DAV_ERR_LOCK_CORRUPT_DB         402     /* DB is corrupt */
 196 #define DAV_ERR_LOCK_UNK_STATE_TOKEN    403     /* unknown State-token */
 197 #define DAV_ERR_LOCK_PARSE_TOKEN        404     /* bad opaquelocktoken */
 198 #define DAV_ERR_LOCK_SAVE_LOCK          405     /* err saving locks */
 199
 200 /*
 201 ** Some comments on Error ID values:
 202 **
 203 ** The numbers do not necessarily need to be unique. Uniqueness simply means
 204 ** that two errors that have not been predefined above can be distinguished
 205 ** from each other. At the moment, mod_dav does not use this distinguishing
 206 ** feature, but it could be used in the future to collapse <response> elements
 207 ** into groups based on the error ID (and associated responsedescription).
 208 **
 209 ** If a compute_desc is provided, then the error ID should be unique within
 210 ** the context of the compute_desc function (so the function can figure out
 211 ** what to filled into the desc).
 212 **
 213 ** Basically, subsystems can ignore defining new error ID values if they want
 214 ** to. The subsystems *do* need to return the predefined errors when
 215 ** appropriate, so that mod_dav can figure out what to do. Subsystems can
 216 ** simply leave the error ID field unfilled (zero) if there isn't an error
 217 ** that must be placed there.
 218 */
 219
 220
 221 /* --------------------------------------------------------------------
 222 **
 223 ** HOOK STRUCTURES
 224 **
 225 ** These are here for forward-declaration purposes. For more info, see
 226 ** the section title "HOOK HANDLING" for more information, plus each
 227 ** structure definition.
 228 */
 229
 230 /* forward-declare this structure */
 231 typedef struct dav_hooks_db dav_hooks_db;
 232 typedef struct dav_hooks_locks dav_hooks_locks;
 233 typedef struct dav_hooks_vsn dav_hooks_vsn;
 234 typedef struct dav_hooks_repository dav_hooks_repository;
 235 typedef struct dav_hooks_liveprop dav_hooks_liveprop;
 236
 237
 238 /* --------------------------------------------------------------------
 239 **
 240 ** RESOURCE HANDLING
 241 */
 242
 243 /*
 244 ** Resource Types:
 245 ** The base protocol defines only file and collection resources.
 246 ** The versioning protocol defines several additional resource types
 247 ** to represent artifacts of a version control system.
 248 */
 249 typedef enum {
 250     DAV_RESOURCE_TYPE_REGULAR,      /* file or collection, working resource
 251                                        or revision */
 252     DAV_RESOURCE_TYPE_REVISION,     /* explicit revision-id */
 253     DAV_RESOURCE_TYPE_HISTORY,      /* explicit history-id */
 254     DAV_RESOURCE_TYPE_WORKSPACE,    /* workspace */
 255     DAV_RESOURCE_TYPE_ACTIVITY,     /* activity */
 256     DAV_RESOURCE_TYPE_CONFIGURATION /* configuration */
 257 } dav_resource_type;
 258
 259 /*
 260 ** Opaque, repository-specific information for a resource.
 261 */
 262 typedef struct dav_resource_private dav_resource_private;
 263
 264 /* Resource descriptor, generated by a repository provider.
 265  * Note: the lock-null state is not explicitly represented here,
 266  * since it may be expensive to compute. Use dav_get_resource_state()
 267  * to determine whether a non-existent resource is a lock-null resource.
 268  */
 269 typedef struct dav_resource {
 270     dav_resource_type type;
 271
 272     int exists;         /* 0 => null resource */
 273     int collection;     /* 0 => file (if type == DAV_RESOURCE_TYPE_REGULAR) */
 274     int versioned;      /* 0 => unversioned */
 275     int working;        /* 0 => revision (if versioned) */
 276     int baselined;      /* 0 => not baselined */
 277
 278     const char *uri;    /* the URI for this resource */
 279
 280     dav_resource_private *info;
 281
 282     const dav_hooks_repository *hooks;  /* hooks used for this resource */
 283
 284 } dav_resource;
 285
 286 /*
 287 ** Lock token type. Lock providers define the details of a lock token.
 288 ** However, all providers are expected to at least be able to parse
 289 ** the "opaquelocktoken" scheme, which is represented by a uuid_t.
 290 */
 291 typedef struct dav_locktoken dav_locktoken;
 292
 293
 294 /* --------------------------------------------------------------------
 295 **
 296 ** BUFFER HANDLING
 297 **
 298 ** These buffers are used as a lightweight buffer reuse mechanism. Apache
 299 ** provides sub-pool creation and destruction to much the same effect, but
 300 ** the sub-pools are a bit more general and heavyweight than these buffers.
 301 */
 302
 303 /* buffer for reuse; can grow to accomodate needed size */
 304 typedef struct
 305 {
 306     size_t alloc_len;   /* how much has been allocated */
 307     size_t cur_len;     /* how much is currently being used */
 308     char *buf;          /* buffer contents */
 309 } dav_buffer;
 310 #define DAV_BUFFER_MINSIZE      256     /* minimum size for buffer */
 311 #define DAV_BUFFER_PAD          64      /* amount of pad when growing */
 312
 313 /* set the cur_len to the given size and ensure space is available */
 314 void dav_set_bufsize(ap_pool_t *p, dav_buffer *pbuf, size_t size);
 315
 316 /* initialize a buffer and copy the specified (null-term'd) string into it */
 317 void dav_buffer_init(ap_pool_t *p, dav_buffer *pbuf, const char *str);
 318
 319 /* check that the buffer can accomodate <extra_needed> more bytes */
 320 void dav_check_bufsize(ap_pool_t *p, dav_buffer *pbuf, size_t extra_needed);
 321
 322 /* append a string to the end of the buffer, adjust length */
 323 void dav_buffer_append(ap_pool_t *p, dav_buffer *pbuf, const char *str);
 324
 325 /* place a string on the end of the buffer, do NOT adjust length */
 326 void dav_buffer_place(ap_pool_t *p, dav_buffer *pbuf, const char *str);
 327
 328 /* place some memory on the end of a buffer; do NOT adjust length */
 329 void dav_buffer_place_mem(ap_pool_t *p, dav_buffer *pbuf, const void *mem,
 330                           size_t amt, size_t pad);
 331
 332
 333 /* --------------------------------------------------------------------
 334 **
 335 ** HANDY UTILITIES
 336 */
 337
 338 /* contains results from one of the getprop functions */
 339 typedef struct
 340 {
 341     ap_text * propstats;        /* <propstat> element text */
 342     ap_text * xmlns;            /* namespace decls for <response> elem */
 343 } dav_get_props_result;
 344
 345 /* holds the contents of a <response> element */
 346 typedef struct dav_response
 347 {
 348     const char *href;           /* always */
 349     const char *desc;           /* optional description at <response> level */
 350
 351     /* use status if propresult.propstats is NULL. */
 352     dav_get_props_result propresult;
 353
 354     int status;
 355
 356     struct dav_response *next;
 357 } dav_response;
 358
 359 typedef struct
 360 {
 361     request_rec *rnew;          /* new subrequest */
 362     dav_error err;              /* potential error response */
 363 } dav_lookup_result;
 364
 365
 366 dav_lookup_result dav_lookup_uri(const char *uri, request_rec *r);
 367
 368 /* ### this stuff is private to dav/fs/repos.c; move it... */
 369 /* format a time string (buf must be at least DAV_TIMEBUF_SIZE chars) */
 370 #define DAV_STYLE_ISO8601       1
 371 #define DAV_STYLE_RFC822        2
 372 #define DAV_TIMEBUF_SIZE        30
 373
 374 int dav_get_depth(request_rec *r, int def_depth);
 375
 376 int dav_validate_root(const ap_xml_doc *doc, const char *tagname);
 377 ap_xml_elem *dav_find_child(const ap_xml_elem *elem, const char *tagname);
 378
 379
 380 /* --------------------------------------------------------------------
 381 **
 382 ** DYNAMIC EXTENSIONS
 383 */
 384
 385 /* ### docco goes here... */
 386
 387
 388 /*
 389 ** This structure is used to define the runtime, per-directory/location
 390 ** operating context for a single provider.
 391 */
 392 typedef struct
 393 {
 394     int id;             /* provider ID */
 395
 396     void *m_context;    /* module-level context (i.e. managed globals) */
 397
 398     void *d_context;    /* per-directory context */
 399     ap_table_t *d_params;       /* per-directory DAV config parameters */
 400
 401     int *ns_map;        /* for LIVEPROP, map provider URI to global URI */
 402
 403 } dav_dyn_context;
 404
 405 /*
 406 ** This structure is used to specify a set of hooks and its associated
 407 ** context, on a per-directory/location basis.
 408 **
 409 ** Note: the context is assembled from various sources. dav_dyn_hooks
 410 ** structures will typically have the same pointer values within the
 411 ** context (e.g. ctx.m_context is shared across all providers in a module).
 412 */
 413 typedef struct dav_dyn_hooks
 414 {
 415     dav_dyn_context ctx;        /* context for this set of hooks */
 416     const void *hooks;          /* the type-specific hooks */
 417
 418     struct dav_dyn_hooks *next; /* next set of hooks, if applicable */
 419
 420 } dav_dyn_hooks;
 421
 422 /*
 423 ** These enumerated values define the different types of functionality that
 424 ** a provider can implement.
 425 */
 426 enum
 427 {
 428     DAV_DYN_TYPE_SENTINEL,
 429
 430     DAV_DYN_TYPE_PROPDB,        /* property database (1 per dir) */
 431     DAV_DYN_TYPE_LOCKS,         /* lock handling (1 per dir) */
 432     DAV_DYN_TYPE_QUERY_GRAMMAR, /* DASL search grammar (N per dir) */
 433     DAV_DYN_TYPE_ACL,           /* ACL handling (1 per dir) */
 434     DAV_DYN_TYPE_VSN,           /* versioning (1 per dir) */
 435     DAV_DYN_TYPE_REPOSITORY,    /* resource repository (1 per dir) */
 436     DAV_DYN_TYPE_LIVEPROP,      /* live property handler (N per dir) */
 437
 438     DAV_DYN_TYPE_MAX
 439 };
 440
 441 /*
 442 ** This structure defines a provider for a particular type of functionality.
 443 **
 444 ** The ID is private to a provider and can be used to differentiate between
 445 ** different subclasses of functionality which are implemented using the
 446 ** same set of hooks. For example, a hook function could perform two entirely
 447 ** different operations based on the ID which is passed.
 448 **
 449 ** is_active() is used by the system to determine whether a particular
 450 ** provider is "active" for the given context. It is possible that a provider
 451 ** is configured for a directory, but has not been enabled -- the is_active()
 452 ** function is used to determine that information.
 453 **
 454 ** ### is_active is not used right now
 455 **
 456 ** Note: dav_dyn_provider structures are always treated as "const" by mod_dav.
 457 */
 458 typedef struct dav_dyn_provider
 459 {
 460     int id;                     /* provider ID */
 461
 462     int type;                   /* provider's functionality type */
 463     const void *hooks;          /* pointer to type-specific hooks */
 464
 465     int (*is_active)(dav_dyn_context *ctx, int id);
 466
 467 } dav_dyn_provider;
 468
 469 #define DAV_DYN_END_MARKER      { 0, DAV_DYN_TYPE_SENTINEL, NULL, NULL }
 470
 471 /*
 472 ** This structure defines a module (a set of providers).
 473 **
 474 ** The friendly name should be a single word. It is used with the "DAV"
 475 ** directive to specify the module to use for a particular directory/location.
 476 **
 477 ** The module_open/close functions are used to initialize per-module "global"
 478 ** data. The functions are expected to update ctx->m_context.
 479 **
 480 ** ### module_open/close are not used at the moment
 481 ** ### dir_* are not well-defined, nor are they used
 482 **
 483 ** Note: The DAV_DYN_VERSION specifies the version of the dav_dyn_module
 484 **       structure itself. It will be updated if changes in the structure
 485 **       are made. There are no provisions for forward or backward
 486 **       compatible changes.
 487 **
 488 ** Note: dav_dyn_module structures are always treated as "const" by mod_dav.
 489 */
 490 typedef struct
 491 {
 492     int magic;
 493 #define DAV_DYN_MAGIC           0x44415621      /* "DAV!" */
 494
 495     int version;
 496 #define DAV_DYN_VERSION         1               /* must match exactly */
 497
 498     const char *name;                           /* friendly name */
 499
 500     int (*module_open)(dav_dyn_context *ctx);
 501     int (*module_close)(dav_dyn_context *ctx);
 502
 503     int (*dir_open)(dav_dyn_context *ctx);
 504     int (*dir_param)(dav_dyn_context *ctx, const char *param_name,
 505                      const char *param_value);
 506     int (*dir_merge)(dav_dyn_context *base, dav_dyn_context *overrides,
 507                      dav_dyn_context *result);
 508     int (*dir_close)(dav_dyn_context *ctx);
 509
 510     const dav_dyn_provider *providers;          /* providers in this module */
 511
 512 } dav_dyn_module;
 513
 514 int dav_load_module(const char *name, const char *module_sym,
 515                     const char *filename);
 516 const dav_dyn_module *dav_find_module(const char *name);
 517
 518 /*
 519 ** Various management functions.
 520 **
 521 ** NOTE: the pool should be the "configuration pool"
 522 */
 523 void dav_process_builtin_modules(ap_pool_t *p);
 524 void dav_process_module(ap_pool_t *p, const dav_dyn_module *mod);
 525
 526 int * dav_collect_liveprop_uris(ap_pool_t *p, const dav_hooks_liveprop *hooks);
 527 extern ap_array_header_t *dav_liveprop_uris;
 528
 529 void *dav_prepare_scan(ap_pool_t *p, const dav_dyn_module *mod);
 530 int dav_scan_providers(void *ctx,
 531                        const dav_dyn_provider **provider,
 532                        dav_dyn_hooks *output);
 533
 534 /* handy macros to assist with dav_dyn_hooks.hooks usage */
 535 #define DAV_AS_HOOKS_PROPDB(ph)         ((const dav_hooks_db *)((ph)->hooks))
 536 #define DAV_AS_HOOKS_LOCKS(ph)          ((const dav_hooks_locks *)((ph)->hooks))
 537 #define DAV_AS_HOOKS_QUERY_GRAMMAR(ph)  ((void *)((ph)->hooks))
 538 #define DAV_AS_HOOKS_ACL(ph)            ((void *)((ph)->hooks))
 539 #define DAV_AS_HOOKS_VSN(ph)            ((const dav_hooks_vsn *)((ph)->hooks))
 540 #define DAV_AS_HOOKS_REPOSITORY(ph)     ((const dav_hooks_repository *)((ph)->hooks))
 541 #define DAV_AS_HOOKS_LIVEPROP(ph)       ((const dav_hooks_liveprop *)((ph)->hooks))
 542
 543 /* get provider hooks, given a request record */
 544 const dav_dyn_hooks *dav_get_provider_hooks(request_rec *r, int provider_type);
 545
 546 #define DAV_GET_HOOKS_PROPDB(r)         DAV_AS_HOOKS_PROPDB(dav_get_provider_hooks(r, DAV_DYN_TYPE_PROPDB))
 547 #define DAV_GET_HOOKS_LOCKS(r)          DAV_AS_HOOKS_LOCKS(dav_get_provider_hooks(r, DAV_DYN_TYPE_LOCKS))
 548 #define DAV_GET_HOOKS_QUERY_GRAMMAR(r)  DAV_AS_HOOKS_QUERY_GRAMMAR(dav_get_provider_hooks(r, DAV_DYN_TYPE_QUERY_GRAMMAR))
 549 #define DAV_GET_HOOKS_ACL(r)            DAV_AS_HOOKS_ACL(dav_get_provider_hooks(r, DAV_DYN_TYPE_ACL))
 550 #define DAV_GET_HOOKS_VSN(r)            DAV_AS_HOOKS_VSN(dav_get_provider_hooks(r, DAV_DYN_TYPE_VSN))
 551 #define DAV_GET_HOOKS_REPOSITORY(r)     DAV_AS_HOOKS_REPOSITORY(dav_get_provider_hooks(r, DAV_DYN_TYPE_REPOSITORY))
 552 #define DAV_GET_HOOKS_LIVEPROP(r)       DAV_AS_HOOKS_LIVEPROP(dav_get_provider_hooks(r, DAV_DYN_TYPE_LIVEPROP))
 553
 554
 555 /* --------------------------------------------------------------------
 556 **
 557 ** IF HEADER PROCESSING
 558 **
 559 ** Here is the definition of the If: header from RFC 2518, S9.4:
 560 **
 561 **    If = "If" ":" (1*No-tag-list | 1*Tagged-list)
 562 **    No-tag-list = List
 563 **    Tagged-list = Resource 1*List
 564 **    Resource = Coded-URL
 565 **    List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")"
 566 **    State-token = Coded-URL
 567 **    Coded-URL = "<" absoluteURI ">"        ; absoluteURI from RFC 2616
 568 **
 569 ** List corresponds to dav_if_state_list. No-tag-list corresponds to
 570 ** dav_if_header with uri==NULL. Tagged-list corresponds to a sequence of
 571 ** dav_if_header structures with (duplicate) uri==Resource -- one
 572 ** dav_if_header per state_list. A second Tagged-list will start a new
 573 ** sequence of dav_if_header structures with the new URI.
 574 **
 575 ** A summary of the semantics, mapped into our structures:
 576 **    - Chained dav_if_headers: OR
 577 **    - Chained dav_if_state_lists: AND
 578 **    - NULL uri matches all resources
 579 */
 580
 581 typedef enum
 582 {
 583     dav_if_etag,
 584     dav_if_opaquelock
 585 } dav_if_state_type;
 586
 587 typedef struct dav_if_state_list
 588 {
 589     dav_if_state_type type;
 590
 591     int condition;
 592 #define DAV_IF_COND_NORMAL      0
 593 #define DAV_IF_COND_NOT         1       /* "Not" was applied */
 594
 595     const char *etag;   /* etag */
 596     dav_locktoken *locktoken;   /* locktoken */
 597
 598     struct dav_if_state_list *next;
 599 } dav_if_state_list;
 600
 601 typedef struct dav_if_header
 602 {
 603     const char *uri;
 604     size_t uri_len;
 605     struct dav_if_state_list *state;
 606     struct dav_if_header *next;
 607
 608     int dummy_header;   /* used internally by the lock/etag validation */
 609 } dav_if_header;
 610
 611 typedef struct dav_locktoken_list
 612 {
 613     dav_locktoken *locktoken;
 614     struct dav_locktoken_list *next;
 615 } dav_locktoken_list;
 616
 617 dav_error * dav_get_locktoken_list(request_rec *r, dav_locktoken_list **ltl);
 618
 619
 620 /* --------------------------------------------------------------------
 621 **
 622 ** LIVE PROPERTY HANDLING
 623 */
 624
 625 typedef enum {
 626     DAV_PROP_INSERT_NOTME,      /* prop not defined by this provider */
 627     DAV_PROP_INSERT_NOTDEF,     /* property is defined by this provider,
 628                                    but nothing was inserted because the
 629                                    (live) property is not defined for this
 630                                    resource (it may be present as a dead
 631                                    property). */
 632     DAV_PROP_INSERT_NAME,       /* a property name (empty elem) was
 633                                    inserted into the text block */
 634     DAV_PROP_INSERT_VALUE       /* a property name/value pair was inserted
 635                                    into the text block */
 636 } dav_prop_insert;
 637
 638 typedef enum {
 639     DAV_PROP_RW_NOTME,          /* not my property */
 640     DAV_PROP_RW_NO,             /* property is NOT writeable */
 641     DAV_PROP_RW_YES             /* property IS writeable */
 642 } dav_prop_rw;
 643
 644 /* opaque type for PROPPATCH rollback information */
 645 typedef struct dav_liveprop_rollback dav_liveprop_rollback;
 646
 647 struct dav_hooks_liveprop
 648 {
 649     /*
 650     ** This URI is returned in the DAV: header to let clients know what
 651     ** sets of live properties are supported by the installation. mod_dav
 652     ** will place open/close angle brackets around this value (much like
 653     ** a Coded-URL); quotes and brackets should not be in the value.
 654     **
 655     ** Example:    http://apache.org/dav/props/
 656     **
 657     ** (of course, use your own domain to ensure a unique value)
 658     */
 659     const char * propset_uri;
 660
 661     /*
 662     ** Find a property, returning a non-zero, unique, opaque identifier.
 663     **
 664     ** NOTE: Providers must ensure this identifier is universally unique.
 665     **       See the registration table below.
 666     ** ### it would be nice to avoid this uniqueness constraint. however,
 667     ** ### that would mean our xml_elem annotation concept would need to
 668     ** ### change (w.r.t. the fact that it acts as a cache for find_prop).
 669     **
 670     ** Returns 0 if the property is not defined by this provider.
 671     */
 672     int (*find_prop)(const char *ns_uri, const char *name);
 673
 674     /*
 675     ** Insert a property name/value into a text block. The property to
 676     ** insert is identified by the propid value. Providers should return
 677     ** DAV_PROP_INSERT_NOTME if they do not define the specified propid.
 678     ** If insvalue is true, then the property's value should be inserted;
 679     ** otherwise, an empty element (ie. just the prop's name) should be
 680     ** inserted.
 681     **
 682     ** Returns one of DAV_PROP_INSERT_* based on what happened.
 683     **
 684     ** ### we may need more context... ie. the lock database
 685     */
 686     dav_prop_insert (*insert_prop)(const dav_resource *resource,
 687                                    int propid, int insvalue,
 688                                    const int *ns_map, ap_text_header *phdr);
 689
 690     /*
 691     ** Insert all known/defined property names (and values). This is
 692     ** similar to insert_prop, but *all* properties will be inserted
 693     ** rather than specific, individual properties.
 694     */
 695     void (*insert_all)(const dav_resource *resource, int insvalue,
 696                        const int *ns_map, ap_text_header *phdr);
 697
 698     /*
 699     ** Determine whether a given property is writeable.
 700     **
 701     ** ### we may want a different semantic. i.e. maybe it should be
 702     ** ### "can we write <value> into this property?"
 703     **
 704     ** Returns appropriate read/write status.
 705     */
 706     dav_prop_rw (*is_writeable)(const dav_resource *resource, int propid);
 707
 708     /*
 709     ** This member defines the set of namespace URIs that the provider
 710     ** uses for its properties. When insert_all is called, it will be
 711     ** passed a list of integers that map from indices into this list
 712     ** to namespace IDs for output generation.
 713     **
 714     ** The last entry in this list should be a NULL value (sentinel).
 715     */
 716     const char * const * namespace_uris;
 717
 718     /*
 719     ** ### this is not the final design. we want an open-ended way for
 720     ** ### liveprop providers to attach *new* properties. To this end,
 721     ** ### we'll have a "give me a list of the props you define", a way
 722     ** ### to check for a prop's existence, a way to validate a set/remove
 723     ** ### of a prop, and a way to execute/commit/rollback that change.
 724     */
 725
 726     /*
 727     ** Validate that the live property can be assigned a value, and that
 728     ** the provided value is valid.
 729     **
 730     ** elem will point to the XML element that names the property. For
 731     ** example:
 732     **     <lp1:executable>T</lp1:executable>
 733     **
 734     ** The provider can access the cdata fields and the child elements
 735     ** to extract the relevant pieces.
 736     **
 737     ** operation is one of DAV_PROP_OP_SET or _DELETE.
 738     **
 739     ** The provider may return a value in *context which will be passed
 740     ** to each of the exec/commit/rollback functions. For example, this
 741     ** may contain an internal value which has been processed from the
 742     ** input element.
 743     **
 744     ** The provider must set defer_to_dead to true (non-zero) or false.
 745     ** If true, then the set/remove is deferred to the dead property
 746     ** database. Note: it will be set to zero on entry.
 747     */
 748     dav_error * (*patch_validate)(const dav_resource *resource,
 749                                   const ap_xml_elem *elem,
 750                                   int operation,
 751                                   void **context,
 752                                   int *defer_to_dead);
 753
 754     /* ### doc... */
 755     dav_error * (*patch_exec)(dav_resource *resource,
 756                               const ap_xml_elem *elem,
 757                               int operation,
 758                               void *context,
 759                               dav_liveprop_rollback **rollback_ctx);
 760
 761     /* ### doc... */
 762     void (*patch_commit)(dav_resource *resource,
 763                          int operation,
 764                          void *context,
 765                          dav_liveprop_rollback *rollback_ctx);
 766
 767     /* ### doc... */
 768     dav_error * (*patch_rollback)(dav_resource *resource,
 769                                   int operation,
 770                                   void *context,
 771                                   dav_liveprop_rollback *rollback_ctx);
 772 };
 773
 774 /*
 775 ** Property Identifier Registration
 776 **
 777 ** At the moment, mod_dav requires live property providers to ensure that
 778 ** each property returned has a unique value. For now, this is done through
 779 ** central registration (there are no known providers other than the default,
 780 ** so this remains manageable).
 781 **
 782 ** WARNING: the TEST ranges should never be "shipped".
 783 */
 784 #define DAV_PROPID_CORE         10000   /* ..10099. defined by mod_dav */
 785 #define DAV_PROPID_FS           10100   /* ..10299.
 786                                            mod_dav filesystem provider. */
 787 #define DAV_PROPID_TEST1        10300   /* ..10399 */
 788 #define DAV_PROPID_TEST2        10400   /* ..10499 */
 789 #define DAV_PROPID_TEST3        10500   /* ..10599 */
 790 /* Next: 10600 */
 791
 792
 793 /* --------------------------------------------------------------------
 794 **
 795 ** DATABASE FUNCTIONS
 796 */
 797
 798 typedef struct dav_db dav_db;
 799 typedef struct
 800 {
 801     char *dptr;
 802     size_t dsize;
 803 } dav_datum;
 804
 805 /* hook functions to enable pluggable databases */
 806 struct dav_hooks_db
 807 {
 808     dav_error * (*open)(ap_pool_t *p, const dav_resource *resource, int ro,
 809                         dav_db **pdb);
 810     void (*close)(dav_db *db);
 811
 812     /*
 813     ** Fetch the value from the database. If the value does not exist,
 814     ** then *pvalue should be zeroed.
 815     **
 816     ** Note: it is NOT an error for the key/value pair to not exist.
 817     */
 818     dav_error * (*fetch)(dav_db *db, dav_datum key, dav_datum *pvalue);
 819
 820     dav_error * (*store)(dav_db *db, dav_datum key, dav_datum value);
 821     dav_error * (*remove)(dav_db *db, dav_datum key);
 822
 823     /* returns 1 if the record specified by "key" exists; 0 otherwise */
 824     int (*exists)(dav_db *db, dav_datum key);
 825
 826     dav_error * (*firstkey)(dav_db *db, dav_datum *pkey);
 827     dav_error * (*nextkey)(dav_db *db, dav_datum *pkey);
 828
 829     void (*freedatum)(dav_db *db, dav_datum data);
 830 };
 831
 832
 833 /* --------------------------------------------------------------------
 834 **
 835 ** LOCK FUNCTIONS
 836 */
 837
 838 /* Used to represent a Timeout header of "Infinity" */
 839 #define DAV_TIMEOUT_INFINITE 0
 840
 841 time_t dav_get_timeout(request_rec *r);
 842
 843 /*
 844 ** Opaque, repository-specific information for a lock database.
 845 */
 846 typedef struct dav_lockdb_private dav_lockdb_private;
 847
 848 /*
 849 ** Opaque, repository-specific information for a lock record.
 850 */
 851 typedef struct dav_lock_private dav_lock_private;
 852
 853 /*
 854 ** Lock database type. Lock providers are urged to implement a "lazy" open, so
 855 ** doing an "open" is cheap until something is actually needed from the DB.
 856 */
 857 typedef struct
 858 {
 859     const dav_hooks_locks *hooks;       /* the hooks used for this lockdb */
 860     int ro;                             /* was it opened readonly? */
 861
 862     dav_lockdb_private *info;
 863
 864 } dav_lockdb;
 865
 866 typedef enum {
 867     DAV_LOCKSCOPE_UNKNOWN,
 868     DAV_LOCKSCOPE_EXCLUSIVE,
 869     DAV_LOCKSCOPE_SHARED
 870 } dav_lock_scope;
 871
 872 typedef enum {
 873     DAV_LOCKTYPE_UNKNOWN,
 874     DAV_LOCKTYPE_WRITE
 875 } dav_lock_type;
 876
 877 typedef enum {
 878     DAV_LOCKREC_DIRECT,                 /* lock asserted on this resource */
 879     DAV_LOCKREC_INDIRECT,               /* lock inherited from a parent */
 880     DAV_LOCKREC_INDIRECT_PARTIAL        /* most info is not filled in */
 881 } dav_lock_rectype;
 882
 883 /*
 884 ** dav_lock: hold information about a lock on a resource.
 885 **
 886 ** This structure is used for both direct and indirect locks. A direct lock
 887 ** is a lock applied to a specific resource by the client. An indirect lock
 888 ** is one that is inherited from a parent resource by virtue of a non-zero
 889 ** Depth: header when the lock was applied.
 890 **
 891 ** mod_dav records both types of locks in the lock database, managing their
 892 ** addition/removal as resources are moved about the namespace.
 893 **
 894 ** Note that the lockdb is free to marshal this structure in any form that
 895 ** it likes.
 896 **
 897 ** For a "partial" lock, the <rectype> and <locktoken> fields must be filled
 898 ** in. All other (user) fields should be zeroed. The lock provider will
 899 ** usually fill in the <info> field, and the <next> field may be used to
 900 ** construct a list of partial locks.
 901 **
 902 ** The lock provider MUST use the info field to store a value such that a
 903 ** dav_lock structure can locate itself in the underlying lock database.
 904 ** This requirement is needed for refreshing: when an indirect dav_lock is
 905 ** refreshed, its reference to the direct lock does not specify the direct's
 906 ** resource, so the only way to locate the (refreshed, direct) lock in the
 907 ** database is to use the info field.
 908 **
 909 ** Note that <is_locknull> only refers to the resource where this lock was
 910 ** found.
 911 ** ### hrm. that says the abstraction is wrong. is_locknull may disappear.
 912 */
 913 typedef struct dav_lock
 914 {
 915     dav_lock_rectype rectype;   /* type of lock record */
 916     int is_locknull;            /* lock establishes a locknull resource */
 917
 918     /* ### put the resource in here? */
 919
 920     dav_lock_scope scope;       /* scope of the lock */
 921     dav_lock_type type;         /* type of lock */
 922     int depth;                  /* depth of the lock */
 923     time_t timeout;             /* when the lock will timeout */
 924
 925     const dav_locktoken *locktoken;     /* the token that was issued */
 926
 927     const char *owner;          /* (XML) owner of the lock */
 928     const char *auth_user;      /* auth'd username owning lock */
 929
 930     dav_lock_private *info;     /* private to the lockdb */
 931
 932     struct dav_lock *next;      /* for managing a list of locks */
 933 } dav_lock;
 934
 935 /* Property-related public lock functions */
 936 const char *dav_lock_get_activelock(request_rec *r, dav_lock *locks,
 937                                     dav_buffer *pbuf);
 938
 939 /* LockDB-related public lock functions */
 940 const char *dav_get_lockdb_path(const request_rec *r);
 941 dav_error * dav_lock_parse_lockinfo(request_rec *r,
 942                                     const dav_resource *resrouce,
 943                                     dav_lockdb *lockdb,
 944                                     const ap_xml_doc *doc,
 945                                     dav_lock **lock_request);
 946 int dav_unlock(request_rec *r, const dav_resource *resource,
 947                const dav_locktoken *locktoken);
 948 dav_error * dav_add_lock(request_rec *r, const dav_resource *resource,
 949                          dav_lockdb *lockdb, dav_lock *request,
 950                          dav_response **response);
 951 dav_error * dav_notify_created(request_rec *r,
 952                                dav_lockdb *lockdb,
 953                                const dav_resource *resource,
 954                                int resource_state,
 955                                int depth);
 956
 957 dav_error * dav_lock_query(dav_lockdb *lockdb, const dav_resource *resource,
 958                            dav_lock **locks);
 959
 960 dav_error * dav_validate_request(request_rec *r, dav_resource *resource,
 961                                  int depth, dav_locktoken *locktoken,
 962                                  dav_response **response, int flags,
 963                                  dav_lockdb *lockdb);
 964 /*
 965 ** flags:
 966 **    0x0F -- reserved for <dav_lock_scope> values
 967 **
 968 **    other flags, detailed below
 969 */
 970 #define DAV_VALIDATE_RESOURCE   0x0010  /* validate just the resource */
 971 #define DAV_VALIDATE_PARENT     0x0020  /* validate resource AND its parent */
 972 #define DAV_VALIDATE_ADD_LD     0x0040  /* add DAV:lockdiscovery into
 973                                            the 424 DAV:response */
 974 #define DAV_VALIDATE_USE_424    0x0080  /* return 424 status, not 207 */
 975 #define DAV_VALIDATE_IS_PARENT  0x0100  /* for internal use */
 976
 977 /* Lock-null related public lock functions */
 978 int dav_get_resource_state(request_rec *r, const dav_resource *resource);
 979
 980 /* Lock provider hooks. Locking is optional, so there may be no
 981  * lock provider for a given repository.
 982  */
 983 struct dav_hooks_locks
 984 {
 985     /* Return the supportedlock property for this provider */
 986     /* ### maybe this should take a resource argument? */
 987     const char * (*get_supportedlock)(void);
 988
 989     /* Parse a lock token URI, returning a lock token object allocated
 990      * in the given pool.
 991      */
 992     dav_error * (*parse_locktoken)(
 993         ap_pool_t *p,
 994         const char *char_token,
 995         dav_locktoken **locktoken_p
 996     );
 997
 998     /* Format a lock token object into a URI string, allocated in
 999      * the given pool.
1000      *
1001      * Always returns non-NULL.
1002      */
1003     const char * (*format_locktoken)(
1004         ap_pool_t *p,
1005         const dav_locktoken *locktoken
1006     );
1007
1008     /* Compare two lock tokens.
1009      *
1010      * Result < 0  => lt1 < lt2
1011      * Result == 0 => lt1 == lt2
1012      * Result > 0  => lt1 > lt2
1013      */
1014     int (*compare_locktoken)(
1015         const dav_locktoken *lt1,
1016         const dav_locktoken *lt2
1017     );
1018
1019     /* Open the provider's lock database.
1020      *
1021      * The provider may or may not use a "real" database for locks
1022      * (a lock could be an attribute on a resource, for example).
1023      *
1024      * The provider may choose to use the value of the DAVLockDB directive
1025      * (as returned by dav_get_lockdb_path()) to decide where to place
1026      * any storage it may need.
1027      *
1028      * The request storage pool should be associated with the lockdb,
1029      * so it can be used in subsequent operations.
1030      *
1031      * If ro != 0, only readonly operations will be performed.
1032      * If force == 0, the open can be "lazy"; no subsequent locking operations
1033      * may occur.
1034      * If force != 0, locking operations will definitely occur.
1035      */
1036     dav_error * (*open_lockdb)(
1037         request_rec *r,
1038         int ro,
1039         int force,
1040         dav_lockdb **lockdb
1041     );
1042
1043     /* Indicates completion of locking operations */
1044     void (*close_lockdb)(
1045         dav_lockdb *lockdb
1046     );
1047
1048     /* Take a resource out of the lock-null state. */
1049     dav_error * (*remove_locknull_state)(
1050         dav_lockdb *lockdb,
1051         const dav_resource *resource
1052     );
1053
1054     /*
1055     ** Create a (direct) lock structure for the given resource. A locktoken
1056     ** will be created.
1057     **
1058     ** The lock provider may store private information into lock->info.
1059     */
1060     dav_error * (*create_lock)(dav_lockdb *lockdb,
1061                                const dav_resource *resource,
1062                                dav_lock **lock);
1063
1064     /*
1065     ** Get the locks associated with the specified resource.
1066     **
1067     ** If resolve_locks is true (non-zero), then any indirect locks are
1068     ** resolved to their actual, direct lock (i.e. the reference to followed
1069     ** to the original lock).
1070     **
1071     ** The locks, if any, are returned as a linked list in no particular
1072     ** order. If no locks are present, then *locks will be NULL.
1073     */
1074     dav_error * (*get_locks)(dav_lockdb *lockdb,
1075                              const dav_resource *resource,
1076                              int calltype,
1077                              dav_lock **locks);
1078
1079 #define DAV_GETLOCKS_RESOLVED   0       /* resolve indirects to directs */
1080 #define DAV_GETLOCKS_PARTIAL    1       /* leave indirects partially filled */
1081 #define DAV_GETLOCKS_COMPLETE   2       /* fill out indirect locks */
1082
1083     /*
1084     ** Find a particular lock on a resource (specified by its locktoken).
1085     **
1086     ** *lock will be set to NULL if the lock is not found.
1087     **
1088     ** Note that the provider can optimize the unmarshalling -- only one
1089     ** lock (or none) must be constructed and returned.
1090     **
1091     ** If partial_ok is true (non-zero), then an indirect lock can be
1092     ** partially filled in. Otherwise, another lookup is done and the
1093     ** lock structure will be filled out as a DAV_LOCKREC_INDIRECT.
1094     */
1095     dav_error * (*find_lock)(dav_lockdb *lockdb,
1096                              const dav_resource *resource,
1097                              const dav_locktoken *locktoken,
1098                              int partial_ok,
1099                              dav_lock **lock);
1100
1101     /*
1102     ** Quick test to see if the resource has *any* locks on it.
1103     **
1104     ** This is typically used to determine if a non-existent resource
1105     ** has a lock and is (therefore) a locknull resource.
1106     **
1107     ** WARNING: this function may return TRUE even when timed-out locks
1108     **          exist (i.e. it may not perform timeout checks).
1109     */
1110     dav_error * (*has_locks)(dav_lockdb *lockdb,
1111                              const dav_resource *resource,
1112                              int *locks_present);
1113
1114     /*
1115     ** Append the specified lock(s) to the set of locks on this resource.
1116     **
1117     ** If "make_indirect" is true (non-zero), then the specified lock(s)
1118     ** should be converted to an indirect lock (if it is a direct lock)
1119     ** before appending. Note that the conversion to an indirect lock does
1120     ** not alter the passed-in lock -- the change is internal the
1121     ** append_locks function.
1122     **
1123     ** Multiple locks are specified using the lock->next links.
1124     */
1125     dav_error * (*append_locks)(dav_lockdb *lockdb,
1126                                 const dav_resource *resource,
1127                                 int make_indirect,
1128                                 const dav_lock *lock);
1129
1130     /*
1131     ** Remove any lock that has the specified locktoken.
1132     **
1133     ** If locktoken == NULL, then ALL locks are removed.
1134     */
1135     dav_error * (*remove_lock)(dav_lockdb *lockdb,
1136                                const dav_resource *resource,
1137                                const dav_locktoken *locktoken);
1138
1139     /*
1140     ** Refresh all locks, found on the specified resource, which has a
1141     ** locktoken in the provided list.
1142     **
1143     ** If the lock is indirect, then the direct lock is referenced and
1144     ** refreshed.
1145     **
1146     ** Each lock that is updated is returned in the <locks> argument.
1147     ** Note that the locks will be fully resolved.
1148     */
1149     dav_error * (*refresh_locks)(dav_lockdb *lockdb,
1150                                  const dav_resource *resource,
1151                                  const dav_locktoken_list *ltl,
1152                                  time_t new_time,
1153                                  dav_lock **locks);
1154
1155     /*
1156     ** Look up the resource associated with a particular locktoken.
1157     **
1158     ** The search begins at the specified <start_resource> and the lock
1159     ** specified by <locktoken>.
1160     **
1161     ** If the resource/token specifies an indirect lock, then the direct
1162     ** lock will be looked up, and THAT resource will be returned. In other
1163     ** words, this function always returns the resource where a particular
1164     ** lock (token) was asserted.
1165     **
1166     ** NOTE: this function pointer is allowed to be NULL, indicating that
1167     **       the provider does not support this type of functionality. The
1168     **       caller should then traverse up the repository hierarchy looking
1169     **       for the resource defining a lock with this locktoken.
1170     */
1171     dav_error * (*lookup_resource)(dav_lockdb *lockdb,
1172                                    const dav_locktoken *locktoken,
1173                                    const dav_resource *start_resource,
1174                                    const dav_resource **resource);
1175 };
1176
1177 /* what types of resources can be discovered by dav_get_resource_state() */
1178 #define DAV_RESOURCE_LOCK_NULL  10      /* resource lock-null */
1179 #define DAV_RESOURCE_NULL       11      /* resource null */
1180 #define DAV_RESOURCE_EXISTS     12      /* resource exists */
1181 #define DAV_RESOURCE_ERROR      13      /* an error occurred */
1182
1183
1184 /* --------------------------------------------------------------------
1185 **
1186 ** PROPERTY HANDLING
1187 */
1188
1189 typedef struct dav_propdb dav_propdb;
1190
1191
1192 dav_error *dav_open_propdb(
1193     request_rec *r,
1194     dav_lockdb *lockdb,
1195     dav_resource *resource,
1196     int ro,
1197     ap_array_header_t *ns_xlate,
1198     dav_propdb **propdb);
1199
1200 void dav_close_propdb(dav_propdb *db);
1201
1202 dav_get_props_result dav_get_props(
1203     dav_propdb *db,
1204     ap_xml_doc *doc);
1205
1206 dav_get_props_result dav_get_allprops(
1207     dav_propdb *db,
1208     int getvals);
1209
1210 /*
1211 ** 3-phase property modification.
1212 **
1213 **   1) validate props. readable? unlocked? ACLs allow access?
1214 **   2) execute operation (set/delete)
1215 **   3) commit or rollback
1216 **
1217 ** ### eventually, auth must be available. a ref to the request_rec (which
1218 ** ### contains the auth info) should be in the shared context struct.
1219 **
1220 ** Each function may alter the error values and information contained within
1221 ** the context record. This should be done as an "increasing" level of
1222 ** error, rather than overwriting any previous error.
1223 **
1224 ** Note that commit() cannot generate errors. It should simply free the
1225 ** rollback information.
1226 **
1227 ** rollback() may generate additional errors because the rollback operation
1228 ** can sometimes fail(!).
1229 **
1230 ** The caller should allocate an array of these, one per operation. It should
1231 ** be zero-initialized, then the db, operation, and prop fields should be
1232 ** filled in before calling dav_prop_validate. Note that the set/delete
1233 ** operations are order-dependent. For a given (logical) context, the same
1234 ** pointer must be passed to each phase.
1235 **
1236 ** error_type is an internal value, but will have the same numeric value
1237 ** for each possible "desc" value. This allows the caller to group the
1238 ** descriptions via the error_type variable, rather than through string
1239 ** comparisons. Note that "status" does not provide enough granularity to
1240 ** differentiate/group the "desc" values.
1241 **
1242 ** Note that the propdb will maintain some (global) context across all
1243 ** of the property change contexts. This implies that you can have only
1244 ** one open transaction per propdb.
1245 */
1246 typedef struct dav_prop_ctx
1247 {
1248     dav_propdb *propdb;
1249
1250     int operation;
1251 #define DAV_PROP_OP_SET         1       /* set a property value */
1252 #define DAV_PROP_OP_DELETE      2       /* delete a prop value */
1253 /* ### add a GET? */
1254
1255     ap_xml_elem *prop;                  /* property to affect */
1256
1257     dav_error *err;                     /* error (if any) */
1258
1259     /* private items to the propdb */
1260     int is_liveprop;
1261     void *liveprop_ctx;
1262     struct dav_rollback_item *rollback; /* optional rollback info */
1263
1264     /* private to mod_dav.c */
1265     request_rec *r;
1266
1267 } dav_prop_ctx;
1268
1269 void dav_prop_validate(dav_prop_ctx *ctx);
1270 void dav_prop_exec(dav_prop_ctx *ctx);
1271 void dav_prop_commit(dav_prop_ctx *ctx);
1272 void dav_prop_rollback(dav_prop_ctx *ctx);
1273
1274 #define DAV_PROP_CTX_HAS_ERR(dpc)       ((dpc).err && (dpc).err->status >= 300)
1275
1276
1277 /* --------------------------------------------------------------------
1278 **
1279 ** WALKER STRUCTURE
1280 */
1281
1282 /* private, opaque info structure for repository walking context */
1283 typedef struct dav_walker_private dav_walker_private;
1284
1285 /* directory tree walking context */
1286 typedef struct dav_walker_ctx
1287 {
1288     int walk_type;
1289 #define DAV_WALKTYPE_AUTH       1       /* limit to authorized files */
1290 #define DAV_WALKTYPE_ALL        2       /* walk normal files */
1291 #define DAV_WALKTYPE_HIDDEN     4       /* walk hidden files */
1292 #define DAV_WALKTYPE_LOCKNULL   8       /* walk locknull resources */
1293
1294     int postfix;                /* call func for dirs after files */
1295
1296     dav_error * (*func)(struct dav_walker_ctx *ctx, int calltype);
1297 #define DAV_CALLTYPE_MEMBER     1       /* called for a member resource */
1298 #define DAV_CALLTYPE_COLLECTION 2       /* called for a collection */
1299 #define DAV_CALLTYPE_LOCKNULL   3       /* called for a locknull resource */
1300 #define DAV_CALLTYPE_POSTFIX    4       /* postfix call for a collection */
1301
1302     ap_pool_t *pool;
1303
1304     request_rec *r;                     /* original request */
1305     dav_buffer uri;                     /* current URI */
1306     const dav_resource *resource;       /* current resource */
1307     const dav_resource *res2;           /* optional secondary resource */
1308
1309     const dav_resource *root;           /* RO: root resource of the walk */
1310
1311     dav_lockdb *lockdb;
1312
1313     dav_response *response;             /* OUT: multistatus responses */
1314
1315     /* for PROPFIND operations */
1316     ap_xml_doc *doc;
1317     int propfind_type;
1318 #define DAV_PROPFIND_IS_ALLPROP         1
1319 #define DAV_PROPFIND_IS_PROPNAME        2
1320 #define DAV_PROPFIND_IS_PROP            3
1321
1322     ap_text *propstat_404;      /* (cached) propstat giving a 404 error */
1323
1324     /* for COPY and MOVE operations */
1325     int is_move;
1326     dav_buffer work_buf;
1327
1328     const dav_if_header *if_header;     /* for validation */
1329     const dav_locktoken *locktoken;     /* for UNLOCK */
1330     const dav_lock *lock;               /* for LOCK */
1331     int skip_root;                      /* for dav_inherit_locks() */
1332
1333     int flags;
1334
1335     dav_walker_private *info;           /* for use by repository manager */
1336
1337 } dav_walker_ctx;
1338
1339 void dav_add_response(dav_walker_ctx *ctx, const char *href, int status,
1340                       dav_get_props_result *propstats);
1341
1342
1343 /* --------------------------------------------------------------------
1344 **
1345 ** "STREAM" STRUCTURE
1346 **
1347 ** mod_dav uses this abstraction for interacting with the repository
1348 ** while fetching/storing resources. mod_dav views resources as a stream
1349 ** of bytes.
1350 **
1351 ** Note that the structure is opaque -- it is private to the repository
1352 ** that created the stream in the repository's "open" function.
1353 */
1354
1355 typedef struct dav_stream dav_stream;
1356
1357 typedef enum {
1358     DAV_MODE_READ,              /* open for reading */
1359     DAV_MODE_READ_SEEKABLE,     /* open for random access reading */
1360     DAV_MODE_WRITE_TRUNC,       /* truncate and open for writing */
1361     DAV_MODE_WRITE_SEEKABLE     /* open for writing; random access */
1362 } dav_stream_mode;
1363
1364 /* --------------------------------------------------------------------
1365 **
1366 ** REPOSITORY FUNCTIONS
1367 */
1368
1369 /* Repository provider hooks */
1370 struct dav_hooks_repository
1371 {
1372     /* Flag for whether repository requires special GET handling.
1373      * If resources in the repository are not visible in the
1374      * filesystem location which URLs map to, then special handling
1375      * is required to first fetch a resource from the repository,
1376      * respond to the GET request, then free the resource copy.
1377      */
1378     int handle_get;
1379
1380     /* Get a resource descriptor for the URI in a request.
1381      * A descriptor is returned even if the resource does not exist.
1382      * The return value should only be NULL for some kind of fatal error.
1383      *
1384      * The root_dir is the root of the directory for which this repository
1385      * is configured.
1386      * The workspace is the value of any Target-Selector header, or NULL
1387      * if there is none.
1388      *
1389      * The provider may associate the request storage pool with the resource,
1390      * to use in other operations on that resource.
1391      */
1392     dav_resource * (*get_resource)(
1393         request_rec *r,
1394         const char *root_dir,
1395         const char *workspace
1396     );
1397
1398     /* Get a resource descriptor for the parent of the given resource.
1399      * The resources need not exist.  NULL is returned if the resource
1400      * is the root collection.
1401      */
1402     dav_resource * (*get_parent_resource)(
1403         const dav_resource *resource
1404     );
1405
1406     /* Determine whether two resource descriptors refer to the same resource.
1407     *
1408      * Result != 0 => the resources are the same.
1409      */
1410     int (*is_same_resource)(
1411         const dav_resource *res1,
1412         const dav_resource *res2
1413     );
1414
1415     /* Determine whether one resource is a parent (immediate or otherwise)
1416      * of another.
1417      *
1418      * Result != 0 => res1 is a parent of res2.
1419      */
1420     int (*is_parent_resource)(
1421         const dav_resource *res1,
1422         const dav_resource *res2
1423     );
1424
1425     /*
1426     ** Open a stream for this resource, using the specified mode. The
1427     ** stream will be returned in *stream.
1428     */
1429     dav_error * (*open_stream)(const dav_resource *resource,
1430                                dav_stream_mode mode,
1431                                dav_stream **stream);
1432
1433     /*
1434     ** Close the specified stream.
1435     **
1436     ** mod_dav will (ideally) make sure to call this. For safety purposes,
1437     ** a provider should (ideally) register a cleanup function with the
1438     ** request pool to get this closed and cleaned up.
1439     **
1440     ** Note the possibility of an error from the close -- it is entirely
1441     ** feasible that the close does a "commit" of some kind, which can
1442     ** produce an error.
1443     **
1444     ** commit should be TRUE (non-zero) or FALSE (0) if the stream was
1445     ** opened for writing. This flag states whether to retain the file
1446     ** or not.
1447     ** Note: the commit flag is ignored for streams opened for reading.
1448     */
1449     dav_error * (*close_stream)(dav_stream *stream, int commit);
1450
1451     /*
1452     ** Read data from the stream.
1453     **
1454     ** The size of the buffer is passed in *bufsize, and the amount read
1455     ** is returned in *bufsize.
1456     **
1457     ** *bufsize should be set to zero when the end of file is reached.
1458     ** As a corollary, this function should always read at least one byte
1459     ** on each call, until the EOF condition is met.
1460     */
1461     dav_error * (*read_stream)(dav_stream *stream,
1462                                void *buf, size_t *bufsize);
1463
1464     /*
1465     ** Write data to the stream.
1466     **
1467     ** All of the bytes must be written, or an error should be returned.
1468     */
1469     dav_error * (*write_stream)(dav_stream *stream,
1470                                 const void *buf, size_t bufsize);
1471
1472     /*
1473     ** Seek to an absolute position in the stream. This is used to support
1474     ** Content-Range in a GET/PUT.
1475     **
1476     ** NOTE: if this function is NULL (which is allowed), then any
1477     **       operations using Content-Range will be refused.
1478     */
1479     dav_error * (*seek_stream)(dav_stream *stream, off_t abs_position);
1480
1481     /*
1482     ** If a GET is processed using a stream (open_stream, read_stream)
1483     ** rather than via a sub-request (on get_pathname), then this function
1484     ** is used to provide the repository with a way to set the headers
1485     ** in the response.
1486     **
1487     ** It may be NULL if get_pathname is provided.
1488     */
1489     dav_error * (*set_headers)(request_rec *r,
1490                                const dav_resource *resource);
1491
1492     /* Get a pathname for the file represented by the resource descriptor.
1493      * A provider may need to create a temporary copy of the file, if it is
1494      * not directly accessible in a filesystem. free_handle_p will be set by
1495      * the provider to point to information needed to clean up any temporary
1496      * storage used.
1497      *
1498      * Returns NULL if the file could not be made accessible.
1499      */
1500     const char * (*get_pathname)(
1501         const dav_resource *resource,
1502         void **free_handle_p
1503     );
1504
1505     /* Free any temporary storage associated with a file made accessible by
1506      * get_pathname().
1507      */
1508     void (*free_file)(
1509         void *free_handle
1510     );
1511
1512     /* Create a collection resource. The resource must not already exist.
1513      *
1514      * Result == NULL if the collection was created successfully. Also, the
1515      * resource object is updated to reflect that the resource exists, and
1516      * is a collection.
1517      */
1518     dav_error * (*create_collection)(
1519         ap_pool_t *p, dav_resource *resource
1520     );
1521
1522     /* Copy one resource to another. The destination must not exist.
1523      * Handles both files and collections. Properties are copied as well.
1524      * The depth argument is ignored for a file, and can be either 0 or
1525      * DAV_INFINITY for a collection.
1526      * If an error occurs in a child resource, then the return value is
1527      * non-NULL, and *response is set to a multistatus response.
1528      * If the copy is successful, the dst resource object is
1529      * updated to reflect that the resource exists.
1530      */
1531     dav_error * (*copy_resource)(
1532         const dav_resource *src,
1533         dav_resource *dst,
1534         int depth,
1535         dav_response **response
1536     );
1537
1538     /* Move one resource to another. The destination must not exist.
1539      * Handles both files and collections. Properties are moved as well.
1540      * If an error occurs in a child resource, then the return value is
1541      * non-NULL, and *response is set to a multistatus response.
1542      * If the move is successful, the src and dst resource objects are
1543      * updated to reflect that the source no longer exists, and the
1544      * destination does.
1545      */
1546     dav_error * (*move_resource)(
1547         dav_resource *src,
1548         dav_resource *dst,
1549         dav_response **response
1550     );
1551
1552     /* Remove a resource. Handles both files and collections.
1553      * Removes any associated properties as well.
1554      * If an error occurs in a child resource, then the return value is
1555      * non-NULL, and *response is set to a multistatus response.
1556      * If the delete is successful, the resource object is updated to
1557      * reflect that the resource no longer exists.
1558      */
1559     dav_error * (*remove_resource)(
1560         dav_resource *resource,
1561         dav_response **response
1562     );
1563
1564     /* Walk a resource hierarchy.
1565      *
1566      * Iterates over the resource hierarchy specified by wctx->resource.
1567      * Parameter for control of the walk and the callback are specified
1568      * by wctx.
1569      *
1570      * An HTTP_* status code is returned if an error occurs during the
1571      * walk or the callback indicates an error. OK is returned on success.
1572      */
1573     dav_error * (*walk)(dav_walker_ctx *wctx, int depth);
1574
1575     /* Get the entity tag for a resource */
1576     const char * (*getetag)(const dav_resource *resource);
1577 };
1578
1579
1580 /* --------------------------------------------------------------------
1581 **
1582 ** VERSIONING FUNCTIONS
1583 */
1584
1585 /* dav_get_target_selector:
1586  *
1587  * Returns any Target-Selector header in a request
1588  * (used by versioning clients)
1589  */
1590 const char *dav_get_target_selector(request_rec *r);
1591
1592 /* Ensure that a resource is writable. If there is no versioning
1593  * provider, then this is essentially a no-op. Versioning repositories
1594  * require explicit resource creation and checkout before they can
1595  * be written to. If a new resource is to be created, or an existing
1596  * resource deleted, the parent collection must be checked out as well.
1597  *
1598  * Set the parent_only flag to only make the parent collection writable.
1599  * Otherwise, both parent and child are made writable as needed. If the
1600  * child does not exist, then a new versioned resource is created and
1601  * checked out.
1602  *
1603  * The parent_resource and parent_was_writable arguments are optional
1604  * (i.e. they may be NULL). If parent_only is set, then the
1605  * resource_existed and resource_was_writable arguments are ignored.
1606  *
1607  * The previous states of the resources are returned, so they can be
1608  * restored after the operation completes (see
1609  * dav_revert_resource_writability())
1610  */
1611 dav_error *dav_ensure_resource_writable(request_rec *r,
1612                                         dav_resource *resource,
1613                                         int parent_only,
1614                                         dav_resource **parent_resource,
1615                                         int *resource_existed,
1616                                         int *resource_was_writable,
1617                                         int *parent_was_writable);
1618
1619 /* Revert the writability of resources back to what they were
1620  * before they were modified. If undo == 0, then the resource
1621  * modifications are maintained (i.e. they are checked in).
1622  * If undo != 0, then resource modifications are discarded
1623  * (i.e. they are unchecked out).
1624  *
1625  * The resource and parent_resource arguments are optional
1626  * (i.e. they may be NULL).
1627  */
1628 dav_error *dav_revert_resource_writability(request_rec *r,
1629                                            dav_resource *resource,
1630                                            dav_resource *parent_resource,
1631                                            int undo,
1632                                            int resource_existed,
1633                                            int resource_was_writable,
1634                                            int parent_was_writable);
1635
1636 /* Versioning provider hooks */
1637 struct dav_hooks_vsn
1638 {
1639     /* Return supported versioning level
1640      * for the Versioning header
1641      */
1642     const char * (*get_vsn_header)(void);
1643
1644     /* Create a new (empty) resource. If successful,
1645      * the resource object state is updated appropriately.
1646      */
1647     dav_error * (*mkresource)(dav_resource *resource);
1648
1649     /* Checkout a resource. If successful, the resource
1650      * object state is updated appropriately.
1651      */
1652     dav_error * (*checkout)(dav_resource *resource);
1653
1654     /* Uncheckout a resource. If successful, the resource
1655      * object state is updated appropriately.
1656      */
1657     dav_error * (*uncheckout)(dav_resource *resource);
1658
1659     /* Checkin a working resource. If successful, the resource
1660      * object state is updated appropriately.
1661      */
1662     dav_error * (*checkin)(dav_resource *resource);
1663
1664     /* Determine whether a non-versioned (or non-existent) resource
1665      * is versionable. Returns != 0 if resource can be versioned.
1666      */
1667     int (*versionable)(const dav_resource *resource);
1668
1669     /* Determine whether auto-versioning is enabled for a resource
1670      * (which may not exist, or may not be versioned).
1671      * Returns != 0 if auto-versioning is enabled.
1672      */
1673     int (*auto_version_enabled)(const dav_resource *resource);
1674 };
1675
1676
1677 /* --------------------------------------------------------------------
1678 **
1679 ** MISCELLANEOUS STUFF
1680 */
1681
1682 /* allow providers access to the per-directory parameters */
1683 ap_table_t *dav_get_dir_params(const request_rec *r);
1684
1685 /* fetch the "LimitXMLRequestBody" in force for this resource */
1686 size_t dav_get_limit_xml_body(const request_rec *r);
1687
1688 typedef struct {
1689     int propid;                         /* live property ID */
1690     const dav_hooks_liveprop *provider; /* the provider defining this prop */
1691     const int *ns_map;                  /* ns map for this provider */
1692 } dav_elem_private;
1693
1694 #ifdef __cplusplus
1695 }
1696 #endif
1697
1698 #endif /* _MOD_DAV_H_ */