1 /** 2 * @copyright 3 * ==================================================================== 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 * ==================================================================== 21 * @endcopyright 22 * 23 * @file svn_delta.h 24 * @brief Delta-parsing 25 */ 26 27 /* ==================================================================== */ 28 29 30 31 #ifndef SVN_DELTA_H 32 #define SVN_DELTA_H 33 34 #include <apr.h> 35 #include <apr_pools.h> 36 #include <apr_hash.h> 37 #include <apr_tables.h> 38 #include <apr_file_io.h> /* for apr_file_t */ 39 40 #include "svn_types.h" 41 #include "svn_string.h" 42 #include "svn_io.h" 43 #include "svn_checksum.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif /* __cplusplus */ 48 49 50 51 /** This compression level effectively disables data compression. 52 * However, the data pre-processing costs may still not be zero. 53 * 54 * @since New in 1.7. 55 */ 56 #define SVN_DELTA_COMPRESSION_LEVEL_NONE 0 57 58 /** This is the maximum compression level we can pass to zlib. 59 * 60 * @since New in 1.7. 61 */ 62 #define SVN_DELTA_COMPRESSION_LEVEL_MAX 9 63 64 /** This is the default compression level we pass to zlib. It 65 * should be between 0 and 9, with higher numbers resulting in 66 * better compression rates but slower operation. 67 * 68 * @since New in 1.7. 69 */ 70 #define SVN_DELTA_COMPRESSION_LEVEL_DEFAULT 5 71 72 /** 73 * Get libsvn_delta version information. 74 * 75 * @since New in 1.1. 76 */ 77 const svn_version_t * 78 svn_delta_version(void); 79 80 /** 81 * @defgroup delta_support Delta generation and handling 82 * 83 * @{ 84 */ 85 86 /** Text deltas. 87 * 88 * A text delta represents the difference between two strings of 89 * bytes, the `source' string and the `target' string. Given a source 90 * string and a target string, we can compute a text delta; given a 91 * source string and a delta, we can reconstruct the target string. 92 * However, note that deltas are not reversible: you cannot always 93 * reconstruct the source string given the target string and delta. 94 * 95 * Since text deltas can be very large, the interface here allows us 96 * to produce and consume them in pieces. Each piece, represented by 97 * an #svn_txdelta_window_t structure, describes how to produce the 98 * next section of the target string. 99 * 100 * To compute a new text delta: 101 * 102 * - We call svn_txdelta() on the streams we want to compare. That 103 * returns us an #svn_txdelta_stream_t object. 104 * 105 * - We then call svn_txdelta_next_window() on the stream object 106 * repeatedly. Each call returns a new #svn_txdelta_window_t 107 * object, which describes the next portion of the target string. 108 * When svn_txdelta_next_window() returns zero, we are done building 109 * the target string. 110 * 111 * @defgroup svn_delta_txt_delta Text deltas 112 * @{ 113 */ 114 115 /** Action codes for text delta instructions. */ 116 enum svn_delta_action { 117 /* Note: The svndiff implementation relies on the values assigned in 118 * this enumeration matching the instruction encoding values. */ 119 120 /** Append the @a length bytes at @a offset in the source view to the 121 * target. 122 * 123 * It must be the case that 0 <= @a offset < @a offset + 124 * @a length <= size of source view. 125 */ 126 svn_txdelta_source, 127 128 /** Append the @a length bytes at @a offset in the target view, to the 129 * target. 130 * 131 * It must be the case that 0 <= @a offset < current position in the 132 * target view. 133 * 134 * However! @a offset + @a length may be *beyond* the end of the existing 135 * target data. "Where the heck does the text come from, then?" 136 * If you start at @a offset, and append @a length bytes one at a time, 137 * it'll work out --- you're adding new bytes to the end at the 138 * same rate you're reading them from the middle. Thus, if your 139 * current target text is "abcdefgh", and you get an #svn_txdelta_target 140 * instruction whose @a offset is 6 and whose @a length is 7, 141 * the resulting string is "abcdefghghghghg". This trick is actually 142 * useful in encoding long runs of consecutive characters, long runs 143 * of CR/LF pairs, etc. 144 */ 145 svn_txdelta_target, 146 147 /** Append the @a length bytes at @a offset in the window's @a new string 148 * to the target. 149 * 150 * It must be the case that 0 <= @a offset < @a offset + 151 * @a length <= length of @a new. Windows MUST use new data in ascending 152 * order with no overlap at the moment; svn_txdelta_to_svndiff() 153 * depends on this. 154 */ 155 svn_txdelta_new 156 }; 157 158 /** A single text delta instruction. */ 159 typedef struct svn_txdelta_op_t 160 { 161 /** Action code of delta instruction */ 162 enum svn_delta_action action_code; 163 /** Offset of delta, see #svn_delta_action for more details. */ 164 apr_size_t offset; 165 /** Number of bytes of delta, see #svn_delta_action for more details. */ 166 apr_size_t length; 167 } svn_txdelta_op_t; 168 169 170 /** An #svn_txdelta_window_t object describes how to reconstruct a 171 * contiguous section of the target string (the "target view") using a 172 * specified contiguous region of the source string (the "source 173 * view"). It contains a series of instructions which assemble the 174 * new target string text by pulling together substrings from: 175 * 176 * - the source view, 177 * 178 * - the previously constructed portion of the target view, 179 * 180 * - a string of new data contained within the window structure 181 * 182 * The source view must always slide forward from one window to the 183 * next; that is, neither the beginning nor the end of the source view 184 * may move to the left as we read from a window stream. This 185 * property allows us to apply deltas to non-seekable source streams 186 * without making a full copy of the source stream. 187 */ 188 typedef struct svn_txdelta_window_t 189 { 190 191 /** The offset of the source view for this window. */ 192 svn_filesize_t sview_offset; 193 194 /** The length of the source view for this window. */ 195 apr_size_t sview_len; 196 197 /** The length of the target view for this window, i.e. the number of 198 * bytes which will be reconstructed by the instruction stream. */ 199 apr_size_t tview_len; 200 201 /** The number of instructions in this window. */ 202 int num_ops; 203 204 /** The number of svn_txdelta_source instructions in this window. If 205 * this number is 0, we don't need to read the source in order to 206 * reconstruct the target view. 207 */ 208 int src_ops; 209 210 /** The instructions for this window. */ 211 const svn_txdelta_op_t *ops; 212 213 /** New data, for use by any `svn_txdelta_new' instructions. */ 214 const svn_string_t *new_data; 215 216 } svn_txdelta_window_t; 217 218 /** 219 * Return a deep copy of @a window, allocated in @a pool. 220 * 221 * @since New in 1.3. 222 */ 223 svn_txdelta_window_t * 224 svn_txdelta_window_dup(const svn_txdelta_window_t *window, 225 apr_pool_t *pool); 226 227 /** 228 * Compose two delta windows, yielding a third, allocated in @a pool. 229 * 230 * @since New in 1.4 231 * 232 */ 233 svn_txdelta_window_t * 234 svn_txdelta_compose_windows(const svn_txdelta_window_t *window_A, 235 const svn_txdelta_window_t *window_B, 236 apr_pool_t *pool); 237 238 /** 239 * Apply the instructions from @a window to a source view @a sbuf to 240 * produce a target view @a tbuf. 241 * 242 * @a sbuf is assumed to have @a window->sview_len bytes of data and 243 * @a tbuf is assumed to have room for @a tlen bytes of output. @a 244 * tlen may be more than @a window->tview_len, so return the actual 245 * number of bytes written. @a sbuf is not touched and may be NULL if 246 * @a window contains no source-copy operations. This is purely a 247 * memory operation; nothing can go wrong as long as we have a valid 248 * window. 249 * 250 * @since New in 1.4 251 * 252 * @since Since 1.9, @a tbuf may be NULL if @a *tlen is 0. 253 */ 254 void 255 svn_txdelta_apply_instructions(svn_txdelta_window_t *window, 256 const char *sbuf, char *tbuf, 257 apr_size_t *tlen); 258 259 /** A typedef for functions that consume a series of delta windows, for 260 * use in caller-pushes interfaces. Such functions will typically 261 * apply the delta windows to produce some file, or save the windows 262 * somewhere. At the end of the delta window stream, you must call 263 * this function passing zero for the @a window argument. 264 */ 265 typedef svn_error_t *(*svn_txdelta_window_handler_t)( 266 svn_txdelta_window_t *window, void *baton); 267 268 269 /** This function will generate delta windows that turn @a source into 270 * @a target, and pushing these windows into the @a handler window handler 271 * callback (passing @a handler_baton to each invocation). 272 * 273 * If @a checksum is not NULL, then a checksum (of kind @a checksum_kind) 274 * will be computed for the target stream, and placed into *checksum. 275 * 276 * If @a cancel_func is not NULL, then it should refer to a cancellation 277 * function (along with @a cancel_baton). 278 * 279 * Results (the checksum) will be allocated from @a result_pool, and all 280 * temporary allocations will be performed in @a scratch_pool. 281 * 282 * Note: this function replaces the combination of svn_txdelta() and 283 * svn_txdelta_send_txstream(). 284 * 285 * @since New in 1.6. 286 */ 287 svn_error_t * 288 svn_txdelta_run(svn_stream_t *source, 289 svn_stream_t *target, 290 svn_txdelta_window_handler_t handler, 291 void *handler_baton, 292 svn_checksum_kind_t checksum_kind, 293 svn_checksum_t **checksum, 294 svn_cancel_func_t cancel_func, 295 void *cancel_baton, 296 apr_pool_t *result_pool, 297 apr_pool_t *scratch_pool); 298 299 300 /** A delta stream --- this is the hat from which we pull a series of 301 * svn_txdelta_window_t objects, which, taken in order, describe the 302 * entire target string. This type is defined within libsvn_delta, and 303 * opaque outside that library. 304 */ 305 typedef struct svn_txdelta_stream_t svn_txdelta_stream_t; 306 307 308 /** A typedef for a function that will set @a *window to the next 309 * window from a #svn_txdelta_stream_t object. If there are no more 310 * delta windows, NULL will be used. The returned window, if any, 311 * will be allocated in @a pool. @a baton is the baton specified 312 * when the stream was created. 313 * 314 * @since New in 1.4. 315 */ 316 typedef svn_error_t * 317 (*svn_txdelta_next_window_fn_t)(svn_txdelta_window_t **window, 318 void *baton, 319 apr_pool_t *pool); 320 321 /** A typedef for a function that will return the md5 checksum of the 322 * fulltext deltified by a #svn_txdelta_stream_t object. Will 323 * return NULL if the final null window hasn't yet been returned by 324 * the stream. The returned value will be allocated in the same pool 325 * as the stream. @a baton is the baton specified when the stream was 326 * created. 327 * 328 * @since New in 1.4. 329 */ 330 typedef const unsigned char * 331 (*svn_txdelta_md5_digest_fn_t)(void *baton); 332 333 /** A typedef for a function that opens an #svn_txdelta_stream_t object, 334 * allocated in @a result_pool. @a baton is provided by the caller. 335 * Any temporary allocations may be performed in @a scratch_pool. 336 * 337 * @since New in 1.10. 338 */ 339 typedef svn_error_t * 340 (*svn_txdelta_stream_open_func_t)(svn_txdelta_stream_t **txdelta_stream, 341 void *baton, 342 apr_pool_t *result_pool, 343 apr_pool_t *scratch_pool); 344 345 /** Create and return a generic text delta stream with @a baton, @a 346 * next_window and @a md5_digest. Allocate the new stream in @a 347 * pool. 348 * 349 * @since New in 1.4. 350 */ 351 svn_txdelta_stream_t * 352 svn_txdelta_stream_create(void *baton, 353 svn_txdelta_next_window_fn_t next_window, 354 svn_txdelta_md5_digest_fn_t md5_digest, 355 apr_pool_t *pool); 356 357 /** Set @a *window to a pointer to the next window from the delta stream 358 * @a stream. When we have completely reconstructed the target string, 359 * set @a *window to zero. 360 * 361 * The window will be allocated in @a pool. 362 */ 363 svn_error_t * 364 svn_txdelta_next_window(svn_txdelta_window_t **window, 365 svn_txdelta_stream_t *stream, 366 apr_pool_t *pool); 367 368 369 /** Return the md5 digest for the complete fulltext deltified by 370 * @a stream, or @c NULL if @a stream has not yet returned its final 371 * @c NULL window. The digest is allocated in the same memory as @a 372 * STREAM. 373 */ 374 const unsigned char * 375 svn_txdelta_md5_digest(svn_txdelta_stream_t *stream); 376 377 /** Set @a *stream to a pointer to a delta stream that will turn the byte 378 * string from @a source into the byte stream from @a target. 379 * 380 * @a source and @a target are both readable generic streams. When we call 381 * svn_txdelta_next_window() on @a *stream, it will read from @a source and 382 * @a target to gather as much data as it needs. If @a calculate_checksum 383 * is set, you may call svn_txdelta_md5_digest() to get an MD5 checksum 384 * for @a target. 385 * 386 * Do any necessary allocation in a sub-pool of @a pool. 387 * 388 * @since New in 1.8. 389 */ 390 void 391 svn_txdelta2(svn_txdelta_stream_t **stream, 392 svn_stream_t *source, 393 svn_stream_t *target, 394 svn_boolean_t calculate_checksum, 395 apr_pool_t *pool); 396 397 /** Similar to svn_txdelta2 but always calculating the target checksum. 398 * 399 * @deprecated Provided for backward compatibility with the 1.7 API. 400 */ 401 SVN_DEPRECATED 402 void 403 svn_txdelta(svn_txdelta_stream_t **stream, 404 svn_stream_t *source, 405 svn_stream_t *target, 406 apr_pool_t *pool); 407 408 409 /** 410 * Return a writable stream which, when fed target data, will send 411 * delta windows to @a handler/@a handler_baton which transform the 412 * data in @a source to the target data. As usual, the window handler 413 * will receive a NULL window to signify the end of the window stream. 414 * The stream handler functions will read data from @a source as 415 * necessary. 416 * 417 * @since New in 1.1. 418 */ 419 svn_stream_t * 420 svn_txdelta_target_push(svn_txdelta_window_handler_t handler, 421 void *handler_baton, 422 svn_stream_t *source, 423 apr_pool_t *pool); 424 425 426 /** Send the contents of @a string to window-handler @a handler/@a baton. 427 * This is effectively a 'copy' operation, resulting in delta windows that 428 * make the target equivalent to the value of @a string. 429 * 430 * All temporary allocation is performed in @a pool. 431 */ 432 svn_error_t * 433 svn_txdelta_send_string(const svn_string_t *string, 434 svn_txdelta_window_handler_t handler, 435 void *handler_baton, 436 apr_pool_t *pool); 437 438 /** Send the contents of @a stream to window-handler @a handler/@a baton. 439 * This is effectively a 'copy' operation, resulting in delta windows that 440 * make the target equivalent to the stream. 441 * 442 * If @a digest is non-NULL, populate it with the md5 checksum for the 443 * fulltext that was deltified (@a digest must be at least 444 * @c APR_MD5_DIGESTSIZE bytes long). 445 * 446 * All temporary allocation is performed in @a pool. 447 */ 448 svn_error_t * 449 svn_txdelta_send_stream(svn_stream_t *stream, 450 svn_txdelta_window_handler_t handler, 451 void *handler_baton, 452 unsigned char *digest, 453 apr_pool_t *pool); 454 455 /** Send the contents of @a txstream to window-handler @a handler/@a baton. 456 * Windows will be extracted from the stream and delivered to the handler. 457 * 458 * All temporary allocation is performed in @a pool. 459 */ 460 svn_error_t * 461 svn_txdelta_send_txstream(svn_txdelta_stream_t *txstream, 462 svn_txdelta_window_handler_t handler, 463 void *handler_baton, 464 apr_pool_t *pool); 465 466 467 /** Send the @a contents of length @a len as a txdelta against an empty 468 * source directly to window-handler @a handler/@a handler_baton. 469 * 470 * All temporary allocation is performed in @a pool. 471 * 472 * @since New in 1.8. 473 */ 474 svn_error_t * 475 svn_txdelta_send_contents(const unsigned char *contents, 476 apr_size_t len, 477 svn_txdelta_window_handler_t handler, 478 void *handler_baton, 479 apr_pool_t *pool); 480 481 /** Prepare to apply a text delta. @a source is a readable generic stream 482 * yielding the source data, @a target is a writable generic stream to 483 * write target data to, and allocation takes place in a sub-pool of 484 * @a pool. On return, @a *handler is set to a window handler function and 485 * @a *handler_baton is set to the value to pass as the @a baton argument to 486 * @a *handler. 487 * 488 * If @a result_digest is non-NULL, it points to APR_MD5_DIGESTSIZE bytes 489 * of storage, and the final call to @a handler populates it with the 490 * MD5 digest of the resulting fulltext. 491 * 492 * If @a error_info is non-NULL, it is inserted parenthetically into 493 * the error string for any error returned by svn_txdelta_apply() or 494 * @a *handler. (It is normally used to provide path information, 495 * since there's nothing else in the delta application's context to 496 * supply a path for error messages.) 497 * 498 * The @a source stream will NOT be closed. The @a target stream will be 499 * closed when the window handler is given a null window to signal the 500 * end of the delta. 501 * 502 * @note To avoid lifetime issues, @a error_info is copied into 503 * @a pool or a subpool thereof. 504 */ 505 void 506 svn_txdelta_apply(svn_stream_t *source, 507 svn_stream_t *target, 508 unsigned char *result_digest, 509 const char *error_info, 510 apr_pool_t *pool, 511 svn_txdelta_window_handler_t *handler, 512 void **handler_baton); 513 514 515 516 517 /*** Producing and consuming svndiff-format text deltas. ***/ 518 519 /** Prepare to produce an svndiff-format diff from text delta windows. 520 * @a output is a writable generic stream to write the svndiff data to. 521 * Allocation takes place in a sub-pool of @a pool. On return, @a *handler 522 * is set to a window handler function and @a *handler_baton is set to 523 * the value to pass as the @a baton argument to @a *handler. The svndiff 524 * version is @a svndiff_version. @a compression_level is the zlib 525 * compression level from 0 (no compression) and 9 (maximum compression). 526 * 527 * @since New in 1.7. Since 1.10, @a svndiff_version can be 2 for the 528 * svndiff2 format. @a compression_level is currently ignored if 529 * @a svndiff_version is set to 2. 530 */ 531 void 532 svn_txdelta_to_svndiff3(svn_txdelta_window_handler_t *handler, 533 void **handler_baton, 534 svn_stream_t *output, 535 int svndiff_version, 536 int compression_level, 537 apr_pool_t *pool); 538 539 /** Similar to svn_txdelta_to_svndiff3(), but always using the SVN default 540 * compression level (#SVN_DELTA_COMPRESSION_LEVEL_DEFAULT). 541 * 542 * @since New in 1.4. 543 * @deprecated Provided for backward compatibility with the 1.6 API. 544 */ 545 SVN_DEPRECATED 546 void 547 svn_txdelta_to_svndiff2(svn_txdelta_window_handler_t *handler, 548 void **handler_baton, 549 svn_stream_t *output, 550 int svndiff_version, 551 apr_pool_t *pool); 552 553 /** Similar to svn_txdelta_to_svndiff2, but always using svndiff 554 * version 0. 555 * 556 * @deprecated Provided for backward compatibility with the 1.3 API. 557 */ 558 SVN_DEPRECATED 559 void 560 svn_txdelta_to_svndiff(svn_stream_t *output, 561 apr_pool_t *pool, 562 svn_txdelta_window_handler_t *handler, 563 void **handler_baton); 564 565 /** Return a readable generic stream which will produce svndiff-encoded 566 * text delta from the delta stream @a txstream. @a svndiff_version and 567 * @a compression_level are same as in svn_txdelta_to_svndiff3(). 568 * 569 * Allocate the stream in @a pool. 570 * 571 * @since New in 1.10. 572 */ 573 svn_stream_t * 574 svn_txdelta_to_svndiff_stream(svn_txdelta_stream_t *txstream, 575 int svndiff_version, 576 int compression_level, 577 apr_pool_t *pool); 578 579 /** Return a writable generic stream which will parse svndiff-format 580 * data into a text delta, invoking @a handler with @a handler_baton 581 * whenever a new window is ready. 582 * 583 * When the caller closes this stream, this will signal completion to 584 * the window handler by invoking @a handler once more, passing zero for 585 * the @c window argument. 586 * 587 * If @a error_on_early_close is @c TRUE, then attempt to avoid 588 * signaling completion to the window handler if the delta was 589 * incomplete. Specifically, attempting to close the stream will be 590 * successful only if the data written to the stream consisted of one or 591 * more complete windows of svndiff data and no extra bytes. Otherwise, 592 * closing the stream will not signal completion to the window handler, 593 * and will return a #SVN_ERR_SVNDIFF_UNEXPECTED_END error. Note that if 594 * no data at all was written, the delta is considered incomplete. 595 * 596 * If @a error_on_early_close is @c FALSE, closing the stream will 597 * signal completion to the window handler, regardless of how much data 598 * was written, and discard any pending incomplete data. 599 * 600 * Allocate the stream in @a pool. 601 */ 602 svn_stream_t * 603 svn_txdelta_parse_svndiff(svn_txdelta_window_handler_t handler, 604 void *handler_baton, 605 svn_boolean_t error_on_early_close, 606 apr_pool_t *pool); 607 608 /** 609 * Read and parse one delta window in svndiff format from the 610 * readable stream @a stream and place it in @a *window, allocating 611 * the result in @a pool. The caller must take responsibility for 612 * stripping off the four-byte 'SVN@<ver@>' header at the beginning of 613 * the svndiff document before reading the first window, and must 614 * provide the version number (the value of the fourth byte) to each 615 * invocation of this routine with the @a svndiff_version argument. 616 * 617 * @since New in 1.1. 618 */ 619 svn_error_t * 620 svn_txdelta_read_svndiff_window(svn_txdelta_window_t **window, 621 svn_stream_t *stream, 622 int svndiff_version, 623 apr_pool_t *pool); 624 625 /** 626 * Read and skip one delta window in svndiff format from the 627 * file @a file. @a pool is used for temporary allocations. The 628 * caller must take responsibility for stripping off the four-byte 629 * 'SVN@<ver@>' header at the beginning of the svndiff document before 630 * reading or skipping the first window, and must provide the version 631 * number (the value of the fourth byte) to each invocation of this 632 * routine with the @a svndiff_version argument. 633 * 634 * @since New in 1.1. 635 */ 636 svn_error_t * 637 svn_txdelta_skip_svndiff_window(apr_file_t *file, 638 int svndiff_version, 639 apr_pool_t *pool); 640 641 /** @} */ 642 643 644 /** Traversing tree deltas. 645 * 646 * In Subversion, we've got various producers and consumers of tree 647 * deltas. 648 * 649 * In processing a `commit' command: 650 * - The client examines its working copy data, and produces a tree 651 * delta describing the changes to be committed. 652 * - The client networking library consumes that delta, and sends them 653 * across the wire as an equivalent series of network requests (for 654 * example, to svnserve as an ra_svn protocol stream, or to an 655 * Apache httpd server as WebDAV commands) 656 * - The server receives those requests and produces a tree delta --- 657 * hopefully equivalent to the one the client produced above. 658 * - The Subversion server module consumes that delta and commits an 659 * appropriate transaction to the filesystem. 660 * 661 * In processing an `update' command, the process is reversed: 662 * - The Subversion server module talks to the filesystem and produces 663 * a tree delta describing the changes necessary to bring the 664 * client's working copy up to date. 665 * - The server consumes this delta, and assembles a reply 666 * representing the appropriate changes. 667 * - The client networking library receives that reply, and produces a 668 * tree delta --- hopefully equivalent to the one the Subversion 669 * server produced above. 670 * - The working copy library consumes that delta, and makes the 671 * appropriate changes to the working copy. 672 * 673 * The simplest approach would be to represent tree deltas using the 674 * obvious data structure. To do an update, the server would 675 * construct a delta structure, and the working copy library would 676 * apply that structure to the working copy; the network layer's job 677 * would simply be to get the structure across the net intact. 678 * 679 * However, we expect that these deltas will occasionally be too large 680 * to fit in a typical workstation's swap area. For example, in 681 * checking out a 200Mb source tree, the entire source tree is 682 * represented by a single tree delta. So it's important to handle 683 * deltas that are too large to fit in swap all at once. 684 * 685 * So instead of representing the tree delta explicitly, we define a 686 * standard way for a consumer to process each piece of a tree delta 687 * as soon as the producer creates it. The #svn_delta_editor_t 688 * structure is a set of callback functions to be defined by a delta 689 * consumer, and invoked by a delta producer. Each invocation of a 690 * callback function describes a piece of the delta --- a file's 691 * contents changing, something being renamed, etc. 692 * 693 * @defgroup svn_delta_tree_deltas Tree deltas 694 * @{ 695 */ 696 697 /** A structure full of callback functions the delta source will invoke 698 * as it produces the delta. 699 * 700 * @note Don't try to allocate one of these yourself. Instead, always 701 * use svn_delta_default_editor() or some other constructor, to avoid 702 * backwards compatibility problems if the structure is extended in 703 * future releases and to ensure that unused slots are filled in with 704 * no-op functions. 705 * 706 * <h3>Function Usage</h3> 707 * 708 * Here's how to use these functions to express a tree delta. 709 * 710 * The delta consumer implements the callback functions described in 711 * this structure, and the delta producer invokes them. So the 712 * caller (producer) is pushing tree delta data at the callee 713 * (consumer). 714 * 715 * At the start of traversal, the consumer provides @a edit_baton, a 716 * baton global to the entire delta edit. If there is a target 717 * revision that needs to be set for this operation, the producer 718 * should call the @c set_target_revision function at this point. 719 * 720 * Next, if there are any tree deltas to express, the producer should 721 * pass the @a edit_baton to the @c open_root function, to get a baton 722 * representing root of the tree being edited. 723 * 724 * Most of the callbacks work in the obvious way: 725 * 726 * @c delete_entry 727 * @c add_file 728 * @c add_directory 729 * @c open_file 730 * @c open_directory 731 * 732 * Each of these takes a directory baton, indicating the directory 733 * in which the change takes place, and a @a path argument, giving the 734 * path of the file, subdirectory, or directory entry to change. 735 * 736 * The @a path argument to each of the callbacks is relative to the 737 * root of the edit. Editors will usually want to join this relative 738 * path with some base stored in the edit baton (e.g. a URL, or a 739 * location in the OS filesystem). 740 * 741 * Since every call requires a parent directory baton, including 742 * @c add_directory and @c open_directory, where do we ever get our 743 * initial directory baton, to get things started? The @c open_root 744 * function returns a baton for the top directory of the change. In 745 * general, the producer needs to invoke the editor's @c open_root 746 * function before it can get anything of interest done. 747 * 748 * While @c open_root provides a directory baton for the root of 749 * the tree being changed, the @c add_directory and @c open_directory 750 * callbacks provide batons for other directories. Like the 751 * callbacks above, they take a @a parent_baton and a relative path 752 * @a path, and then return a new baton for the subdirectory being 753 * created / modified --- @a child_baton. The producer can then use 754 * @a child_baton to make further changes in that subdirectory. 755 * 756 * So, if we already have subdirectories named `foo' and `foo/bar', 757 * then the producer can create a new file named `foo/bar/baz.c' by 758 * calling: 759 * 760 * - @c open_root () --- yielding a baton @a root for the top directory 761 * 762 * - @c open_directory (@a root, "foo") --- yielding a baton @a f for `foo' 763 * 764 * - @c open_directory (@a f, "foo/bar") --- yielding a baton @a b for 765 * `foo/bar' 766 * 767 * - @c add_file (@a b, "foo/bar/baz.c") 768 * 769 * When the producer is finished making changes to a directory, it 770 * should call @c close_directory. This lets the consumer do any 771 * necessary cleanup, and free the baton's storage. 772 * 773 * The @c add_file and @c open_file callbacks each return a baton 774 * for the file being created or changed. This baton can then be 775 * passed to @c apply_textdelta or @c apply_textdelta_stream to change 776 * the file's contents, or @c change_file_prop to change the file's 777 * properties. When the producer is finished making changes to a 778 * file, it should call @c close_file, to let the consumer clean up 779 * and free the baton. 780 * 781 * The @c add_file and @c add_directory functions each take arguments 782 * @a copyfrom_path and @a copyfrom_revision. If @a copyfrom_path is 783 * non-@c NULL, then @a copyfrom_path and @a copyfrom_revision indicate where 784 * the file or directory should be copied from (to create the file 785 * or directory being added). In that case, @a copyfrom_path must be 786 * either a path relative to the root of the edit, or a URI from the 787 * repository being edited. If @a copyfrom_path is @c NULL, then @a 788 * copyfrom_revision must be #SVN_INVALID_REVNUM; it is invalid to 789 * pass a mix of valid and invalid copyfrom arguments. 790 * 791 * 792 * <h3>Function Call Ordering</h3> 793 * 794 * There are six restrictions on the order in which the producer 795 * may use the batons: 796 * 797 * 1. The producer may call @c open_directory, @c add_directory, 798 * @c open_file, @c add_file at most once on any given directory 799 * entry. @c delete_entry may be called at most once on any given 800 * directory entry and may later be followed by @c add_directory or 801 * @c add_file on the same directory entry. @c delete_entry may 802 * not be called on any directory entry after @c open_directory, 803 * @c add_directory, @c open_file or @c add_file has been called on 804 * that directory entry. 805 * 806 * 2. The producer may not close a directory baton until it has 807 * closed all batons for its subdirectories. 808 * 809 * 3. When a producer calls @c open_directory or @c add_directory, 810 * it must specify the most recently opened of the currently open 811 * directory batons. Put another way, the producer cannot have 812 * two sibling directory batons open at the same time. 813 * 814 * 4. A producer must call @c change_dir_prop on a directory either 815 * before opening any of the directory's subdirs or after closing 816 * them, but not in the middle. 817 * 818 * 5. When the producer calls @c open_file or @c add_file, either: 819 * 820 * (a) The producer must follow with any changes to the file 821 * (@c change_file_prop and/or @c apply_textdelta / 822 * @c apply_textdelta_stream, as applicable), followed by 823 * a @c close_file call, before issuing any other file or 824 * directory calls, or 825 * 826 * (b) The producer must follow with a @c change_file_prop call if 827 * it is applicable, before issuing any other file or directory 828 * calls; later, after all directory batons including the root 829 * have been closed, the producer must issue @c apply_textdelta / 830 * @c apply_textdelta_stream and @c close_file calls. 831 * 832 * 6. When the producer calls @c apply_textdelta, it must make all of 833 * the window handler calls (including the @c NULL window at the 834 * end) before issuing any other #svn_delta_editor_t calls. 835 * 836 * So, the producer needs to use directory and file batons as if it 837 * is doing a single depth-first traversal of the tree, with the 838 * exception that the producer may keep file batons open in order to 839 * make @c apply_textdelta / @c apply_textdelta_stream calls at the end. 840 * 841 * 842 * <h3>Pool Usage</h3> 843 * 844 * Many editor functions are invoked multiple times, in a sequence 845 * determined by the editor "driver". The driver is responsible for 846 * creating a pool for use on each iteration of the editor function, 847 * and clearing that pool between each iteration. The driver passes 848 * the appropriate pool on each function invocation. 849 * 850 * Based on the requirement of calling the editor functions in a 851 * depth-first style, it is usually customary for the driver to similarly 852 * nest the pools. However, this is only a safety feature to ensure 853 * that pools associated with deeper items are always cleared when the 854 * top-level items are also cleared. The interface does not assume, nor 855 * require, any particular organization of the pools passed to these 856 * functions. In fact, if "postfix deltas" are used for files, the file 857 * pools definitely need to live outside the scope of their parent 858 * directories' pools. 859 * 860 * Note that close_directory can be called *before* a file in that 861 * directory has been closed. That is, the directory's baton is 862 * closed before the file's baton. The implication is that 863 * @c apply_textdelta / @c apply_textdelta_stream and @c close_file 864 * should not refer to a parent directory baton UNLESS the editor has 865 * taken precautions to allocate it in a pool of the appropriate 866 * lifetime (the @a result_pool passed to @c open_directory and 867 * @c add_directory definitely does not have the proper lifetime). 868 * In general, it is recommended to simply avoid keeping a parent 869 * directory baton in a file baton. 870 * 871 * 872 * <h3>Errors</h3> 873 * 874 * At least one implementation of the editor interface is 875 * asynchronous; an error from one operation may be detected some 876 * number of operations later. As a result, an editor driver must not 877 * assume that an error from an editing function resulted from the 878 * particular operation being detected. Moreover, once an editing 879 * function (including @c close_edit) returns an error, the edit is 880 * dead; the only further operation which may be called on the editor 881 * is @c abort_edit. 882 */ 883 typedef struct svn_delta_editor_t 884 { 885 /** Set the target revision for this edit to @a target_revision. This 886 * call, if used, should precede all other editor calls. 887 * 888 * @note This is typically used only for server->client update-type 889 * operations. It doesn't really make much sense for commit-type 890 * operations, because the revision of a commit isn't known until 891 * the commit is finalized. 892 * 893 * Any temporary allocations may be performed in @a scratch_pool. 894 */ 895 svn_error_t *(*set_target_revision)(void *edit_baton, 896 svn_revnum_t target_revision, 897 apr_pool_t *scratch_pool); 898 899 /** Set @a *root_baton to a baton for the top directory of the change. 900 * (This is the top of the subtree being changed, not necessarily 901 * the root of the filesystem.) As with any other directory baton, the 902 * producer should call @c close_directory on @a root_baton when done. 903 * And as with other @c open_* calls, the @a base_revision here is the 904 * current revision of the directory (before getting bumped up to the 905 * new target revision set with @c set_target_revision). 906 * 907 * Allocations for the returned @a root_baton should be performed in 908 * @a result_pool. It is also typical to (possibly) save this pool for 909 * later usage by @c close_directory. 910 */ 911 svn_error_t *(*open_root)(void *edit_baton, 912 svn_revnum_t base_revision, 913 apr_pool_t *result_pool, 914 void **root_baton); 915 916 917 /** Remove the directory entry at @a path, a child of the directory 918 * represented by @a parent_baton. If @a revision is a valid 919 * revision number, it is used as a sanity check to ensure that you 920 * are really removing the revision of @a path that you think you are. 921 * 922 * Any temporary allocations may be performed in @a scratch_pool. 923 * 924 * @note The @a revision parameter is typically used only for 925 * client->server commit-type operations, allowing the server to 926 * verify that it is deleting what the client thinks it should be 927 * deleting. It only really makes sense in the opposite direction 928 * (during server->client update-type operations) when the trees 929 * whose delta is being described are ancestrally related (that is, 930 * one tree is an ancestor of the other). 931 */ 932 svn_error_t *(*delete_entry)(const char *path, 933 svn_revnum_t revision, 934 void *parent_baton, 935 apr_pool_t *scratch_pool); 936 937 938 /** We are going to add a new subdirectory at @a path, a child of 939 * the directory represented by @a parent_baton. We will use 940 * the value this callback stores in @a *child_baton as the 941 * parent baton for further changes in the new subdirectory. 942 * 943 * If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a 944 * copy), and the origin of the copy may be recorded as 945 * @a copyfrom_path under @a copyfrom_revision. 946 * 947 * Allocations for the returned @a child_baton should be performed in 948 * @a result_pool. It is also typical to (possibly) save this pool for 949 * later usage by @c close_directory. 950 */ 951 svn_error_t *(*add_directory)(const char *path, 952 void *parent_baton, 953 const char *copyfrom_path, 954 svn_revnum_t copyfrom_revision, 955 apr_pool_t *result_pool, 956 void **child_baton); 957 958 /** We are going to make changes in the subdirectory at @a path, a 959 * child of the directory represented by @a parent_baton. 960 * The callback must store a value in @a *child_baton that 961 * should be used as the parent baton for subsequent changes in this 962 * subdirectory. If a valid revnum, @a base_revision is the current 963 * revision of the subdirectory. 964 * 965 * Allocations for the returned @a child_baton should be performed in 966 * @a result_pool. It is also typical to (possibly) save this pool for 967 * later usage by @c close_directory. 968 */ 969 svn_error_t *(*open_directory)(const char *path, 970 void *parent_baton, 971 svn_revnum_t base_revision, 972 apr_pool_t *result_pool, 973 void **child_baton); 974 975 /** Change the value of a directory's property. 976 * - @a dir_baton specifies the directory whose property should change. 977 * - @a name is the name of the property to change. 978 * - @a value is the new (final) value of the property, or @c NULL if the 979 * property should be removed altogether. 980 * 981 * The callback is guaranteed to be called exactly once for each property 982 * whose value differs between the start and the end of the edit. 983 * 984 * Any temporary allocations may be performed in @a scratch_pool. 985 */ 986 svn_error_t *(*change_dir_prop)(void *dir_baton, 987 const char *name, 988 const svn_string_t *value, 989 apr_pool_t *scratch_pool); 990 991 /** We are done processing a subdirectory, whose baton is @a dir_baton 992 * (set by @c add_directory or @c open_directory). We won't be using 993 * the baton any more, so whatever resources it refers to may now be 994 * freed. 995 * 996 * Any temporary allocations may be performed in @a scratch_pool. 997 */ 998 svn_error_t *(*close_directory)(void *dir_baton, 999 apr_pool_t *scratch_pool); 1000 1001 1002 /** In the directory represented by @a parent_baton, indicate that 1003 * @a path is present as a subdirectory in the edit source, but 1004 * cannot be conveyed to the edit consumer. Currently, this would 1005 * only occur because of authorization restrictions, but may change 1006 * in the future. 1007 * 1008 * Any temporary allocations may be performed in @a scratch_pool. 1009 */ 1010 svn_error_t *(*absent_directory)(const char *path, 1011 void *parent_baton, 1012 apr_pool_t *scratch_pool); 1013 1014 /** We are going to add a new file at @a path, a child of the 1015 * directory represented by @a parent_baton. The callback can 1016 * store a baton for this new file in @a **file_baton; whatever value 1017 * it stores there should be passed through to @c apply_textdelta or 1018 * @c apply_textdelta_stream. 1019 * 1020 * If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a 1021 * copy), and the origin of the copy may be recorded as 1022 * @a copyfrom_path under @a copyfrom_revision. 1023 * 1024 * Allocations for the returned @a file_baton should be performed in 1025 * @a result_pool. It is also typical to save this pool for later usage 1026 * by @c apply_textdelta and possibly @c close_file. 1027 * 1028 * @note Because the editor driver could be employing the "postfix 1029 * deltas" paradigm, @a result_pool could potentially be relatively 1030 * long-lived. Every file baton created by the editor for a given 1031 * editor drive might be resident in memory similtaneously. Editor 1032 * implementations should ideally keep their file batons as 1033 * conservative (memory-usage-wise) as possible, and use @a result_pool 1034 * only for those batons. (Consider using a subpool of @a result_pool 1035 * for scratch work, destroying the subpool before exiting this 1036 * function's implementation.) 1037 */ 1038 svn_error_t *(*add_file)(const char *path, 1039 void *parent_baton, 1040 const char *copyfrom_path, 1041 svn_revnum_t copyfrom_revision, 1042 apr_pool_t *result_pool, 1043 void **file_baton); 1044 1045 /** We are going to make changes to a file at @a path, a child of the 1046 * directory represented by @a parent_baton. 1047 * 1048 * The callback can store a baton for this new file in @a **file_baton; 1049 * whatever value it stores there should be passed through to 1050 * @c apply_textdelta or @c apply_textdelta_stream. If a valid revnum, 1051 * @a base_revision is the current revision of the file. 1052 * 1053 * Allocations for the returned @a file_baton should be performed in 1054 * @a result_pool. It is also typical to save this pool for later usage 1055 * by @c apply_textdelta and possibly @c close_file. 1056 * 1057 * @note See note about memory usage on @a add_file, which also 1058 * applies here. 1059 */ 1060 svn_error_t *(*open_file)(const char *path, 1061 void *parent_baton, 1062 svn_revnum_t base_revision, 1063 apr_pool_t *result_pool, 1064 void **file_baton); 1065 1066 /** Apply a text delta, yielding the new revision of a file. 1067 * 1068 * @a file_baton indicates the file we're creating or updating, and the 1069 * ancestor file on which it is based; it is the baton set by some 1070 * prior @c add_file or @c open_file callback. 1071 * 1072 * The callback should set @a *handler to a text delta window 1073 * handler; we will then call @a *handler on successive text 1074 * delta windows as we receive them. The callback should set 1075 * @a *handler_baton to the value we should pass as the @a baton 1076 * argument to @a *handler. These values should be allocated within 1077 * @a result_pool. 1078 * 1079 * @a base_checksum is the hex MD5 digest for the base text against 1080 * which the delta is being applied; it is ignored if NULL, and may 1081 * be ignored even if not NULL. If it is not ignored, it must match 1082 * the checksum of the base text against which svndiff data is being 1083 * applied; if it does not, @c apply_textdelta or the @a *handler call 1084 * which detects the mismatch will return the error 1085 * SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may 1086 * still be an error if @a base_checksum is neither NULL nor the hex 1087 * MD5 checksum of the empty string). 1088 */ 1089 svn_error_t *(*apply_textdelta)(void *file_baton, 1090 const char *base_checksum, 1091 apr_pool_t *result_pool, 1092 svn_txdelta_window_handler_t *handler, 1093 void **handler_baton); 1094 1095 /** Change the value of a file's property. 1096 * - @a file_baton specifies the file whose property should change. 1097 * - @a name is the name of the property to change. 1098 * - @a value is the new (final) value of the property, or @c NULL if the 1099 * property should be removed altogether. 1100 * 1101 * The callback is guaranteed to be called exactly once for each property 1102 * whose value differs between the start and the end of the edit. 1103 * 1104 * Any temporary allocations may be performed in @a scratch_pool. 1105 */ 1106 svn_error_t *(*change_file_prop)(void *file_baton, 1107 const char *name, 1108 const svn_string_t *value, 1109 apr_pool_t *scratch_pool); 1110 1111 /** We are done processing a file, whose baton is @a file_baton (set by 1112 * @c add_file or @c open_file). We won't be using the baton any 1113 * more, so whatever resources it refers to may now be freed. 1114 * 1115 * @a text_checksum is the hex MD5 digest for the fulltext that 1116 * resulted from a delta application, see @c apply_textdelta and 1117 * @c apply_textdelta_stream. The checksum is ignored if NULL. 1118 * If not null, it is compared to the checksum of the new fulltext, 1119 * and the error SVN_ERR_CHECKSUM_MISMATCH is returned if they do 1120 * not match. If there is no new fulltext, @a text_checksum is ignored. 1121 * 1122 * Any temporary allocations may be performed in @a scratch_pool. 1123 */ 1124 svn_error_t *(*close_file)(void *file_baton, 1125 const char *text_checksum, 1126 apr_pool_t *scratch_pool); 1127 1128 /** In the directory represented by @a parent_baton, indicate that 1129 * @a path is present as a file in the edit source, but cannot be 1130 * cannot be conveyed to the edit consumer. Currently, this would 1131 * only occur because of authorization restrictions, but may change 1132 * in the future. 1133 * 1134 * Any temporary allocations may be performed in @a scratch_pool. 1135 */ 1136 svn_error_t *(*absent_file)(const char *path, 1137 void *parent_baton, 1138 apr_pool_t *scratch_pool); 1139 1140 /** All delta processing is done. Call this, with the @a edit_baton for 1141 * the entire edit. 1142 * 1143 * Any temporary allocations may be performed in @a scratch_pool. 1144 */ 1145 svn_error_t *(*close_edit)(void *edit_baton, 1146 apr_pool_t *scratch_pool); 1147 1148 /** The editor-driver has decided to bail out. Allow the editor to 1149 * gracefully clean up things if it needs to. 1150 * 1151 * Any temporary allocations may be performed in @a scratch_pool. 1152 */ 1153 svn_error_t *(*abort_edit)(void *edit_baton, 1154 apr_pool_t *scratch_pool); 1155 1156 /** Apply a text delta stream, yielding the new revision of a file. 1157 * This callback operates on the passed-in @a editor instance. 1158 * 1159 * @a file_baton indicates the file we're creating or updating, and the 1160 * ancestor file on which it is based; it is the baton set by some 1161 * prior @c add_file or @c open_file callback. 1162 * 1163 * @a open_func is a function that opens a #svn_txdelta_stream_t object. 1164 * @a open_baton is provided by the caller. 1165 * 1166 * @a base_checksum is the hex MD5 digest for the base text against 1167 * which the delta is being applied; it is ignored if NULL, and may 1168 * be ignored even if not NULL. If it is not ignored, it must match 1169 * the checksum of the base text against which svndiff data is being 1170 * applied; if it does not, @c apply_textdelta_stream call which detects 1171 * the mismatch will return the error #SVN_ERR_CHECKSUM_MISMATCH 1172 * (if there is no base text, there may still be an error if 1173 * @a base_checksum is neither NULL nor the hex MD5 checksum of the 1174 * empty string). 1175 * 1176 * Any temporary allocations may be performed in @a scratch_pool. 1177 * 1178 * @since New in 1.10. 1179 */ 1180 svn_error_t *(*apply_textdelta_stream)( 1181 const struct svn_delta_editor_t *editor, 1182 void *file_baton, 1183 const char *base_checksum, 1184 svn_txdelta_stream_open_func_t open_func, 1185 void *open_baton, 1186 apr_pool_t *scratch_pool); 1187 1188 /* Be sure to update svn_delta_get_cancellation_editor() and 1189 * svn_delta_default_editor() if you add a new callback here. */ 1190 } svn_delta_editor_t; 1191 1192 1193 /** Return a default delta editor template, allocated in @a pool. 1194 * 1195 * The editor functions in the template do only the most basic 1196 * baton-swapping: each editor function that produces a baton does so 1197 * by copying its incoming baton into the outgoing baton reference. 1198 * 1199 * This editor is not intended to be useful by itself, but is meant to 1200 * be the basis for a useful editor. After getting a default editor, 1201 * you substitute in your own implementations for the editor functions 1202 * you care about. The ones you don't care about, you don't have to 1203 * implement -- you can rely on the template's implementation to 1204 * safely do nothing of consequence. 1205 */ 1206 svn_delta_editor_t * 1207 svn_delta_default_editor(apr_pool_t *pool); 1208 1209 /** A text-delta window handler which does nothing. 1210 * 1211 * Editors can return this handler from @c apply_textdelta if they don't 1212 * care about text delta windows. 1213 */ 1214 svn_error_t * 1215 svn_delta_noop_window_handler(svn_txdelta_window_t *window, 1216 void *baton); 1217 1218 /** Set @a *editor and @a *edit_baton to a cancellation editor that 1219 * wraps @a wrapped_editor and @a wrapped_baton. 1220 * 1221 * The @a editor will call @a cancel_func with @a cancel_baton when each of 1222 * its functions is called, continuing on to call the corresponding wrapped 1223 * function if @a cancel_func returns #SVN_NO_ERROR. 1224 * 1225 * If @a cancel_func is @c NULL, set @a *editor to @a wrapped_editor and 1226 * @a *edit_baton to @a wrapped_baton. 1227 */ 1228 svn_error_t * 1229 svn_delta_get_cancellation_editor(svn_cancel_func_t cancel_func, 1230 void *cancel_baton, 1231 const svn_delta_editor_t *wrapped_editor, 1232 void *wrapped_baton, 1233 const svn_delta_editor_t **editor, 1234 void **edit_baton, 1235 apr_pool_t *pool); 1236 1237 /** Set @a *editor and @a *edit_baton to an depth-based filtering 1238 * editor that wraps @a wrapped_editor and @a wrapped_baton. 1239 * 1240 * The @a editor will track the depth of this drive against the @a 1241 * requested_depth, taking into account whether not the edit drive is 1242 * making use of a target (via @a has_target), and forward editor 1243 * calls which operate "within" the request depth range through to @a 1244 * wrapped_editor. 1245 * 1246 * @a requested_depth must be one of the following depth values: 1247 * #svn_depth_infinity, #svn_depth_empty, #svn_depth_files, 1248 * #svn_depth_immediates, or #svn_depth_unknown. 1249 * 1250 * If filtering is deemed unnecessary (or if @a requested_depth is 1251 * #svn_depth_unknown), @a *editor and @a *edit_baton will be set to @a 1252 * wrapped_editor and @a wrapped_baton, respectively; otherwise, 1253 * they'll be set to new objects allocated from @a pool. 1254 * 1255 * @note Because the svn_delta_editor_t interface's @c delete_entry() 1256 * function doesn't carry node kind information, a depth-based 1257 * filtering editor being asked to filter for #svn_depth_files but 1258 * receiving a @c delete_entry() call on an immediate child of the 1259 * editor's target is unable to know if that deletion should be 1260 * allowed or filtered out -- a delete of a top-level file is okay in 1261 * this case, a delete of a top-level subdirectory is not. As such, 1262 * this filtering editor takes a conservative approach, and ignores 1263 * top-level deletion requests when filtering for #svn_depth_files. 1264 * Fortunately, most non-depth-aware (pre-1.5) Subversion editor 1265 * drivers can be told to drive non-recursively (where non-recursive 1266 * means essentially #svn_depth_files), which means they won't 1267 * transmit out-of-scope editor commands anyway. 1268 * 1269 * @since New in 1.5. 1270 */ 1271 svn_error_t * 1272 svn_delta_depth_filter_editor(const svn_delta_editor_t **editor, 1273 void **edit_baton, 1274 const svn_delta_editor_t *wrapped_editor, 1275 void *wrapped_edit_baton, 1276 svn_depth_t requested_depth, 1277 svn_boolean_t has_target, 1278 apr_pool_t *pool); 1279 1280 /** @} */ 1281 1282 1283 /** Path-based editor drives. 1284 * 1285 * @defgroup svn_delta_path_delta_drivers Path-based delta drivers 1286 * @{ 1287 */ 1288 1289 /** Callback function type for svn_delta_path_driver(). 1290 * 1291 * The handler of this callback is given the callback baton @a 1292 * callback_baton, @a editor and @a edit_baton which represent the 1293 * editor being driven, @a relpath which is a relpath relative to the 1294 * root of the edit, and the @a parent_baton which represents 1295 * @a relpath's parent directory as created by the editor. 1296 * 1297 * If the handler deletes the node at @a relpath (and does not replace it 1298 * with an added directory) it must set @a *dir_baton to null or leave 1299 * it unchanged. 1300 * 1301 * If the handler opens (or adds) a directory at @a relpath, it must set 1302 * @a *dir_baton to the directory baton for @a relpath, generated from 1303 * the same editor. The driver will close the directory later. 1304 * 1305 * If the handler opens (or adds) a file at @a relpath, the handler must 1306 * set @a *dir_baton to null or leave it unchanged. The handler must 1307 * either close the file immediately, or delay that close until the end 1308 * of the edit when svn_delta_path_driver() returns. 1309 * 1310 * Finally, if @a parent_baton is @c NULL, then the root of the edit 1311 * is also one of the paths passed to svn_delta_path_driver(). The 1312 * handler of this callback must call the editor's open_root() 1313 * function and return the top-level root dir baton in @a *dir_baton. 1314 * 1315 * @since New in 1.12. 1316 */ 1317 typedef svn_error_t *(*svn_delta_path_driver_cb_func2_t)( 1318 void **dir_baton, 1319 const svn_delta_editor_t *editor, 1320 void *edit_baton, 1321 void *parent_baton, 1322 void *callback_baton, 1323 const char *relpath, 1324 apr_pool_t *pool); 1325 1326 /** Like #svn_delta_path_driver_cb_func2_t but without the @a editor and 1327 * @a edit_baton parameters. The user must arrange for the editor to be 1328 * passed through @a callback_baton (if required, which it usually is). 1329 * And @a path could possibly have a '/' prefix instead of being a relpath; 1330 * see the note on svn_delta_path_driver2(). 1331 * 1332 * @deprecated Provided for backward compatibility with the 1.11 API. 1333 */ 1334 typedef svn_error_t *(*svn_delta_path_driver_cb_func_t)( 1335 void **dir_baton, 1336 void *parent_baton, 1337 void *callback_baton, 1338 const char *path, 1339 apr_pool_t *pool); 1340 1341 1342 /** Drive @a editor (with its @a edit_baton) to visit each path in @a relpaths. 1343 * 1344 * As each path is hit as part of the editor drive, use 1345 * @a callback_func and @a callback_baton to allow the caller to handle 1346 * the portion of the editor drive related to that path. 1347 * 1348 * Each path in @a relpaths is a (const char *) relpath, relative 1349 * to the root path of the edit. The editor drive will be 1350 * performed in the same order as @a relpaths. The paths should be sorted 1351 * using something like svn_sort_compare_paths() to ensure that each 1352 * directory in the depth-first walk is visited only once. If @a sort_paths 1353 * is set, the function will sort the paths for you. Some callers may need 1354 * further customization of the order (ie. libsvn_delta/compat.c). 1355 * 1356 * If the first target path (after any requested sorting) is @c "" (the 1357 * root of the edit), the callback function will be responsible for 1358 * calling the editor's @c open_root method; otherwise, this function 1359 * will call @c open_root. 1360 * 1361 * Use @a scratch_pool for all necessary allocations. 1362 * 1363 * @since New in 1.12. 1364 */ 1365 svn_error_t * 1366 svn_delta_path_driver3(const svn_delta_editor_t *editor, 1367 void *edit_baton, 1368 const apr_array_header_t *relpaths, 1369 svn_boolean_t sort_paths, 1370 svn_delta_path_driver_cb_func2_t callback_func, 1371 void *callback_baton, 1372 apr_pool_t *pool); 1373 1374 /** Like svn_delta_path_driver3() but with a different callback function 1375 * signature. 1376 * 1377 * Optionally, paths in @a paths could have a '/' prefix instead of being 1378 * relpaths. If any of them do, then (since 1.12) ALL paths sent to the 1379 * callback will have a '/' prefix. 1380 * 1381 * @deprecated Provided for backward compatibility with the 1.11 API. 1382 * @since New in 1.8. Before 1.12, paths sent to the callback were the 1383 * exact paths passed in @a paths. 1384 */ 1385 SVN_DEPRECATED 1386 svn_error_t * 1387 svn_delta_path_driver2(const svn_delta_editor_t *editor, 1388 void *edit_baton, 1389 const apr_array_header_t *paths, 1390 svn_boolean_t sort_paths, 1391 svn_delta_path_driver_cb_func_t callback_func, 1392 void *callback_baton, 1393 apr_pool_t *scratch_pool); 1394 1395 1396 /** Similar to svn_delta_path_driver2, but takes an (unused) revision, 1397 * and will sort the provided @a paths using svn_sort_compare_paths. 1398 * 1399 * @note In versions prior to 1.8, this function would modify the order 1400 * of elements in @a paths, despite the 'const' marker on the parameter. 1401 * This has been fixed in 1.8. 1402 * 1403 * @deprecated Provided for backward compatibility with the 1.7 API. 1404 */ 1405 SVN_DEPRECATED 1406 svn_error_t * 1407 svn_delta_path_driver(const svn_delta_editor_t *editor, 1408 void *edit_baton, 1409 svn_revnum_t revision, 1410 const apr_array_header_t *paths, 1411 svn_delta_path_driver_cb_func_t callback_func, 1412 void *callback_baton, 1413 apr_pool_t *scratch_pool); 1414 1415 1416 /** A state object for the path driver that is obtained from 1417 * svn_delta_path_driver_start() and driven by 1418 * svn_delta_path_driver_step() and svn_delta_path_driver_finish(). 1419 * 1420 * @since New in 1.12. 1421 */ 1422 typedef struct svn_delta_path_driver_state_t svn_delta_path_driver_state_t; 1423 1424 /** Return a path driver object that can drive @a editor (with its 1425 * @a edit_baton) to visit a series of paths. 1426 * 1427 * As each path is hit as part of the editor drive, the path driver will 1428 * call @a callback_func and @a callback_baton to allow the caller to handle 1429 * the portion of the editor drive related to that path. 1430 * 1431 * This will not call the editor's open_root method; for that, see 1432 * svn_delta_path_driver_step(). 1433 * 1434 * @since New in 1.12. 1435 */ 1436 svn_error_t * 1437 svn_delta_path_driver_start(svn_delta_path_driver_state_t **state_p, 1438 const svn_delta_editor_t *editor, 1439 void *edit_baton, 1440 svn_delta_path_driver_cb_func2_t callback_func, 1441 void *callback_baton, 1442 apr_pool_t *result_pool); 1443 1444 /** Visit @a relpath. 1445 * 1446 * @a state is the object returned by svn_delta_path_driver_start(). 1447 * 1448 * @a relpath is a relpath relative to the root path of the edit. 1449 * 1450 * This function uses the editor and the callback that were originally 1451 * supplied to svn_delta_path_driver_start(). 1452 * 1453 * This drives the editor in a depth-first order, closing and then opening 1454 * directories if necessary to move from the last visited path to the new 1455 * path, as required by the editor driving rules. 1456 * 1457 * This then calls the callback to allow the caller to handle 1458 * the portion of the editor drive related to that path. 1459 * 1460 * If the first path to visit is @c "" (the root of the edit), the 1461 * callback function will be responsible for calling the editor's 1462 * @c open_root method; otherwise, this function will call @c open_root. 1463 * 1464 * The order of paths to visit should in general be sorted using something 1465 * like svn_sort_compare_paths() to ensure that each directory in the 1466 * depth-first walk is visited only once. Some editors may rely on such a 1467 * restriction. 1468 * 1469 * @since New in 1.12. 1470 */ 1471 svn_error_t * 1472 svn_delta_path_driver_step(svn_delta_path_driver_state_t *state, 1473 const char *relpath, 1474 apr_pool_t *scratch_pool); 1475 1476 /** Finish driving the editor. 1477 * 1478 * @a state is the object returned by svn_delta_path_driver_start(). 1479 * 1480 * This drives the editor to close any open directories and then calls 1481 * the editor's @c close_edit method. 1482 * 1483 * @since New in 1.12. 1484 */ 1485 svn_error_t * 1486 svn_delta_path_driver_finish(svn_delta_path_driver_state_t *state, 1487 apr_pool_t *scratch_pool); 1488 1489 /** @} */ 1490 1491 1492 /*** File revision iterator types ***/ 1493 1494 /** 1495 * The callback invoked by file rev loopers, such as 1496 * svn_ra_plugin_t.get_file_revs2() and svn_repos_get_file_revs2(). 1497 * 1498 * @a baton is provided by the caller, @a path is the pathname of the file 1499 * in revision @a rev and @a rev_props are the revision properties. 1500 * 1501 * If @a delta_handler and @a delta_baton are non-NULL, they may be set to a 1502 * handler/baton which will be called with the delta between the previous 1503 * revision and this one after the return of this callback. They may be 1504 * left as NULL/NULL. 1505 * 1506 * @a result_of_merge will be @c TRUE if the revision being returned was 1507 * included as the result of a merge. 1508 * 1509 * @a prop_diffs is an array of svn_prop_t elements indicating the property 1510 * delta for this and the previous revision. 1511 * 1512 * @a pool may be used for temporary allocations, but you can't rely 1513 * on objects allocated to live outside of this particular call and 1514 * the immediately following calls to @a *delta_handler if any. (Pass 1515 * in a pool via @a baton if need be.) 1516 * 1517 * @since New in 1.5. 1518 */ 1519 typedef svn_error_t *(*svn_file_rev_handler_t)( 1520 void *baton, 1521 const char *path, 1522 svn_revnum_t rev, 1523 apr_hash_t *rev_props, 1524 svn_boolean_t result_of_merge, 1525 svn_txdelta_window_handler_t *delta_handler, 1526 void **delta_baton, 1527 apr_array_header_t *prop_diffs, 1528 apr_pool_t *pool); 1529 1530 /** 1531 * The old file rev handler interface. 1532 * 1533 * @note #svn_file_rev_handler_old_t is a placeholder type for both 1534 * #svn_repos_file_rev_handler_t and #svn_ra_file_rev_handler_t. It is 1535 * reproduced here for dependency reasons. 1536 * 1537 * @deprecated This type is provided for the svn_compat_wrap_file_rev_handler() 1538 * compatibility wrapper, and should not be used for new development. 1539 * @since New in 1.5. 1540 */ 1541 typedef svn_error_t *(*svn_file_rev_handler_old_t)( 1542 void *baton, 1543 const char *path, 1544 svn_revnum_t rev, 1545 apr_hash_t *rev_props, 1546 svn_txdelta_window_handler_t *delta_handler, 1547 void **delta_baton, 1548 apr_array_header_t *prop_diffs, 1549 apr_pool_t *pool); 1550 1551 /** Return, in @a *handler2 and @a *handler2_baton a function/baton that 1552 * will call @a handler/@a handler_baton, allocating the @a *handler2_baton 1553 * in @a pool. 1554 * 1555 * @note This is used by compatibility wrappers, which exist in more than 1556 * Subversion core library. 1557 * 1558 * @note #svn_file_rev_handler_old_t is a placeholder type for both 1559 * #svn_repos_file_rev_handler_t and #svn_ra_file_rev_handler_t. It is 1560 * reproduced here for dependency reasons. 1561 * 1562 * @since New in 1.5. 1563 */ 1564 void 1565 svn_compat_wrap_file_rev_handler(svn_file_rev_handler_t *handler2, 1566 void **handler2_baton, 1567 svn_file_rev_handler_old_t handler, 1568 void *handler_baton, 1569 apr_pool_t *pool); 1570 1571 /** @} end group: delta_support */ 1572 1573 1574 #ifdef __cplusplus 1575 } 1576 #endif /* __cplusplus */ 1577 1578 #endif /* SVN_DELTA_H */ 1579