00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00026 #ifndef _MOD_DAV_H_ 00027 #define _MOD_DAV_H_ 00028 00029 #include "apr_hooks.h" 00030 #include "apr_hash.h" 00031 #include "apr_dbm.h" 00032 #include "apr_tables.h" 00033 00034 #include "httpd.h" 00035 #include "util_filter.h" 00036 #include "util_xml.h" 00037 00038 #include <limits.h> /* for INT_MAX */ 00039 #include <time.h> /* for time_t */ 00040 00041 #ifdef __cplusplus 00042 extern "C" { 00043 #endif 00044 00045 00046 #define DAV_VERSION AP_SERVER_BASEREVISION 00047 00048 #define DAV_XML_HEADER "<?xml version=\"1.0\" encoding=\"utf-8\"?>" 00049 #define DAV_XML_CONTENT_TYPE "text/xml; charset=\"utf-8\"" 00050 00051 #define DAV_READ_BLOCKSIZE 2048 /* used for reading input blocks */ 00052 00053 #define DAV_RESPONSE_BODY_1 "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>" 00054 #define DAV_RESPONSE_BODY_2 "</title>\n</head><body>\n<h1>" 00055 #define DAV_RESPONSE_BODY_3 "</h1>\n<p>" 00056 #define DAV_RESPONSE_BODY_4 "</p>\n" 00057 #define DAV_RESPONSE_BODY_5 "</body></html>\n" 00058 00059 #define DAV_DO_COPY 0 00060 #define DAV_DO_MOVE 1 00061 00062 00063 #if 1 00064 #define DAV_DEBUG 1 00065 #define DEBUG_CR "\n" 00066 #define DBG0(f) ap_log_error(APLOG_MARK, \ 00067 APLOG_ERR, 0, NULL, (f)) 00068 #define DBG1(f,a1) ap_log_error(APLOG_MARK, \ 00069 APLOG_ERR, 0, NULL, f, a1) 00070 #define DBG2(f,a1,a2) ap_log_error(APLOG_MARK, \ 00071 APLOG_ERR, 0, NULL, f, a1, a2) 00072 #define DBG3(f,a1,a2,a3) ap_log_error(APLOG_MARK, \ 00073 APLOG_ERR, 0, NULL, f, a1, a2, a3) 00074 #else 00075 #undef DAV_DEBUG 00076 #define DEBUG_CR "" 00077 #endif 00078 00079 #define DAV_INFINITY INT_MAX /* for the Depth: header */ 00080 00081 /* Create a set of DAV_DECLARE(type), DAV_DECLARE_NONSTD(type) and 00082 * DAV_DECLARE_DATA with appropriate export and import tags for the platform 00083 */ 00084 #if !defined(WIN32) 00085 #define DAV_DECLARE(type) type 00086 #define DAV_DECLARE_NONSTD(type) type 00087 #define DAV_DECLARE_DATA 00088 #elif defined(DAV_DECLARE_STATIC) 00089 #define DAV_DECLARE(type) type __stdcall 00090 #define DAV_DECLARE_NONSTD(type) type 00091 #define DAV_DECLARE_DATA 00092 #elif defined(DAV_DECLARE_EXPORT) 00093 #define DAV_DECLARE(type) __declspec(dllexport) type __stdcall 00094 #define DAV_DECLARE_NONSTD(type) __declspec(dllexport) type 00095 #define DAV_DECLARE_DATA __declspec(dllexport) 00096 #else 00097 #define DAV_DECLARE(type) __declspec(dllimport) type __stdcall 00098 #define DAV_DECLARE_NONSTD(type) __declspec(dllimport) type 00099 #define DAV_DECLARE_DATA __declspec(dllimport) 00100 #endif 00101 00102 /* -------------------------------------------------------------------- 00103 ** 00104 ** ERROR MANAGEMENT 00105 */ 00106 00107 /* 00108 ** dav_error structure. 00109 ** 00110 ** In most cases, mod_dav uses a pointer to a dav_error structure. If the 00111 ** pointer is NULL, then no error has occurred. 00112 ** 00113 ** In certain cases, a dav_error structure is directly used. In these cases, 00114 ** a status value of 0 means that an error has not occurred. 00115 ** 00116 ** Note: this implies that status != 0 whenever an error occurs. 00117 ** 00118 ** The desc field is optional (it may be NULL). When NULL, it typically 00119 ** implies that Apache has a proper description for the specified status. 00120 */ 00121 typedef struct dav_error { 00122 int status; /* suggested HTTP status (0 for no error) */ 00123 int error_id; /* DAV-specific error ID */ 00124 const char *desc; /* DAV:responsedescription and error log */ 00125 00126 int save_errno; /* copy of errno causing the error */ 00127 00128 const char *namespace; /* [optional] namespace of error */ 00129 const char *tagname; /* name of error-tag */ 00130 00131 struct dav_error *prev; /* previous error (in stack) */ 00132 00133 } dav_error; 00134 00135 /* 00136 ** Create a new error structure. save_errno will be filled with the current 00137 ** errno value. 00138 */ 00139 DAV_DECLARE(dav_error*) dav_new_error(apr_pool_t *p, int status, 00140 int error_id, const char *desc); 00141 00142 00143 /* 00144 ** Create a new error structure with tagname and (optional) namespace; 00145 ** namespace may be NULL, which means "DAV:". save_errno will be 00146 ** filled with the current errno value. 00147 */ 00148 DAV_DECLARE(dav_error*) dav_new_error_tag(apr_pool_t *p, int status, 00149 int error_id, const char *desc, 00150 const char *namespace, 00151 const char *tagname); 00152 00153 00154 /* 00155 ** Push a new error description onto the stack of errors. 00156 ** 00157 ** This function is used to provide an additional description to an existing 00158 ** error. 00159 ** 00160 ** <status> should contain the caller's view of what the current status is, 00161 ** given the underlying error. If it doesn't have a better idea, then the 00162 ** caller should pass prev->status. 00163 ** 00164 ** <error_id> can specify a new error_id since the topmost description has 00165 ** changed. 00166 */ 00167 DAV_DECLARE(dav_error*) dav_push_error(apr_pool_t *p, int status, int error_id, 00168 const char *desc, dav_error *prev); 00169 00170 00171 /* error ID values... */ 00172 00173 /* IF: header errors */ 00174 #define DAV_ERR_IF_PARSE 100 /* general parsing error */ 00175 #define DAV_ERR_IF_MULTIPLE_NOT 101 /* multiple "Not" found */ 00176 #define DAV_ERR_IF_UNK_CHAR 102 /* unknown char in header */ 00177 #define DAV_ERR_IF_ABSENT 103 /* no locktokens given */ 00178 #define DAV_ERR_IF_TAGGED 104 /* in parsing tagged-list */ 00179 #define DAV_ERR_IF_UNCLOSED_PAREN 105 /* in no-tagged-list */ 00180 00181 /* Prop DB errors */ 00182 #define DAV_ERR_PROP_BAD_MAJOR 200 /* major version was wrong */ 00183 #define DAV_ERR_PROP_READONLY 201 /* prop is read-only */ 00184 #define DAV_ERR_PROP_NO_DATABASE 202 /* writable db not avail */ 00185 #define DAV_ERR_PROP_NOT_FOUND 203 /* prop not found */ 00186 #define DAV_ERR_PROP_BAD_LOCKDB 204 /* could not open lockdb */ 00187 #define DAV_ERR_PROP_OPENING 205 /* problem opening propdb */ 00188 #define DAV_ERR_PROP_EXEC 206 /* problem exec'ing patch */ 00189 00190 /* Predefined DB errors */ 00191 /* ### any to define?? */ 00192 00193 /* Predefined locking system errors */ 00194 #define DAV_ERR_LOCK_OPENDB 400 /* could not open lockdb */ 00195 #define DAV_ERR_LOCK_NO_DB 401 /* no database defined */ 00196 #define DAV_ERR_LOCK_CORRUPT_DB 402 /* DB is corrupt */ 00197 #define DAV_ERR_LOCK_UNK_STATE_TOKEN 403 /* unknown State-token */ 00198 #define DAV_ERR_LOCK_PARSE_TOKEN 404 /* bad opaquelocktoken */ 00199 #define DAV_ERR_LOCK_SAVE_LOCK 405 /* err saving locks */ 00200 00201 /* 00202 ** Some comments on Error ID values: 00203 ** 00204 ** The numbers do not necessarily need to be unique. Uniqueness simply means 00205 ** that two errors that have not been predefined above can be distinguished 00206 ** from each other. At the moment, mod_dav does not use this distinguishing 00207 ** feature, but it could be used in the future to collapse <response> elements 00208 ** into groups based on the error ID (and associated responsedescription). 00209 ** 00210 ** If a compute_desc is provided, then the error ID should be unique within 00211 ** the context of the compute_desc function (so the function can figure out 00212 ** what to filled into the desc). 00213 ** 00214 ** Basically, subsystems can ignore defining new error ID values if they want 00215 ** to. The subsystems *do* need to return the predefined errors when 00216 ** appropriate, so that mod_dav can figure out what to do. Subsystems can 00217 ** simply leave the error ID field unfilled (zero) if there isn't an error 00218 ** that must be placed there. 00219 */ 00220 00221 00222 /* -------------------------------------------------------------------- 00223 ** 00224 ** HOOK STRUCTURES 00225 ** 00226 ** These are here for forward-declaration purposes. For more info, see 00227 ** the section title "HOOK HANDLING" for more information, plus each 00228 ** structure definition. 00229 */ 00230 00231 /* forward-declare this structure */ 00232 typedef struct dav_hooks_propdb dav_hooks_propdb; 00233 typedef struct dav_hooks_locks dav_hooks_locks; 00234 typedef struct dav_hooks_vsn dav_hooks_vsn; 00235 typedef struct dav_hooks_repository dav_hooks_repository; 00236 typedef struct dav_hooks_liveprop dav_hooks_liveprop; 00237 typedef struct dav_hooks_binding dav_hooks_binding; 00238 typedef struct dav_hooks_search dav_hooks_search; 00239 00240 /* ### deprecated name */ 00241 typedef dav_hooks_propdb dav_hooks_db; 00242 00243 00244 /* -------------------------------------------------------------------- 00245 ** 00246 ** RESOURCE HANDLING 00247 */ 00248 00249 /* 00250 ** Resource Types: 00251 ** The base protocol defines only file and collection resources. 00252 ** The versioning protocol defines several additional resource types 00253 ** to represent artifacts of a version control system. 00254 ** 00255 ** This enumeration identifies the type of URL used to identify the 00256 ** resource. Since the same resource may have more than one type of 00257 ** URL which can identify it, dav_resource_type cannot be used 00258 ** alone to determine the type of the resource; attributes of the 00259 ** dav_resource object must also be consulted. 00260 */ 00261 typedef enum { 00262 DAV_RESOURCE_TYPE_UNKNOWN, 00263 00264 DAV_RESOURCE_TYPE_REGULAR, /* file or collection; could be 00265 * unversioned, or version selector, 00266 * or baseline selector */ 00267 00268 DAV_RESOURCE_TYPE_VERSION, /* version or baseline URL */ 00269 00270 DAV_RESOURCE_TYPE_HISTORY, /* version or baseline history URL */ 00271 00272 DAV_RESOURCE_TYPE_WORKING, /* working resource URL */ 00273 00274 DAV_RESOURCE_TYPE_WORKSPACE, /* workspace URL */ 00275 00276 DAV_RESOURCE_TYPE_ACTIVITY, /* activity URL */ 00277 00278 DAV_RESOURCE_TYPE_PRIVATE /* repository-private type */ 00279 00280 } dav_resource_type; 00281 00282 /* 00283 ** Opaque, repository-specific information for a resource. 00284 */ 00285 typedef struct dav_resource_private dav_resource_private; 00286 00287 /* 00288 ** Resource descriptor, generated by a repository provider. 00289 ** 00290 ** Note: the lock-null state is not explicitly represented here, 00291 ** since it may be expensive to compute. Use dav_get_resource_state() 00292 ** to determine whether a non-existent resource is a lock-null resource. 00293 ** 00294 ** A quick explanation of how the flags can apply to different resources: 00295 ** 00296 ** unversioned file or collection: 00297 ** type = DAV_RESOURCE_TYPE_REGULAR 00298 ** exists = ? (1 if exists) 00299 ** collection = ? (1 if collection) 00300 ** versioned = 0 00301 ** baselined = 0 00302 ** working = 0 00303 ** 00304 ** version-controlled resource or configuration: 00305 ** type = DAV_RESOURCE_TYPE_REGULAR 00306 ** exists = 1 00307 ** collection = ? (1 if collection) 00308 ** versioned = 1 00309 ** baselined = ? (1 if configuration) 00310 ** working = ? (1 if checked out) 00311 ** 00312 ** version/baseline history: 00313 ** type = DAV_RESOURCE_TYPE_HISTORY 00314 ** exists = 1 00315 ** collection = 0 00316 ** versioned = 0 00317 ** baselined = 0 00318 ** working = 0 00319 ** 00320 ** version/baseline: 00321 ** type = DAV_RESOURCE_TYPE_VERSION 00322 ** exists = 1 00323 ** collection = ? (1 if collection) 00324 ** versioned = 1 00325 ** baselined = ? (1 if baseline) 00326 ** working = 0 00327 ** 00328 ** working resource: 00329 ** type = DAV_RESOURCE_TYPE_WORKING 00330 ** exists = 1 00331 ** collection = ? (1 if collection) 00332 ** versioned = 1 00333 ** baselined = 0 00334 ** working = 1 00335 ** 00336 ** workspace: 00337 ** type = DAV_RESOURCE_TYPE_WORKSPACE 00338 ** exists = ? (1 if exists) 00339 ** collection = 1 00340 ** versioned = ? (1 if version-controlled) 00341 ** baselined = ? (1 if baseline-controlled) 00342 ** working = ? (1 if checked out) 00343 ** 00344 ** activity: 00345 ** type = DAV_RESOURCE_TYPE_ACTIVITY 00346 ** exists = ? (1 if exists) 00347 ** collection = 0 00348 ** versioned = 0 00349 ** baselined = 0 00350 ** working = 0 00351 */ 00352 typedef struct dav_resource { 00353 dav_resource_type type; 00354 00355 int exists; /* 0 => null resource */ 00356 00357 int collection; /* 0 => file; can be 1 for 00358 * REGULAR, VERSION, and WORKING resources, 00359 * and is always 1 for WORKSPACE */ 00360 00361 int versioned; /* 0 => unversioned; can be 1 for 00362 * REGULAR and WORKSPACE resources, 00363 * and is always 1 for VERSION and WORKING */ 00364 00365 int baselined; /* 0 => not baselined; can be 1 for 00366 * REGULAR, VERSION, and WORKSPACE resources; 00367 * versioned == 1 when baselined == 1 */ 00368 00369 int working; /* 0 => not checked out; can be 1 for 00370 * REGULAR and WORKSPACE resources, 00371 * and is always 1 for WORKING */ 00372 00373 const char *uri; /* the URI for this resource */ 00374 00375 dav_resource_private *info; /* the provider's private info */ 00376 00377 const dav_hooks_repository *hooks; /* hooks used for this resource */ 00378 00379 /* When allocating items related specifically to this resource, the 00380 following pool should be used. Its lifetime will be at least as 00381 long as the dav_resource structure. */ 00382 apr_pool_t *pool; 00383 00384 } dav_resource; 00385 00386 /* 00387 ** Lock token type. Lock providers define the details of a lock token. 00388 ** However, all providers are expected to at least be able to parse 00389 ** the "opaquelocktoken" scheme, which is represented by a uuid_t. 00390 */ 00391 typedef struct dav_locktoken dav_locktoken; 00392 00393 00394 /* -------------------------------------------------------------------- 00395 ** 00396 ** BUFFER HANDLING 00397 ** 00398 ** These buffers are used as a lightweight buffer reuse mechanism. Apache 00399 ** provides sub-pool creation and destruction to much the same effect, but 00400 ** the sub-pools are a bit more general and heavyweight than these buffers. 00401 */ 00402 00403 /* buffer for reuse; can grow to accomodate needed size */ 00404 typedef struct 00405 { 00406 apr_size_t alloc_len; /* how much has been allocated */ 00407 apr_size_t cur_len; /* how much is currently being used */ 00408 char *buf; /* buffer contents */ 00409 } dav_buffer; 00410 #define DAV_BUFFER_MINSIZE 256 /* minimum size for buffer */ 00411 #define DAV_BUFFER_PAD 64 /* amount of pad when growing */ 00412 00413 /* set the cur_len to the given size and ensure space is available */ 00414 DAV_DECLARE(void) dav_set_bufsize(apr_pool_t *p, dav_buffer *pbuf, 00415 apr_size_t size); 00416 00417 /* initialize a buffer and copy the specified (null-term'd) string into it */ 00418 DAV_DECLARE(void) dav_buffer_init(apr_pool_t *p, dav_buffer *pbuf, 00419 const char *str); 00420 00421 /* check that the buffer can accomodate <extra_needed> more bytes */ 00422 DAV_DECLARE(void) dav_check_bufsize(apr_pool_t *p, dav_buffer *pbuf, 00423 apr_size_t extra_needed); 00424 00425 /* append a string to the end of the buffer, adjust length */ 00426 DAV_DECLARE(void) dav_buffer_append(apr_pool_t *p, dav_buffer *pbuf, 00427 const char *str); 00428 00429 /* place a string on the end of the buffer, do NOT adjust length */ 00430 DAV_DECLARE(void) dav_buffer_place(apr_pool_t *p, dav_buffer *pbuf, 00431 const char *str); 00432 00433 /* place some memory on the end of a buffer; do NOT adjust length */ 00434 DAV_DECLARE(void) dav_buffer_place_mem(apr_pool_t *p, dav_buffer *pbuf, 00435 const void *mem, apr_size_t amt, 00436 apr_size_t pad); 00437 00438 00439 /* -------------------------------------------------------------------- 00440 ** 00441 ** HANDY UTILITIES 00442 */ 00443 00444 /* contains results from one of the getprop functions */ 00445 typedef struct 00446 { 00447 apr_text * propstats; /* <propstat> element text */ 00448 apr_text * xmlns; /* namespace decls for <response> elem */ 00449 } dav_get_props_result; 00450 00451 /* holds the contents of a <response> element */ 00452 typedef struct dav_response 00453 { 00454 const char *href; /* always */ 00455 const char *desc; /* optional description at <response> level */ 00456 00457 /* use status if propresult.propstats is NULL. */ 00458 dav_get_props_result propresult; 00459 00460 int status; 00461 00462 struct dav_response *next; 00463 } dav_response; 00464 00465 typedef struct 00466 { 00467 request_rec *rnew; /* new subrequest */ 00468 dav_error err; /* potential error response */ 00469 } dav_lookup_result; 00470 00471 00472 DAV_DECLARE(dav_lookup_result) dav_lookup_uri(const char *uri, request_rec *r, 00473 int must_be_absolute); 00474 00475 /* defines type of property info a provider is to return */ 00476 typedef enum { 00477 DAV_PROP_INSERT_NOTDEF, /* property is defined by this provider, 00478 but nothing was inserted because the 00479 (live) property is not defined for this 00480 resource (it may be present as a dead 00481 property). */ 00482 DAV_PROP_INSERT_NOTSUPP, /* property is recognized by this provider, 00483 but it is not supported, and cannot be 00484 treated as a dead property */ 00485 DAV_PROP_INSERT_NAME, /* a property name (empty elem) was 00486 inserted into the text block */ 00487 DAV_PROP_INSERT_VALUE, /* a property name/value pair was inserted 00488 into the text block */ 00489 DAV_PROP_INSERT_SUPPORTED /* a supported live property was added to 00490 the text block as a 00491 <DAV:supported-live-property> element */ 00492 } dav_prop_insert; 00493 00494 /* ### this stuff is private to dav/fs/repos.c; move it... */ 00495 /* format a time string (buf must be at least DAV_TIMEBUF_SIZE chars) */ 00496 #define DAV_STYLE_ISO8601 1 00497 #define DAV_STYLE_RFC822 2 00498 #define DAV_TIMEBUF_SIZE 30 00499 00500 DAV_DECLARE(int) dav_get_depth(request_rec *r, int def_depth); 00501 00502 DAV_DECLARE(int) dav_validate_root(const apr_xml_doc *doc, 00503 const char *tagname); 00504 DAV_DECLARE(apr_xml_elem *) dav_find_child(const apr_xml_elem *elem, 00505 const char *tagname); 00506 00507 /* gather up all the CDATA into a single string */ 00508 DAV_DECLARE(const char *) dav_xml_get_cdata(const apr_xml_elem *elem, apr_pool_t *pool, 00509 int strip_white); 00510 00511 /* 00512 ** XML namespace handling 00513 ** 00514 ** This structure tracks namespace declarations (xmlns:prefix="URI"). 00515 ** It maintains a one-to-many relationship of URIs-to-prefixes. In other 00516 ** words, one URI may be defined by many prefixes, but any specific 00517 ** prefix will specify only one URI. 00518 ** 00519 ** Prefixes using the "g###" pattern can be generated automatically if 00520 ** the caller does not have specific prefix requirements. 00521 */ 00522 typedef struct { 00523 apr_pool_t *pool; 00524 apr_hash_t *uri_prefix; /* map URIs to an available prefix */ 00525 apr_hash_t *prefix_uri; /* map all prefixes to their URIs */ 00526 int count; /* counter for "g###" prefixes */ 00527 } dav_xmlns_info; 00528 00529 /* create an empty dav_xmlns_info structure */ 00530 DAV_DECLARE(dav_xmlns_info *) dav_xmlns_create(apr_pool_t *pool); 00531 00532 /* add a specific prefix/URI pair. the prefix/uri should have a lifetime 00533 at least that of xmlns->pool */ 00534 DAV_DECLARE(void) dav_xmlns_add(dav_xmlns_info *xi, 00535 const char *prefix, const char *uri); 00536 00537 /* add a URI (if not present); any prefix is acceptable and is returned. 00538 the uri should have a lifetime at least that xmlns->pool */ 00539 DAV_DECLARE(const char *) dav_xmlns_add_uri(dav_xmlns_info *xi, 00540 const char *uri); 00541 00542 /* return the URI for a specified prefix (or NULL if the prefix is unknown) */ 00543 DAV_DECLARE(const char *) dav_xmlns_get_uri(dav_xmlns_info *xi, 00544 const char *prefix); 00545 00546 /* return an available prefix for a specified URI (or NULL if the URI 00547 is unknown) */ 00548 DAV_DECLARE(const char *) dav_xmlns_get_prefix(dav_xmlns_info *xi, 00549 const char *uri); 00550 00551 /* generate xmlns declarations (appending into the given text) */ 00552 DAV_DECLARE(void) dav_xmlns_generate(dav_xmlns_info *xi, 00553 apr_text_header *phdr); 00554 00555 /* -------------------------------------------------------------------- 00556 ** 00557 ** DAV PLUGINS 00558 */ 00559 00560 /* ### docco ... */ 00561 00562 /* 00563 ** dav_provider 00564 ** 00565 ** This structure wraps up all of the hooks that a mod_dav provider can 00566 ** supply. The provider MUST supply <repos> and <propdb>. The rest are 00567 ** optional and should contain NULL if that feature is not supplied. 00568 ** 00569 ** Note that a provider cannot pick and choose portions from various 00570 ** underlying implementations (which was theoretically possible in 00571 ** mod_dav 1.0). There are too many dependencies between a dav_resource 00572 ** (defined by <repos>) and the other functionality. 00573 ** 00574 ** Live properties are not part of the dav_provider structure because they 00575 ** are handled through the APR_HOOK interface (to allow for multiple liveprop 00576 ** providers). The core always provides some properties, and then a given 00577 ** provider will add more properties. 00578 ** 00579 ** Some providers may need to associate a context with the dav_provider 00580 ** structure -- the ctx field is available for storing this context. Just 00581 ** leave it NULL if it isn't required. 00582 */ 00583 typedef struct { 00584 const dav_hooks_repository *repos; 00585 const dav_hooks_propdb *propdb; 00586 const dav_hooks_locks *locks; 00587 const dav_hooks_vsn *vsn; 00588 const dav_hooks_binding *binding; 00589 const dav_hooks_search *search; 00590 00591 void *ctx; 00592 } dav_provider; 00593 00594 /* 00595 ** gather_propsets: gather all live property propset-URIs 00596 ** 00597 ** The hook implementor should push one or more URIs into the specified 00598 ** array. These URIs are returned in the DAV: header to let clients know 00599 ** what sets of live properties are supported by the installation. mod_dav 00600 ** will place open/close angle brackets around each value (much like 00601 ** a Coded-URL); quotes and brackets should not be in the value. 00602 ** 00603 ** Example: http://apache.org/dav/props/ 00604 ** 00605 ** (of course, use your own domain to ensure a unique value) 00606 */ 00607 APR_DECLARE_EXTERNAL_HOOK(dav, DAV, void, gather_propsets, 00608 (apr_array_header_t *uris)) 00609 00610 /* 00611 ** find_liveprop: find a live property, returning a non-zero, unique, 00612 ** opaque identifier. 00613 ** 00614 ** If the hook implementor determines the specified URI/name refers to 00615 ** one of its properties, then it should fill in HOOKS and return a 00616 ** non-zero value. The returned value is the "property ID" and will 00617 ** be passed to the various liveprop hook functions. 00618 ** 00619 ** Return 0 if the property is not defined by the hook implementor. 00620 */ 00621 APR_DECLARE_EXTERNAL_HOOK(dav, DAV, int, find_liveprop, 00622 (const dav_resource *resource, 00623 const char *ns_uri, const char *name, 00624 const dav_hooks_liveprop **hooks)) 00625 00626 /* 00627 ** insert_all_liveprops: insert all (known) live property names/values. 00628 ** 00629 ** The hook implementor should append XML text to PHDR, containing liveprop 00630 ** names. If INSVALUE is true, then the property values should also be 00631 ** inserted into the output XML stream. 00632 ** 00633 ** The liveprop provider should insert *all* known and *defined* live 00634 ** properties on the specified resource. If a particular liveprop is 00635 ** not defined for this resource, then it should not be inserted. 00636 */ 00637 APR_DECLARE_EXTERNAL_HOOK(dav, DAV, void, insert_all_liveprops, 00638 (request_rec *r, const dav_resource *resource, 00639 dav_prop_insert what, apr_text_header *phdr)) 00640 00641 DAV_DECLARE(const dav_hooks_locks *) dav_get_lock_hooks(request_rec *r); 00642 DAV_DECLARE(const dav_hooks_propdb *) dav_get_propdb_hooks(request_rec *r); 00643 DAV_DECLARE(const dav_hooks_vsn *) dav_get_vsn_hooks(request_rec *r); 00644 DAV_DECLARE(const dav_hooks_binding *) dav_get_binding_hooks(request_rec *r); 00645 DAV_DECLARE(const dav_hooks_search *) dav_get_search_hooks(request_rec *r); 00646 00647 DAV_DECLARE(void) dav_register_provider(apr_pool_t *p, const char *name, 00648 const dav_provider *hooks); 00649 DAV_DECLARE(const dav_provider *) dav_lookup_provider(const char *name); 00650 00651 00652 /* ### deprecated */ 00653 #define DAV_GET_HOOKS_PROPDB(r) dav_get_propdb_hooks(r) 00654 #define DAV_GET_HOOKS_LOCKS(r) dav_get_lock_hooks(r) 00655 #define DAV_GET_HOOKS_VSN(r) dav_get_vsn_hooks(r) 00656 #define DAV_GET_HOOKS_BINDING(r) dav_get_binding_hooks(r) 00657 #define DAV_GET_HOOKS_SEARCH(r) dav_get_search_hooks(r) 00658 00659 00660 /* -------------------------------------------------------------------- 00661 ** 00662 ** IF HEADER PROCESSING 00663 ** 00664 ** Here is the definition of the If: header from RFC 2518, S9.4: 00665 ** 00666 ** If = "If" ":" (1*No-tag-list | 1*Tagged-list) 00667 ** No-tag-list = List 00668 ** Tagged-list = Resource 1*List 00669 ** Resource = Coded-URL 00670 ** List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")" 00671 ** State-token = Coded-URL 00672 ** Coded-URL = "<" absoluteURI ">" ; absoluteURI from RFC 2616 00673 ** 00674 ** List corresponds to dav_if_state_list. No-tag-list corresponds to 00675 ** dav_if_header with uri==NULL. Tagged-list corresponds to a sequence of 00676 ** dav_if_header structures with (duplicate) uri==Resource -- one 00677 ** dav_if_header per state_list. A second Tagged-list will start a new 00678 ** sequence of dav_if_header structures with the new URI. 00679 ** 00680 ** A summary of the semantics, mapped into our structures: 00681 ** - Chained dav_if_headers: OR 00682 ** - Chained dav_if_state_lists: AND 00683 ** - NULL uri matches all resources 00684 */ 00685 00686 typedef enum 00687 { 00688 dav_if_etag, 00689 dav_if_opaquelock, 00690 dav_if_unknown /* the "unknown" state type; always matches false. */ 00691 } dav_if_state_type; 00692 00693 typedef struct dav_if_state_list 00694 { 00695 dav_if_state_type type; 00696 00697 int condition; 00698 #define DAV_IF_COND_NORMAL 0 00699 #define DAV_IF_COND_NOT 1 /* "Not" was applied */ 00700 00701 const char *etag; 00702 dav_locktoken *locktoken; 00703 00704 struct dav_if_state_list *next; 00705 } dav_if_state_list; 00706 00707 typedef struct dav_if_header 00708 { 00709 const char *uri; 00710 apr_size_t uri_len; 00711 struct dav_if_state_list *state; 00712 struct dav_if_header *next; 00713 00714 int dummy_header; /* used internally by the lock/etag validation */ 00715 } dav_if_header; 00716 00717 typedef struct dav_locktoken_list 00718 { 00719 dav_locktoken *locktoken; 00720 struct dav_locktoken_list *next; 00721 } dav_locktoken_list; 00722 00723 DAV_DECLARE(dav_error *) dav_get_locktoken_list(request_rec *r, 00724 dav_locktoken_list **ltl); 00725 00726 00727 /* -------------------------------------------------------------------- 00728 ** 00729 ** LIVE PROPERTY HANDLING 00730 */ 00731 00732 /* opaque type for PROPPATCH rollback information */ 00733 typedef struct dav_liveprop_rollback dav_liveprop_rollback; 00734 00735 struct dav_hooks_liveprop 00736 { 00737 /* 00738 ** Insert property information into a text block. The property to 00739 ** insert is identified by the propid value. The information to insert 00740 ** is identified by the "what" argument, as follows: 00741 ** DAV_PROP_INSERT_NAME 00742 ** property name, as an empty XML element 00743 ** DAV_PROP_INSERT_VALUE 00744 ** property name/value, as an XML element 00745 ** DAV_PROP_INSERT_SUPPORTED 00746 ** if the property is defined on the resource, then 00747 ** a DAV:supported-live-property element, as defined 00748 ** by the DeltaV extensions to RFC2518. 00749 ** 00750 ** Providers should return DAV_PROP_INSERT_NOTDEF if the property is 00751 ** known and not defined for this resource, so should be handled as a 00752 ** dead property. If a provider recognizes, but does not support, a 00753 ** property, and does not want it handled as a dead property, it should 00754 ** return DAV_PROP_INSERT_NOTSUPP. 00755 ** 00756 ** Returns one of DAV_PROP_INSERT_* based on what happened. 00757 ** 00758 ** ### we may need more context... ie. the lock database 00759 */ 00760 dav_prop_insert (*insert_prop)(const dav_resource *resource, 00761 int propid, dav_prop_insert what, 00762 apr_text_header *phdr); 00763 00764 /* 00765 ** Determine whether a given property is writable. 00766 ** 00767 ** ### we may want a different semantic. i.e. maybe it should be 00768 ** ### "can we write <value> into this property?" 00769 ** 00770 ** Returns 1 if the live property can be written, 0 if read-only. 00771 */ 00772 int (*is_writable)(const dav_resource *resource, int propid); 00773 00774 /* 00775 ** This member defines the set of namespace URIs that the provider 00776 ** uses for its properties. When insert_all is called, it will be 00777 ** passed a list of integers that map from indices into this list 00778 ** to namespace IDs for output generation. 00779 ** 00780 ** The last entry in this list should be a NULL value (sentinel). 00781 */ 00782 const char * const * namespace_uris; 00783 00784 /* 00785 ** ### this is not the final design. we want an open-ended way for 00786 ** ### liveprop providers to attach *new* properties. To this end, 00787 ** ### we'll have a "give me a list of the props you define", a way 00788 ** ### to check for a prop's existence, a way to validate a set/remove 00789 ** ### of a prop, and a way to execute/commit/rollback that change. 00790 */ 00791 00792 /* 00793 ** Validate that the live property can be assigned a value, and that 00794 ** the provided value is valid. 00795 ** 00796 ** elem will point to the XML element that names the property. For 00797 ** example: 00798 ** <lp1:executable>T</lp1:executable> 00799 ** 00800 ** The provider can access the cdata fields and the child elements 00801 ** to extract the relevant pieces. 00802 ** 00803 ** operation is one of DAV_PROP_OP_SET or _DELETE. 00804 ** 00805 ** The provider may return a value in *context which will be passed 00806 ** to each of the exec/commit/rollback functions. For example, this 00807 ** may contain an internal value which has been processed from the 00808 ** input element. 00809 ** 00810 ** The provider must set defer_to_dead to true (non-zero) or false. 00811 ** If true, then the set/remove is deferred to the dead property 00812 ** database. Note: it will be set to zero on entry. 00813 */ 00814 dav_error * (*patch_validate)(const dav_resource *resource, 00815 const apr_xml_elem *elem, 00816 int operation, 00817 void **context, 00818 int *defer_to_dead); 00819 00820 /* ### doc... */ 00821 dav_error * (*patch_exec)(const dav_resource *resource, 00822 const apr_xml_elem *elem, 00823 int operation, 00824 void *context, 00825 dav_liveprop_rollback **rollback_ctx); 00826 00827 /* ### doc... */ 00828 void (*patch_commit)(const dav_resource *resource, 00829 int operation, 00830 void *context, 00831 dav_liveprop_rollback *rollback_ctx); 00832 00833 /* ### doc... */ 00834 dav_error * (*patch_rollback)(const dav_resource *resource, 00835 int operation, 00836 void *context, 00837 dav_liveprop_rollback *rollback_ctx); 00838 00839 /* 00840 ** If a provider needs a context to associate with this hooks structure, 00841 ** then this field may be used. In most cases, it will just be NULL. 00842 */ 00843 void *ctx; 00844 }; 00845 00846 /* 00847 ** dav_liveprop_spec: specify a live property 00848 ** 00849 ** This structure is used as a standard way to determine if a particular 00850 ** property is a live property. Its use is not part of the mandated liveprop 00851 ** interface, but can be used by liveprop providers in conjuction with the 00852 ** utility routines below. 00853 ** 00854 ** spec->name == NULL is the defined end-sentinel for a list of specs. 00855 */ 00856 typedef struct { 00857 int ns; /* provider-local namespace index */ 00858 const char *name; /* name of the property */ 00859 00860 int propid; /* provider-local property ID */ 00861 00862 int is_writable; /* is the property writable? */ 00863 00864 } dav_liveprop_spec; 00865 00866 /* 00867 ** dav_liveprop_group: specify a group of liveprops 00868 ** 00869 ** This structure specifies a group of live properties, their namespaces, 00870 ** and how to handle them. 00871 */ 00872 typedef struct { 00873 const dav_liveprop_spec *specs; 00874 const char * const *namespace_uris; 00875 const dav_hooks_liveprop *hooks; 00876 00877 } dav_liveprop_group; 00878 00879 /* ### docco */ 00880 DAV_DECLARE(int) dav_do_find_liveprop(const char *ns_uri, const char *name, 00881 const dav_liveprop_group *group, 00882 const dav_hooks_liveprop **hooks); 00883 00884 /* ### docco */ 00885 DAV_DECLARE(long) dav_get_liveprop_info(int propid, 00886 const dav_liveprop_group *group, 00887 const dav_liveprop_spec **info); 00888 00889 /* ### docco */ 00890 DAV_DECLARE(void) dav_register_liveprop_group(apr_pool_t *pool, 00891 const dav_liveprop_group *group); 00892 00893 /* ### docco */ 00894 DAV_DECLARE(long) dav_get_liveprop_ns_index(const char *uri); 00895 00896 /* ### docco */ 00897 DAV_DECLARE(long) dav_get_liveprop_ns_count(void); 00898 00899 /* ### docco */ 00900 DAV_DECLARE(void) dav_add_all_liveprop_xmlns(apr_pool_t *p, 00901 apr_text_header *phdr); 00902 00903 /* 00904 ** The following three functions are part of mod_dav's internal handling 00905 ** for the core WebDAV properties. They are not part of mod_dav's API. 00906 */ 00907 DAV_DECLARE_NONSTD(int) dav_core_find_liveprop( 00908 const dav_resource *resource, 00909 const char *ns_uri, 00910 const char *name, 00911 const dav_hooks_liveprop **hooks); 00912 DAV_DECLARE_NONSTD(void) dav_core_insert_all_liveprops( 00913 request_rec *r, 00914 const dav_resource *resource, 00915 dav_prop_insert what, 00916 apr_text_header *phdr); 00917 DAV_DECLARE_NONSTD(void) dav_core_register_uris(apr_pool_t *p); 00918 00919 00920 /* 00921 ** Standard WebDAV Property Identifiers 00922 ** 00923 ** A live property provider does not need to use these; they are simply 00924 ** provided for convenience. 00925 ** 00926 ** Property identifiers need to be unique within a given provider, but not 00927 ** *across* providers (note: this uniqueness constraint was different in 00928 ** older versions of mod_dav). 00929 ** 00930 ** The identifiers start at 20000 to make it easier for providers to avoid 00931 ** conflicts with the standard properties. The properties are arranged 00932 ** alphabetically, and may be reordered from time to time (as properties 00933 ** are introduced). 00934 ** 00935 ** NOTE: there is no problem with reordering (e.g. binary compat) since the 00936 ** identifiers are only used within a given provider, which would pick up 00937 ** the entire set of changes upon a recompile. 00938 */ 00939 enum { 00940 DAV_PROPID_BEGIN = 20000, 00941 00942 /* Standard WebDAV properties (RFC 2518) */ 00943 DAV_PROPID_creationdate, 00944 DAV_PROPID_displayname, 00945 DAV_PROPID_getcontentlanguage, 00946 DAV_PROPID_getcontentlength, 00947 DAV_PROPID_getcontenttype, 00948 DAV_PROPID_getetag, 00949 DAV_PROPID_getlastmodified, 00950 DAV_PROPID_lockdiscovery, 00951 DAV_PROPID_resourcetype, 00952 DAV_PROPID_source, 00953 DAV_PROPID_supportedlock, 00954 00955 /* DeltaV properties (from the I-D (#14)) */ 00956 DAV_PROPID_activity_checkout_set, 00957 DAV_PROPID_activity_set, 00958 DAV_PROPID_activity_version_set, 00959 DAV_PROPID_auto_merge_set, 00960 DAV_PROPID_auto_version, 00961 DAV_PROPID_baseline_collection, 00962 DAV_PROPID_baseline_controlled_collection, 00963 DAV_PROPID_baseline_controlled_collection_set, 00964 DAV_PROPID_checked_in, 00965 DAV_PROPID_checked_out, 00966 DAV_PROPID_checkin_fork, 00967 DAV_PROPID_checkout_fork, 00968 DAV_PROPID_checkout_set, 00969 DAV_PROPID_comment, 00970 DAV_PROPID_creator_displayname, 00971 DAV_PROPID_current_activity_set, 00972 DAV_PROPID_current_workspace_set, 00973 DAV_PROPID_default_variant, 00974 DAV_PROPID_eclipsed_set, 00975 DAV_PROPID_label_name_set, 00976 DAV_PROPID_merge_set, 00977 DAV_PROPID_precursor_set, 00978 DAV_PROPID_predecessor_set, 00979 DAV_PROPID_root_version, 00980 DAV_PROPID_subactivity_set, 00981 DAV_PROPID_subbaseline_set, 00982 DAV_PROPID_successor_set, 00983 DAV_PROPID_supported_method_set, 00984 DAV_PROPID_supported_live_property_set, 00985 DAV_PROPID_supported_report_set, 00986 DAV_PROPID_unreserved, 00987 DAV_PROPID_variant_set, 00988 DAV_PROPID_version_controlled_binding_set, 00989 DAV_PROPID_version_controlled_configuration, 00990 DAV_PROPID_version_history, 00991 DAV_PROPID_version_name, 00992 DAV_PROPID_workspace, 00993 DAV_PROPID_workspace_checkout_set, 00994 00995 DAV_PROPID_END 00996 }; 00997 00998 /* 00999 ** Property Identifier Registration 01000 ** 01001 ** At the moment, mod_dav requires live property providers to ensure that 01002 ** each property returned has a unique value. For now, this is done through 01003 ** central registration (there are no known providers other than the default, 01004 ** so this remains manageable). 01005 ** 01006 ** WARNING: the TEST ranges should never be "shipped". 01007 */ 01008 #define DAV_PROPID_CORE 10000 /* ..10099. defined by mod_dav */ 01009 #define DAV_PROPID_FS 10100 /* ..10299. 01010 mod_dav filesystem provider. */ 01011 #define DAV_PROPID_TEST1 10300 /* ..10399 */ 01012 #define DAV_PROPID_TEST2 10400 /* ..10499 */ 01013 #define DAV_PROPID_TEST3 10500 /* ..10599 */ 01014 /* Next: 10600 */ 01015 01016 01017 /* -------------------------------------------------------------------- 01018 ** 01019 ** DATABASE FUNCTIONS 01020 */ 01021 01022 typedef struct dav_db dav_db; 01023 typedef struct dav_namespace_map dav_namespace_map; 01024 typedef struct dav_deadprop_rollback dav_deadprop_rollback; 01025 01026 typedef struct { 01027 const char *ns; /* "" signals "no namespace" */ 01028 const char *name; 01029 } dav_prop_name; 01030 01031 /* hook functions to enable pluggable databases */ 01032 struct dav_hooks_propdb 01033 { 01034 dav_error * (*open)(apr_pool_t *p, const dav_resource *resource, int ro, 01035 dav_db **pdb); 01036 void (*close)(dav_db *db); 01037 01038 /* 01039 ** In bulk, define any namespaces that the values and their name 01040 ** elements may need. 01041 ** 01042 ** Note: sometimes mod_dav will defer calling this until output_value 01043 ** returns found==1. If the output process needs the dav_xmlns_info 01044 ** filled for its work, then it will need to fill it on demand rather 01045 ** than depending upon this hook to fill in the structure. 01046 ** 01047 ** Note: this will *always* be called during an output sequence. Thus, 01048 ** the provider may rely solely on using this to fill the xmlns info. 01049 */ 01050 dav_error * (*define_namespaces)(dav_db *db, dav_xmlns_info *xi); 01051 01052 /* 01053 ** Output the value from the database (i.e. add an element name and 01054 ** the value into *phdr). Set *found based on whether the name/value 01055 ** was found in the propdb. 01056 ** 01057 ** Note: it is NOT an error for the key/value pair to not exist. 01058 ** 01059 ** The dav_xmlns_info passed to define_namespaces() is also passed to 01060 ** each output_value() call so that namespaces can be added on-demand. 01061 ** It can also be used to look up prefixes or URIs during the output 01062 ** process. 01063 */ 01064 dav_error * (*output_value)(dav_db *db, const dav_prop_name *name, 01065 dav_xmlns_info *xi, 01066 apr_text_header *phdr, int *found); 01067 01068 /* 01069 ** Build a mapping from "global" namespaces (stored in apr_xml_*) 01070 ** into provider-local namespace identifiers. 01071 ** 01072 ** This mapping should be done once per set of namespaces, and the 01073 ** resulting mapping should be passed into the store() hook function. 01074 ** 01075 ** Note: usually, there is just a single document/namespaces for all 01076 ** elements passed. However, the generality of creating multiple 01077 ** mappings and passing them to store() is provided here. 01078 ** 01079 ** Note: this is only in preparation for a series of store() calls. 01080 ** As a result, the propdb must be open for read/write access when 01081 ** this function is called. 01082 */ 01083 dav_error * (*map_namespaces)(dav_db *db, 01084 const apr_array_header_t *namespaces, 01085 dav_namespace_map **mapping); 01086 01087 /* 01088 ** Store a property value for a given name. The value->combined field 01089 ** MUST be set for this call. 01090 ** 01091 ** ### WARNING: current providers will quote the text within ELEM. 01092 ** ### this implies you can call this function only once with a given 01093 ** ### element structure (a second time will quote it again). 01094 */ 01095 dav_error * (*store)(dav_db *db, const dav_prop_name *name, 01096 const apr_xml_elem *elem, 01097 dav_namespace_map *mapping); 01098 01099 /* remove a given property */ 01100 dav_error * (*remove)(dav_db *db, const dav_prop_name *name); 01101 01102 /* returns 1 if the record specified by "key" exists; 0 otherwise */ 01103 int (*exists)(dav_db *db, const dav_prop_name *name); 01104 01105 /* 01106 ** Iterate over the property names in the database. 01107 ** 01108 ** iter->name.ns == iter->name.name == NULL when there are no more names. 01109 ** 01110 ** Note: only one iteration may occur over the propdb at a time. 01111 */ 01112 dav_error * (*first_name)(dav_db *db, dav_prop_name *pname); 01113 dav_error * (*next_name)(dav_db *db, dav_prop_name *pname); 01114 01115 /* 01116 ** Rollback support: get rollback context, and apply it. 01117 ** 01118 ** struct dav_deadprop_rollback is a provider-private structure; it 01119 ** should remember the name, and the name's old value (or the fact that 01120 ** the value was not present, and should be deleted if a rollback occurs). 01121 */ 01122 dav_error * (*get_rollback)(dav_db *db, const dav_prop_name *name, 01123 dav_deadprop_rollback **prollback); 01124 dav_error * (*apply_rollback)(dav_db *db, 01125 dav_deadprop_rollback *rollback); 01126 01127 /* 01128 ** If a provider needs a context to associate with this hooks structure, 01129 ** then this field may be used. In most cases, it will just be NULL. 01130 */ 01131 void *ctx; 01132 }; 01133 01134 01135 /* -------------------------------------------------------------------- 01136 ** 01137 ** LOCK FUNCTIONS 01138 */ 01139 01140 /* Used to represent a Timeout header of "Infinity" */ 01141 #define DAV_TIMEOUT_INFINITE 0 01142 01143 DAV_DECLARE(time_t) dav_get_timeout(request_rec *r); 01144 01145 /* 01146 ** Opaque, provider-specific information for a lock database. 01147 */ 01148 typedef struct dav_lockdb_private dav_lockdb_private; 01149 01150 /* 01151 ** Opaque, provider-specific information for a lock record. 01152 */ 01153 typedef struct dav_lock_private dav_lock_private; 01154 01155 /* 01156 ** Lock database type. Lock providers are urged to implement a "lazy" open, so 01157 ** doing an "open" is cheap until something is actually needed from the DB. 01158 */ 01159 typedef struct 01160 { 01161 const dav_hooks_locks *hooks; /* the hooks used for this lockdb */ 01162 int ro; /* was it opened readonly? */ 01163 01164 dav_lockdb_private *info; 01165 01166 } dav_lockdb; 01167 01168 typedef enum { 01169 DAV_LOCKSCOPE_UNKNOWN, 01170 DAV_LOCKSCOPE_EXCLUSIVE, 01171 DAV_LOCKSCOPE_SHARED 01172 } dav_lock_scope; 01173 01174 typedef enum { 01175 DAV_LOCKTYPE_UNKNOWN, 01176 DAV_LOCKTYPE_WRITE 01177 } dav_lock_type; 01178 01179 typedef enum { 01180 DAV_LOCKREC_DIRECT, /* lock asserted on this resource */ 01181 DAV_LOCKREC_INDIRECT, /* lock inherited from a parent */ 01182 DAV_LOCKREC_INDIRECT_PARTIAL /* most info is not filled in */ 01183 } dav_lock_rectype; 01184 01185 /* 01186 ** dav_lock: hold information about a lock on a resource. 01187 ** 01188 ** This structure is used for both direct and indirect locks. A direct lock 01189 ** is a lock applied to a specific resource by the client. An indirect lock 01190 ** is one that is inherited from a parent resource by virtue of a non-zero 01191 ** Depth: header when the lock was applied. 01192 ** 01193 ** mod_dav records both types of locks in the lock database, managing their 01194 ** addition/removal as resources are moved about the namespace. 01195 ** 01196 ** Note that the lockdb is free to marshal this structure in any form that 01197 ** it likes. 01198 ** 01199 ** For a "partial" lock, the <rectype> and <locktoken> fields must be filled 01200 ** in. All other (user) fields should be zeroed. The lock provider will 01201 ** usually fill in the <info> field, and the <next> field may be used to 01202 ** construct a list of partial locks. 01203 ** 01204 ** The lock provider MUST use the info field to store a value such that a 01205 ** dav_lock structure can locate itself in the underlying lock database. 01206 ** This requirement is needed for refreshing: when an indirect dav_lock is 01207 ** refreshed, its reference to the direct lock does not specify the direct's 01208 ** resource, so the only way to locate the (refreshed, direct) lock in the 01209 ** database is to use the info field. 01210 ** 01211 ** Note that <is_locknull> only refers to the resource where this lock was 01212 ** found. 01213 ** ### hrm. that says the abstraction is wrong. is_locknull may disappear. 01214 */ 01215 typedef struct dav_lock 01216 { 01217 dav_lock_rectype rectype; /* type of lock record */ 01218 int is_locknull; /* lock establishes a locknull resource */ 01219 01220 /* ### put the resource in here? */ 01221 01222 dav_lock_scope scope; /* scope of the lock */ 01223 dav_lock_type type; /* type of lock */ 01224 int depth; /* depth of the lock */ 01225 time_t timeout; /* when the lock will timeout */ 01226 01227 const dav_locktoken *locktoken; /* the token that was issued */ 01228 01229 const char *owner; /* (XML) owner of the lock */ 01230 const char *auth_user; /* auth'd username owning lock */ 01231 01232 dav_lock_private *info; /* private to the lockdb */ 01233 01234 struct dav_lock *next; /* for managing a list of locks */ 01235 } dav_lock; 01236 01237 /* Property-related public lock functions */ 01238 DAV_DECLARE(const char *)dav_lock_get_activelock(request_rec *r, 01239 dav_lock *locks, 01240 dav_buffer *pbuf); 01241 01242 /* LockDB-related public lock functions */ 01243 DAV_DECLARE(dav_error *) dav_lock_parse_lockinfo(request_rec *r, 01244 const dav_resource *resrouce, 01245 dav_lockdb *lockdb, 01246 const apr_xml_doc *doc, 01247 dav_lock **lock_request); 01248 DAV_DECLARE(int) dav_unlock(request_rec *r, 01249 const dav_resource *resource, 01250 const dav_locktoken *locktoken); 01251 DAV_DECLARE(dav_error *) dav_add_lock(request_rec *r, 01252 const dav_resource *resource, 01253 dav_lockdb *lockdb, dav_lock *request, 01254 dav_response **response); 01255 DAV_DECLARE(dav_error *) dav_notify_created(request_rec *r, 01256 dav_lockdb *lockdb, 01257 const dav_resource *resource, 01258 int resource_state, 01259 int depth); 01260 01261 DAV_DECLARE(dav_error*) dav_lock_query(dav_lockdb *lockdb, 01262 const dav_resource *resource, 01263 dav_lock **locks); 01264 01265 DAV_DECLARE(dav_error *) dav_validate_request(request_rec *r, 01266 dav_resource *resource, 01267 int depth, 01268 dav_locktoken *locktoken, 01269 dav_response **response, 01270 int flags, 01271 dav_lockdb *lockdb); 01272 /* 01273 ** flags: 01274 ** 0x0F -- reserved for <dav_lock_scope> values 01275 ** 01276 ** other flags, detailed below 01277 */ 01278 #define DAV_VALIDATE_RESOURCE 0x0010 /* validate just the resource */ 01279 #define DAV_VALIDATE_PARENT 0x0020 /* validate resource AND its parent */ 01280 #define DAV_VALIDATE_ADD_LD 0x0040 /* add DAV:lockdiscovery into 01281 the 424 DAV:response */ 01282 #define DAV_VALIDATE_USE_424 0x0080 /* return 424 status, not 207 */ 01283 #define DAV_VALIDATE_IS_PARENT 0x0100 /* for internal use */ 01284 01285 /* Lock-null related public lock functions */ 01286 DAV_DECLARE(int) dav_get_resource_state(request_rec *r, 01287 const dav_resource *resource); 01288 01289 /* Lock provider hooks. Locking is optional, so there may be no 01290 * lock provider for a given repository. 01291 */ 01292 struct dav_hooks_locks 01293 { 01294 /* Return the supportedlock property for a resource */ 01295 const char * (*get_supportedlock)( 01296 const dav_resource *resource 01297 ); 01298 01299 /* Parse a lock token URI, returning a lock token object allocated 01300 * in the given pool. 01301 */ 01302 dav_error * (*parse_locktoken)( 01303 apr_pool_t *p, 01304 const char *char_token, 01305 dav_locktoken **locktoken_p 01306 ); 01307 01308 /* Format a lock token object into a URI string, allocated in 01309 * the given pool. 01310 * 01311 * Always returns non-NULL. 01312 */ 01313 const char * (*format_locktoken)( 01314 apr_pool_t *p, 01315 const dav_locktoken *locktoken 01316 ); 01317 01318 /* Compare two lock tokens. 01319 * 01320 * Result < 0 => lt1 < lt2 01321 * Result == 0 => lt1 == lt2 01322 * Result > 0 => lt1 > lt2 01323 */ 01324 int (*compare_locktoken)( 01325 const dav_locktoken *lt1, 01326 const dav_locktoken *lt2 01327 ); 01328 01329 /* Open the provider's lock database. 01330 * 01331 * The provider may or may not use a "real" database for locks 01332 * (a lock could be an attribute on a resource, for example). 01333 * 01334 * The provider may choose to use the value of the DAVLockDB directive 01335 * (as returned by dav_get_lockdb_path()) to decide where to place 01336 * any storage it may need. 01337 * 01338 * The request storage pool should be associated with the lockdb, 01339 * so it can be used in subsequent operations. 01340 * 01341 * If ro != 0, only readonly operations will be performed. 01342 * If force == 0, the open can be "lazy"; no subsequent locking operations 01343 * may occur. 01344 * If force != 0, locking operations will definitely occur. 01345 */ 01346 dav_error * (*open_lockdb)( 01347 request_rec *r, 01348 int ro, 01349 int force, 01350 dav_lockdb **lockdb 01351 ); 01352 01353 /* Indicates completion of locking operations */ 01354 void (*close_lockdb)( 01355 dav_lockdb *lockdb 01356 ); 01357 01358 /* Take a resource out of the lock-null state. */ 01359 dav_error * (*remove_locknull_state)( 01360 dav_lockdb *lockdb, 01361 const dav_resource *resource 01362 ); 01363 01364 /* 01365 ** Create a (direct) lock structure for the given resource. A locktoken 01366 ** will be created. 01367 ** 01368 ** The lock provider may store private information into lock->info. 01369 */ 01370 dav_error * (*create_lock)(dav_lockdb *lockdb, 01371 const dav_resource *resource, 01372 dav_lock **lock); 01373 01374 /* 01375 ** Get the locks associated with the specified resource. 01376 ** 01377 ** If resolve_locks is true (non-zero), then any indirect locks are 01378 ** resolved to their actual, direct lock (i.e. the reference to followed 01379 ** to the original lock). 01380 ** 01381 ** The locks, if any, are returned as a linked list in no particular 01382 ** order. If no locks are present, then *locks will be NULL. 01383 */ 01384 dav_error * (*get_locks)(dav_lockdb *lockdb, 01385 const dav_resource *resource, 01386 int calltype, 01387 dav_lock **locks); 01388 01389 #define DAV_GETLOCKS_RESOLVED 0 /* resolve indirects to directs */ 01390 #define DAV_GETLOCKS_PARTIAL 1 /* leave indirects partially filled */ 01391 #define DAV_GETLOCKS_COMPLETE 2 /* fill out indirect locks */ 01392 01393 /* 01394 ** Find a particular lock on a resource (specified by its locktoken). 01395 ** 01396 ** *lock will be set to NULL if the lock is not found. 01397 ** 01398 ** Note that the provider can optimize the unmarshalling -- only one 01399 ** lock (or none) must be constructed and returned. 01400 ** 01401 ** If partial_ok is true (non-zero), then an indirect lock can be 01402 ** partially filled in. Otherwise, another lookup is done and the 01403 ** lock structure will be filled out as a DAV_LOCKREC_INDIRECT. 01404 */ 01405 dav_error * (*find_lock)(dav_lockdb *lockdb, 01406 const dav_resource *resource, 01407 const dav_locktoken *locktoken, 01408 int partial_ok, 01409 dav_lock **lock); 01410 01411 /* 01412 ** Quick test to see if the resource has *any* locks on it. 01413 ** 01414 ** This is typically used to determine if a non-existent resource 01415 ** has a lock and is (therefore) a locknull resource. 01416 ** 01417 ** WARNING: this function may return TRUE even when timed-out locks 01418 ** exist (i.e. it may not perform timeout checks). 01419 */ 01420 dav_error * (*has_locks)(dav_lockdb *lockdb, 01421 const dav_resource *resource, 01422 int *locks_present); 01423 01424 /* 01425 ** Append the specified lock(s) to the set of locks on this resource. 01426 ** 01427 ** If "make_indirect" is true (non-zero), then the specified lock(s) 01428 ** should be converted to an indirect lock (if it is a direct lock) 01429 ** before appending. Note that the conversion to an indirect lock does 01430 ** not alter the passed-in lock -- the change is internal the 01431 ** append_locks function. 01432 ** 01433 ** Multiple locks are specified using the lock->next links. 01434 */ 01435 dav_error * (*append_locks)(dav_lockdb *lockdb, 01436 const dav_resource *resource, 01437 int make_indirect, 01438 const dav_lock *lock); 01439 01440 /* 01441 ** Remove any lock that has the specified locktoken. 01442 ** 01443 ** If locktoken == NULL, then ALL locks are removed. 01444 */ 01445 dav_error * (*remove_lock)(dav_lockdb *lockdb, 01446 const dav_resource *resource, 01447 const dav_locktoken *locktoken); 01448 01449 /* 01450 ** Refresh all locks, found on the specified resource, which has a 01451 ** locktoken in the provided list. 01452 ** 01453 ** If the lock is indirect, then the direct lock is referenced and 01454 ** refreshed. 01455 ** 01456 ** Each lock that is updated is returned in the <locks> argument. 01457 ** Note that the locks will be fully resolved. 01458 */ 01459 dav_error * (*refresh_locks)(dav_lockdb *lockdb, 01460 const dav_resource *resource, 01461 const dav_locktoken_list *ltl, 01462 time_t new_time, 01463 dav_lock **locks); 01464 01465 /* 01466 ** Look up the resource associated with a particular locktoken. 01467 ** 01468 ** The search begins at the specified <start_resource> and the lock 01469 ** specified by <locktoken>. 01470 ** 01471 ** If the resource/token specifies an indirect lock, then the direct 01472 ** lock will be looked up, and THAT resource will be returned. In other 01473 ** words, this function always returns the resource where a particular 01474 ** lock (token) was asserted. 01475 ** 01476 ** NOTE: this function pointer is allowed to be NULL, indicating that 01477 ** the provider does not support this type of functionality. The 01478 ** caller should then traverse up the repository hierarchy looking 01479 ** for the resource defining a lock with this locktoken. 01480 */ 01481 dav_error * (*lookup_resource)(dav_lockdb *lockdb, 01482 const dav_locktoken *locktoken, 01483 const dav_resource *start_resource, 01484 const dav_resource **resource); 01485 01486 /* 01487 ** If a provider needs a context to associate with this hooks structure, 01488 ** then this field may be used. In most cases, it will just be NULL. 01489 */ 01490 void *ctx; 01491 }; 01492 01493 /* what types of resources can be discovered by dav_get_resource_state() */ 01494 #define DAV_RESOURCE_LOCK_NULL 10 /* resource lock-null */ 01495 #define DAV_RESOURCE_NULL 11 /* resource null */ 01496 #define DAV_RESOURCE_EXISTS 12 /* resource exists */ 01497 #define DAV_RESOURCE_ERROR 13 /* an error occurred */ 01498 01499 01500 /* -------------------------------------------------------------------- 01501 ** 01502 ** PROPERTY HANDLING 01503 */ 01504 01505 typedef struct dav_propdb dav_propdb; 01506 01507 01508 DAV_DECLARE(dav_error *) dav_open_propdb( 01509 request_rec *r, 01510 dav_lockdb *lockdb, 01511 const dav_resource *resource, 01512 int ro, 01513 apr_array_header_t *ns_xlate, 01514 dav_propdb **propdb); 01515 01516 DAV_DECLARE(void) dav_close_propdb(dav_propdb *db); 01517 01518 DAV_DECLARE(dav_get_props_result) dav_get_props( 01519 dav_propdb *db, 01520 apr_xml_doc *doc); 01521 01522 DAV_DECLARE(dav_get_props_result) dav_get_allprops( 01523 dav_propdb *db, 01524 dav_prop_insert what); 01525 01526 DAV_DECLARE(void) dav_get_liveprop_supported( 01527 dav_propdb *propdb, 01528 const char *ns_uri, 01529 const char *propname, 01530 apr_text_header *body); 01531 01532 /* 01533 ** 3-phase property modification. 01534 ** 01535 ** 1) validate props. readable? unlocked? ACLs allow access? 01536 ** 2) execute operation (set/delete) 01537 ** 3) commit or rollback 01538 ** 01539 ** ### eventually, auth must be available. a ref to the request_rec (which 01540 ** ### contains the auth info) should be in the shared context struct. 01541 ** 01542 ** Each function may alter the error values and information contained within 01543 ** the context record. This should be done as an "increasing" level of 01544 ** error, rather than overwriting any previous error. 01545 ** 01546 ** Note that commit() cannot generate errors. It should simply free the 01547 ** rollback information. 01548 ** 01549 ** rollback() may generate additional errors because the rollback operation 01550 ** can sometimes fail(!). 01551 ** 01552 ** The caller should allocate an array of these, one per operation. It should 01553 ** be zero-initialized, then the db, operation, and prop fields should be 01554 ** filled in before calling dav_prop_validate. Note that the set/delete 01555 ** operations are order-dependent. For a given (logical) context, the same 01556 ** pointer must be passed to each phase. 01557 ** 01558 ** error_type is an internal value, but will have the same numeric value 01559 ** for each possible "desc" value. This allows the caller to group the 01560 ** descriptions via the error_type variable, rather than through string 01561 ** comparisons. Note that "status" does not provide enough granularity to 01562 ** differentiate/group the "desc" values. 01563 ** 01564 ** Note that the propdb will maintain some (global) context across all 01565 ** of the property change contexts. This implies that you can have only 01566 ** one open transaction per propdb. 01567 */ 01568 typedef struct dav_prop_ctx 01569 { 01570 dav_propdb *propdb; 01571 01572 int operation; 01573 #define DAV_PROP_OP_SET 1 /* set a property value */ 01574 #define DAV_PROP_OP_DELETE 2 /* delete a prop value */ 01575 /* ### add a GET? */ 01576 01577 apr_xml_elem *prop; /* property to affect */ 01578 01579 dav_error *err; /* error (if any) */ 01580 01581 /* private items to the propdb */ 01582 int is_liveprop; 01583 void *liveprop_ctx; 01584 struct dav_rollback_item *rollback; /* optional rollback info */ 01585 01586 /* private to mod_dav.c */ 01587 request_rec *r; 01588 01589 } dav_prop_ctx; 01590 01591 DAV_DECLARE_NONSTD(void) dav_prop_validate(dav_prop_ctx *ctx); 01592 DAV_DECLARE_NONSTD(void) dav_prop_exec(dav_prop_ctx *ctx); 01593 DAV_DECLARE_NONSTD(void) dav_prop_commit(dav_prop_ctx *ctx); 01594 DAV_DECLARE_NONSTD(void) dav_prop_rollback(dav_prop_ctx *ctx); 01595 01596 #define DAV_PROP_CTX_HAS_ERR(dpc) ((dpc).err && (dpc).err->status >= 300) 01597 01598 01599 /* -------------------------------------------------------------------- 01600 ** 01601 ** WALKER STRUCTURE 01602 */ 01603 01604 enum { 01605 DAV_CALLTYPE_MEMBER = 1, /* called for a member resource */ 01606 DAV_CALLTYPE_COLLECTION, /* called for a collection */ 01607 DAV_CALLTYPE_LOCKNULL /* called for a locknull resource */ 01608 }; 01609 01610 typedef struct 01611 { 01612 /* the client-provided context */ 01613 void *walk_ctx; 01614 01615 /* pool to use for allocations in the callback */ 01616 apr_pool_t *pool; 01617 01618 /* the current resource */ 01619 const dav_resource *resource; 01620 01621 /* OUTPUT: add responses to this */ 01622 dav_response *response; 01623 01624 } dav_walk_resource; 01625 01626 typedef struct 01627 { 01628 int walk_type; 01629 #define DAV_WALKTYPE_AUTH 0x0001 /* limit to authorized files */ 01630 #define DAV_WALKTYPE_NORMAL 0x0002 /* walk normal files */ 01631 #define DAV_WALKTYPE_LOCKNULL 0x0004 /* walk locknull resources */ 01632 01633 /* callback function and a client context for the walk */ 01634 dav_error * (*func)(dav_walk_resource *wres, int calltype); 01635 void *walk_ctx; 01636 01637 /* what pool to use for allocations needed by walk logic */ 01638 apr_pool_t *pool; 01639 01640 /* beginning root of the walk */ 01641 const dav_resource *root; 01642 01643 /* lock database to enable walking LOCKNULL resources */ 01644 dav_lockdb *lockdb; 01645 01646 } dav_walk_params; 01647 01648 /* directory tree walking context */ 01649 typedef struct dav_walker_ctx 01650 { 01651 /* input: */ 01652 dav_walk_params w; 01653 01654 01655 /* ### client data... phasing out this big glom */ 01656 01657 /* this brigade buffers data being sent to r->output_filters */ 01658 apr_bucket_brigade *bb; 01659 01660 /* a scratch pool, used to stream responses and iteratively cleared. */ 01661 apr_pool_t *scratchpool; 01662 01663 request_rec *r; /* original request */ 01664 01665 /* for PROPFIND operations */ 01666 apr_xml_doc *doc; 01667 int propfind_type; 01668 #define DAV_PROPFIND_IS_ALLPROP 1 01669 #define DAV_PROPFIND_IS_PROPNAME 2 01670 #define DAV_PROPFIND_IS_PROP 3 01671 01672 apr_text *propstat_404; /* (cached) propstat giving a 404 error */ 01673 01674 const dav_if_header *if_header; /* for validation */ 01675 const dav_locktoken *locktoken; /* for UNLOCK */ 01676 const dav_lock *lock; /* for LOCK */ 01677 int skip_root; /* for dav_inherit_locks() */ 01678 01679 int flags; 01680 01681 dav_buffer work_buf; /* for dav_validate_request() */ 01682 01683 } dav_walker_ctx; 01684 01685 DAV_DECLARE(void) dav_add_response(dav_walk_resource *wres, 01686 int status, 01687 dav_get_props_result *propstats); 01688 01689 01690 /* -------------------------------------------------------------------- 01691 ** 01692 ** "STREAM" STRUCTURE 01693 ** 01694 ** mod_dav uses this abstraction for interacting with the repository 01695 ** while fetching/storing resources. mod_dav views resources as a stream 01696 ** of bytes. 01697 ** 01698 ** Note that the structure is opaque -- it is private to the repository 01699 ** that created the stream in the repository's "open" function. 01700 ** 01701 ** ### THIS STUFF IS GOING AWAY ... GET/read requests are handled by 01702 ** ### having the provider jam stuff straight into the filter stack. 01703 ** ### this is only left for handling PUT/write requests. 01704 */ 01705 01706 typedef struct dav_stream dav_stream; 01707 01708 typedef enum { 01709 DAV_MODE_WRITE_TRUNC, /* truncate and open for writing */ 01710 DAV_MODE_WRITE_SEEKABLE /* open for writing; random access */ 01711 } dav_stream_mode; 01712 01713 01714 /* -------------------------------------------------------------------- 01715 ** 01716 ** REPOSITORY FUNCTIONS 01717 */ 01718 01719 /* Repository provider hooks */ 01720 struct dav_hooks_repository 01721 { 01722 /* Flag for whether repository requires special GET handling. 01723 * If resources in the repository are not visible in the 01724 * filesystem location which URLs map to, then special handling 01725 * is required to first fetch a resource from the repository, 01726 * respond to the GET request, then free the resource copy. 01727 */ 01728 int handle_get; 01729 01730 /* Get a resource descriptor for the URI in a request. A descriptor 01731 * should always be returned even if the resource does not exist. This 01732 * repository has been identified as handling the resource given by 01733 * the URI, so an answer must be given. If there is a problem with the 01734 * URI or accessing the resource or whatever, then an error should be 01735 * returned. 01736 * 01737 * root_dir: 01738 * the root of the directory for which this repository is configured. 01739 * 01740 * label: 01741 * if a Label: header is present (and allowed), this is the label 01742 * to use to identify a version resource from the resource's 01743 * corresponding version history. Otherwise, it will be NULL. 01744 * 01745 * use_checked_in: 01746 * use the DAV:checked-in property of the resource identified by the 01747 * Request-URI to identify and return a version resource 01748 * 01749 * The provider may associate the request storage pool with the resource 01750 * (in the resource->pool field), to use in other operations on that 01751 * resource. 01752 */ 01753 dav_error * (*get_resource)( 01754 request_rec *r, 01755 const char *root_dir, 01756 const char *label, 01757 int use_checked_in, 01758 dav_resource **resource 01759 ); 01760 01761 /* Get a resource descriptor for the parent of the given resource. 01762 * The resources need not exist. NULL is returned if the resource 01763 * is the root collection. 01764 * 01765 * An error should be returned only if there is a fatal error in 01766 * fetching information about the parent resource. 01767 */ 01768 dav_error * (*get_parent_resource)( 01769 const dav_resource *resource, 01770 dav_resource **parent_resource 01771 ); 01772 01773 /* Determine whether two resource descriptors refer to the same resource. 01774 * 01775 * Result != 0 => the resources are the same. 01776 */ 01777 int (*is_same_resource)( 01778 const dav_resource *res1, 01779 const dav_resource *res2 01780 ); 01781 01782 /* Determine whether one resource is a parent (immediate or otherwise) 01783 * of another. 01784 * 01785 * Result != 0 => res1 is a parent of res2. 01786 */ 01787 int (*is_parent_resource)( 01788 const dav_resource *res1, 01789 const dav_resource *res2 01790 ); 01791 01792 /* 01793 ** Open a stream for this resource, using the specified mode. The 01794 ** stream will be returned in *stream. 01795 */ 01796 dav_error * (*open_stream)(const dav_resource *resource, 01797 dav_stream_mode mode, 01798 dav_stream **stream); 01799 01800 /* 01801 ** Close the specified stream. 01802 ** 01803 ** mod_dav will (ideally) make sure to call this. For safety purposes, 01804 ** a provider should (ideally) register a cleanup function with the 01805 ** request pool to get this closed and cleaned up. 01806 ** 01807 ** Note the possibility of an error from the close -- it is entirely 01808 ** feasible that the close does a "commit" of some kind, which can 01809 ** produce an error. 01810 ** 01811 ** commit should be TRUE (non-zero) or FALSE (0) if the stream was 01812 ** opened for writing. This flag states whether to retain the file 01813 ** or not. 01814 ** Note: the commit flag is ignored for streams opened for reading. 01815 */ 01816 dav_error * (*close_stream)(dav_stream *stream, int commit); 01817 01818 /* 01819 ** Write data to the stream. 01820 ** 01821 ** All of the bytes must be written, or an error should be returned. 01822 */ 01823 dav_error * (*write_stream)(dav_stream *stream, 01824 const void *buf, apr_size_t bufsize); 01825 01826 /* 01827 ** Seek to an absolute position in the stream. This is used to support 01828 ** Content-Range in a GET/PUT. 01829 ** 01830 ** NOTE: if this function is NULL (which is allowed), then any 01831 ** operations using Content-Range will be refused. 01832 */ 01833 dav_error * (*seek_stream)(dav_stream *stream, apr_off_t abs_position); 01834 01835 /* 01836 ** If a GET is processed using a stream (open_stream, read_stream) 01837 ** rather than via a sub-request (on get_pathname), then this function 01838 ** is used to provide the repository with a way to set the headers 01839 ** in the response. 01840 ** 01841 ** This function may be called without a following deliver(), to 01842 ** handle a HEAD request. 01843 ** 01844 ** This may be NULL if handle_get is FALSE. 01845 */ 01846 dav_error * (*set_headers)(request_rec *r, 01847 const dav_resource *resource); 01848 01849 /* 01850 ** The provider should deliver the resource into the specified filter. 01851 ** Basically, this is the response to the GET method. 01852 ** 01853 ** Note that this is called for all resources, including collections. 01854 ** The provider should determine what has content to deliver or not. 01855 ** 01856 ** set_headers will be called prior to this function, allowing the 01857 ** provider to set the appropriate response headers. 01858 ** 01859 ** This may be NULL if handle_get is FALSE. 01860 ** ### maybe toss handle_get and just use this function as the marker 01861 */ 01862 dav_error * (*deliver)(const dav_resource *resource, 01863 ap_filter_t *output); 01864 01865 /* Create a collection resource. The resource must not already exist. 01866 * 01867 * Result == NULL if the collection was created successfully. Also, the 01868 * resource object is updated to reflect that the resource exists, and 01869 * is a collection. 01870 */ 01871 dav_error * (*create_collection)( 01872 dav_resource *resource 01873 ); 01874 01875 /* Copy one resource to another. The destination may exist, if it is 01876 * versioned. 01877 * Handles both files and collections. Properties are copied as well. 01878 * If the destination exists and is versioned, the provider must update 01879 * the destination to have identical content to the source, 01880 * recursively for collections. 01881 * The depth argument is ignored for a file, and can be either 0 or 01882 * DAV_INFINITY for a collection. 01883 * If an error occurs in a child resource, then the return value is 01884 * non-NULL, and *response is set to a multistatus response. 01885 * If the copy is successful, the dst resource object is 01886 * updated to reflect that the resource exists. 01887 */ 01888 dav_error * (*copy_resource)( 01889 const dav_resource *src, 01890 dav_resource *dst, 01891 int depth, 01892 dav_response **response 01893 ); 01894 01895 /* Move one resource to another. The destination must not exist. 01896 * Handles both files and collections. Properties are moved as well. 01897 * If an error occurs in a child resource, then the return value is 01898 * non-NULL, and *response is set to a multistatus response. 01899 * If the move is successful, the src and dst resource objects are 01900 * updated to reflect that the source no longer exists, and the 01901 * destination does. 01902 */ 01903 dav_error * (*move_resource)( 01904 dav_resource *src, 01905 dav_resource *dst, 01906 dav_response **response 01907 ); 01908 01909 /* Remove a resource. Handles both files and collections. 01910 * Removes any associated properties as well. 01911 * If an error occurs in a child resource, then the return value is 01912 * non-NULL, and *response is set to a multistatus response. 01913 * If the delete is successful, the resource object is updated to 01914 * reflect that the resource no longer exists. 01915 */ 01916 dav_error * (*remove_resource)( 01917 dav_resource *resource, 01918 dav_response **response 01919 ); 01920 01921 /* Walk a resource hierarchy. 01922 * 01923 * Iterates over the resource hierarchy specified by params->root. 01924 * Control of the walk and the callback are specified by 'params'. 01925 * 01926 * An error may be returned. *response will contain multistatus 01927 * responses (if any) suitable for the body of the error. It is also 01928 * possible to return NULL, yet still have multistatus responses. 01929 * In this case, typically the caller should return a 207 (Multistatus) 01930 * and the responses (in the body) as the HTTP response. 01931 */ 01932 dav_error * (*walk)(const dav_walk_params *params, int depth, 01933 dav_response **response); 01934 01935 /* Get the entity tag for a resource */ 01936 const char * (*getetag)(const dav_resource *resource); 01937 01938 /* 01939 ** If a provider needs a context to associate with this hooks structure, 01940 ** then this field may be used. In most cases, it will just be NULL. 01941 */ 01942 void *ctx; 01943 }; 01944 01945 01946 /* -------------------------------------------------------------------- 01947 ** 01948 ** VERSIONING FUNCTIONS 01949 */ 01950 01951 01952 /* dav_add_vary_header 01953 * 01954 * If there were any headers in the request which require a Vary header 01955 * in the response, add it. 01956 */ 01957 DAV_DECLARE(void) dav_add_vary_header(request_rec *in_req, 01958 request_rec *out_req, 01959 const dav_resource *resource); 01960 01961 /* 01962 ** Flags specifying auto-versioning behavior, returned by 01963 ** the auto_versionable hook. The value returned depends 01964 ** on both the state of the resource and the value of the 01965 ** DAV:auto-versioning property for the resource. 01966 ** 01967 ** If the resource does not exist (null or lock-null), 01968 ** DAV_AUTO_VERSION_ALWAYS causes creation of a new version-controlled resource 01969 ** 01970 ** If the resource is checked in, 01971 ** DAV_AUTO_VERSION_ALWAYS causes it to be checked out always, 01972 ** DAV_AUTO_VERSION_LOCKED causes it to be checked out only when locked 01973 ** 01974 ** If the resource is checked out, 01975 ** DAV_AUTO_VERSION_ALWAYS causes it to be checked in always, 01976 ** DAV_AUTO_VERSION_LOCKED causes it to be checked in when unlocked 01977 ** (note: a provider should allow auto-checkin only for resources which 01978 ** were automatically checked out) 01979 ** 01980 ** In all cases, DAV_AUTO_VERSION_NEVER results in no auto-versioning behavior. 01981 */ 01982 typedef enum { 01983 DAV_AUTO_VERSION_NEVER, 01984 DAV_AUTO_VERSION_ALWAYS, 01985 DAV_AUTO_VERSION_LOCKED 01986 } dav_auto_version; 01987 01988 /* 01989 ** This structure is used to record what auto-versioning operations 01990 ** were done to make a resource writable, so that they can be undone 01991 ** at the end of a request. 01992 */ 01993 typedef struct { 01994 int resource_versioned; /* 1 => resource was auto-version-controlled */ 01995 int resource_checkedout; /* 1 => resource was auto-checked-out */ 01996 int parent_checkedout; /* 1 => parent was auto-checked-out */ 01997 dav_resource *parent_resource; /* parent resource, if it was needed */ 01998 } dav_auto_version_info; 01999 02000 /* Ensure that a resource is writable. If there is no versioning 02001 * provider, then this is essentially a no-op. Versioning repositories 02002 * require explicit resource creation and checkout before they can 02003 * be written to. If a new resource is to be created, or an existing 02004 * resource deleted, the parent collection must be checked out as well. 02005 * 02006 * Set the parent_only flag to only make the parent collection writable. 02007 * Otherwise, both parent and child are made writable as needed. If the 02008 * child does not exist, then a new versioned resource is created and 02009 * checked out. 02010 * 02011 * If auto-versioning is not enabled for a versioned resource, then an error is 02012 * returned, since the resource cannot be modified. 02013 * 02014 * The dav_auto_version_info structure is filled in with enough information 02015 * to restore both parent and child resources to the state they were in 02016 * before the auto-versioning operations occurred. 02017 */ 02018 DAV_DECLARE(dav_error *) dav_auto_checkout( 02019 request_rec *r, 02020 dav_resource *resource, 02021 int parent_only, 02022 dav_auto_version_info *av_info); 02023 02024 /* Revert the writability of resources back to what they were 02025 * before they were modified. If undo == 0, then the resource 02026 * modifications are maintained (i.e. they are checked in). 02027 * If undo != 0, then resource modifications are discarded 02028 * (i.e. they are unchecked out). 02029 * 02030 * Set the unlock flag to indicate that the resource is about 02031 * to be unlocked; it will be checked in if the resource 02032 * auto-versioning property indicates it should be. In this case, 02033 * av_info is ignored, so it can be NULL. 02034 * 02035 * The resource argument may be NULL if only the parent resource 02036 * was checked out (i.e. the parent_only was != 0 in the 02037 * dav_auto_checkout call). 02038 */ 02039 DAV_DECLARE(dav_error *) dav_auto_checkin( 02040 request_rec *r, 02041 dav_resource *resource, 02042 int undo, 02043 int unlock, 02044 dav_auto_version_info *av_info); 02045 02046 /* 02047 ** This structure is used to describe available reports 02048 ** 02049 ** "nmspace" should be valid XML and URL-quoted. mod_dav will place 02050 ** double-quotes around it and use it in an xmlns declaration. 02051 */ 02052 typedef struct { 02053 const char *nmspace; /* namespace of the XML report element */ 02054 const char *name; /* element name for the XML report */ 02055 } dav_report_elem; 02056 02057 02058 /* Versioning provider hooks */ 02059 struct dav_hooks_vsn 02060 { 02061 /* 02062 ** MANDATORY HOOKS 02063 ** The following hooks are mandatory for all versioning providers; 02064 ** they define the functionality needed to implement "core" versioning. 02065 */ 02066 02067 /* Return supported versioning options. 02068 * Each dav_text item in the list will be returned as a separate 02069 * DAV header. Providers are advised to limit the length of an 02070 * individual text item to 63 characters, to conform to the limit 02071 * used by MS Web Folders. 02072 */ 02073 void (*get_vsn_options)(apr_pool_t *p, apr_text_header *phdr); 02074 02075 /* Get the value of a specific option for an OPTIONS request. 02076 * The option being requested is given by the parsed XML 02077 * element object "elem". The value of the option should be 02078 * appended to the "option" text object. 02079 */ 02080 dav_error * (*get_option)(const dav_resource *resource, 02081 const apr_xml_elem *elem, 02082 apr_text_header *option); 02083 02084 /* Determine whether a non-versioned (or non-existent) resource 02085 * is versionable. Returns != 0 if resource can be versioned. 02086 */ 02087 int (*versionable)(const dav_resource *resource); 02088 02089 /* Determine whether auto-versioning is enabled for a resource 02090 * (which may not exist, or may not be versioned). If the resource 02091 * is a checked-out resource, the provider must only enable 02092 * auto-checkin if the resource was automatically checked out. 02093 * 02094 * The value returned depends on both the state of the resource 02095 * and the value of its DAV:auto-version property. See the description 02096 * of the dav_auto_version enumeration above for the details. 02097 */ 02098 dav_auto_version (*auto_versionable)(const dav_resource *resource); 02099 02100 /* Put a resource under version control. If the resource already 02101 * exists unversioned, then it becomes the initial version of the 02102 * new version history, and it is replaced by a version selector 02103 * which targets the new version. 02104 * 02105 * If the resource does not exist, then a new version-controlled 02106 * resource is created which either targets an existing version (if the 02107 * "target" argument is not NULL), or the initial, empty version 02108 * in a new history resource (if the "target" argument is NULL). 02109 * 02110 * If successful, the resource object state is updated appropriately 02111 * (that is, changed to refer to the new version-controlled resource). 02112 */ 02113 dav_error * (*vsn_control)(dav_resource *resource, 02114 const char *target); 02115 02116 /* Checkout a resource. If successful, the resource 02117 * object state is updated appropriately. 02118 * 02119 * The auto_checkout flag will be set if this checkout is being 02120 * done automatically, as part of some method which modifies 02121 * the resource. The provider must remember that the resource 02122 * was automatically checked out, so it can determine whether it 02123 * can be automatically checked in. (Auto-checkin should only be 02124 * enabled for resources which were automatically checked out.) 02125 * 02126 * If the working resource has a different URL from the 02127 * target resource, a dav_resource descriptor is returned 02128 * for the new working resource. Otherwise, the original 02129 * resource descriptor will refer to the working resource. 02130 * The working_resource argument can be NULL if the caller 02131 * is not interested in the working resource. 02132 * 02133 * If the client has specified DAV:unreserved or DAV:fork-ok in the 02134 * checkout request, then the corresponding flags are set. If 02135 * DAV:activity-set has been specified, then create_activity is set 02136 * if DAV:new was specified; otherwise, the DAV:href elements' CDATA 02137 * (the actual href text) is passed in the "activities" array (each 02138 * element of the array is a const char *). activities will be NULL 02139 * no DAV:activity-set was provided or when create_activity is set. 02140 */ 02141 dav_error * (*checkout)(dav_resource *resource, 02142 int auto_checkout, 02143 int is_unreserved, int is_fork_ok, 02144 int create_activity, 02145 apr_array_header_t *activities, 02146 dav_resource **working_resource); 02147 02148 /* Uncheckout a checked-out resource. If successful, the resource 02149 * object state is updated appropriately. 02150 */ 02151 dav_error * (*uncheckout)(dav_resource *resource); 02152 02153 /* Checkin a checked-out resource. If successful, the resource 02154 * object state is updated appropriately, and the 02155 * version_resource descriptor will refer to the new version. 02156 * The version_resource argument can be NULL if the caller 02157 * is not interested in the new version resource. 02158 * 02159 * If the client has specified DAV:keep-checked-out in the checkin 02160 * request, then the keep_checked_out flag is set. The provider 02161 * should create a new version, but keep the resource in the 02162 * checked-out state. 02163 */ 02164 dav_error * (*checkin)(dav_resource *resource, 02165 int keep_checked_out, 02166 dav_resource **version_resource); 02167 02168 /* 02169 ** Return the set of reports available at this resource. 02170 ** 02171 ** An array of report elements should be returned, with an end-marker 02172 ** element containing namespace==NULL. The value of the 02173 ** DAV:supported-report-set property will be constructed and 02174 ** returned. 02175 */ 02176 dav_error * (*avail_reports)(const dav_resource *resource, 02177 const dav_report_elem **reports); 02178 02179 /* 02180 ** Determine whether a Label header can be used 02181 ** with a particular report. The dav_xml_doc structure 02182 ** contains the parsed report request body. 02183 ** Returns 0 if the Label header is not allowed. 02184 */ 02185 int (*report_label_header_allowed)(const apr_xml_doc *doc); 02186 02187 /* 02188 ** Generate a report on a resource. Since a provider is free 02189 ** to define its own reports, and the value of request headers 02190 ** may affect the interpretation of a report, the request record 02191 ** must be passed to this routine. 02192 ** 02193 ** The dav_xml_doc structure contains the parsed report request 02194 ** body. The report response should be generated into the specified 02195 ** output filter. 02196 ** 02197 ** If an error occurs, and a response has not yet been generated, 02198 ** then an error can be returned from this function. mod_dav will 02199 ** construct an appropriate error response. Once some output has 02200 ** been placed into the filter, however, the provider should not 02201 ** return an error -- there is no way that mod_dav can deliver it 02202 ** properly. 02203 ** 02204 ** ### maybe we need a way to signal an error anyways, and then 02205 ** ### apache can abort the connection? 02206 */ 02207 dav_error * (*deliver_report)(request_rec *r, 02208 const dav_resource *resource, 02209 const apr_xml_doc *doc, 02210 ap_filter_t *output); 02211 02212 /* 02213 ** OPTIONAL HOOKS 02214 ** The following hooks are optional; if not defined, then the 02215 ** corresponding protocol methods will be unsupported. 02216 */ 02217 02218 /* 02219 ** Set the state of a checked-in version-controlled resource. 02220 ** 02221 ** If the request specified a version, the version resource 02222 ** represents that version. If the request specified a label, 02223 ** then "version" is NULL, and "label" is the label. 02224 ** 02225 ** The depth argument is ignored for a file, and can be 0, 1, or 02226 ** DAV_INFINITY for a collection. The depth argument only applies 02227 ** with a label, not a version. 02228 ** 02229 ** If an error occurs in a child resource, then the return value is 02230 ** non-NULL, and *response is set to a multistatus response. 02231 ** 02232 ** This hook is optional; if not defined, then the UPDATE method 02233 ** will not be supported. 02234 */ 02235 dav_error * (*update)(const dav_resource *resource, 02236 const dav_resource *version, 02237 const char *label, 02238 int depth, 02239 dav_response **response); 02240 02241 /* 02242 ** Add a label to a version. The resource is either a specific 02243 ** version, or a version selector, in which case the label should 02244 ** be added to the current target of the version selector. The 02245 ** version selector cannot be checked out. 02246 ** 02247 ** If replace != 0, any existing label by the same name is 02248 ** effectively deleted first. Otherwise, it is an error to 02249 ** attempt to add a label which already exists on some version 02250 ** of the same history resource. 02251 ** 02252 ** This hook is optional; if not defined, then the LABEL method 02253 ** will not be supported. If it is defined, then the remove_label 02254 ** hook must be defined also. 02255 */ 02256 dav_error * (*add_label)(const dav_resource *resource, 02257 const char *label, 02258 int replace); 02259 02260 /* 02261 ** Remove a label from a version. The resource is either a specific 02262 ** version, or a version selector, in which case the label should 02263 ** be added to the current target of the version selector. The 02264 ** version selector cannot be checked out. 02265 ** 02266 ** It is an error if no such label exists on the specified version. 02267 ** 02268 ** This hook is optional, but if defined, the add_label hook 02269 ** must be defined also. 02270 */ 02271 dav_error * (*remove_label)(const dav_resource *resource, 02272 const char *label); 02273 02274 /* 02275 ** Determine whether a null resource can be created as a workspace. 02276 ** The provider may restrict workspaces to certain locations. 02277 ** Returns 0 if the resource cannot be a workspace. 02278 ** 02279 ** This hook is optional; if the provider does not support workspaces, 02280 ** it should be set to NULL. 02281 */ 02282 int (*can_be_workspace)(const dav_resource *resource); 02283 02284 /* 02285 ** Create a workspace resource. The resource must not already 02286 ** exist. Any <DAV:mkworkspace> element is passed to the provider 02287 ** in the "doc" structure; it may be empty. 02288 ** 02289 ** If workspace creation is succesful, the state of the resource 02290 ** object is updated appropriately. 02291 ** 02292 ** This hook is optional; if the provider does not support workspaces, 02293 ** it should be set to NULL. 02294 */ 02295 dav_error * (*make_workspace)(dav_resource *resource, 02296 apr_xml_doc *doc); 02297 02298 /* 02299 ** Determine whether a null resource can be created as an activity. 02300 ** The provider may restrict activities to certain locations. 02301 ** Returns 0 if the resource cannot be an activity. 02302 ** 02303 ** This hook is optional; if the provider does not support activities, 02304 ** it should be set to NULL. 02305 */ 02306 int (*can_be_activity)(const dav_resource *resource); 02307 02308 /* 02309 ** Create an activity resource. The resource must not already 02310 ** exist. 02311 ** 02312 ** If activity creation is succesful, the state of the resource 02313 ** object is updated appropriately. 02314 ** 02315 ** This hook is optional; if the provider does not support activities, 02316 ** it should be set to NULL. 02317 */ 02318 dav_error * (*make_activity)(dav_resource *resource); 02319 02320 /* 02321 ** Merge a resource (tree) into target resource (tree). 02322 ** 02323 ** ### more doc... 02324 ** 02325 ** This hook is optional; if the provider does not support merging, 02326 ** then this should be set to NULL. 02327 */ 02328 dav_error * (*merge)(dav_resource *target, dav_resource *source, 02329 int no_auto_merge, int no_checkout, 02330 apr_xml_elem *prop_elem, 02331 ap_filter_t *output); 02332 02333 /* 02334 ** If a provider needs a context to associate with this hooks structure, 02335 ** then this field may be used. In most cases, it will just be NULL. 02336 */ 02337 void *ctx; 02338 }; 02339 02340 02341 /* -------------------------------------------------------------------- 02342 ** 02343 ** BINDING FUNCTIONS 02344 */ 02345 02346 /* binding provider hooks */ 02347 struct dav_hooks_binding { 02348 02349 /* Determine whether a resource can be the target of a binding. 02350 * Returns 0 if the resource cannot be a binding target. 02351 */ 02352 int (*is_bindable)(const dav_resource *resource); 02353 02354 /* Create a binding to a resource. 02355 * The resource argument is the target of the binding; 02356 * the binding argument must be a resource which does not already 02357 * exist. 02358 */ 02359 dav_error * (*bind_resource)(const dav_resource *resource, 02360 dav_resource *binding); 02361 02362 /* 02363 ** If a provider needs a context to associate with this hooks structure, 02364 ** then this field may be used. In most cases, it will just be NULL. 02365 */ 02366 void *ctx; 02367 02368 }; 02369 02370 02371 /* -------------------------------------------------------------------- 02372 ** 02373 ** SEARCH(DASL) FUNCTIONS 02374 */ 02375 02376 /* search provider hooks */ 02377 struct dav_hooks_search { 02378 /* Set header for a OPTION method 02379 * An error may be returned. 02380 * To set a hadder, this function might call 02381 * apr_table_setn(r->headers_out, "DASL", dasl_optin1); 02382 * 02383 * Examples: 02384 * DASL: <DAV:basicsearch> 02385 * DASL: <http://foo.bar.com/syntax1> 02386 * DASL: <http://akuma.com/syntax2> 02387 */ 02388 dav_error * (*set_option_head)(request_rec *r); 02389 02390 /* Search resources 02391 * An error may be returned. *response will contain multistatus 02392 * responses (if any) suitable for the body of the error. It is also 02393 * possible to return NULL, yet still have multistatus responses. 02394 * In this case, typically the caller should return a 207 (Multistatus) 02395 * and the responses (in the body) as the HTTP response. 02396 */ 02397 dav_error * (*search_resource)(request_rec *r, 02398 dav_response **response); 02399 02400 /* 02401 ** If a provider needs a context to associate with this hooks structure, 02402 ** then this field may be used. In most cases, it will just be NULL. 02403 */ 02404 void *ctx; 02405 02406 }; 02407 02408 02409 /* -------------------------------------------------------------------- 02410 ** 02411 ** MISCELLANEOUS STUFF 02412 */ 02413 02414 /* fetch the "LimitXMLRequestBody" in force for this resource */ 02415 DAV_DECLARE(apr_size_t) dav_get_limit_xml_body(const request_rec *r); 02416 02417 typedef struct { 02418 int propid; /* live property ID */ 02419 const dav_hooks_liveprop *provider; /* the provider defining this prop */ 02420 } dav_elem_private; 02421 02422 #ifdef __cplusplus 02423 } 02424 #endif 02425 02426 #endif /* _MOD_DAV_H_ */ 02427
1.4.7