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