00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Licensed to the Apache Software Foundation (ASF) under one 00005 * or more contributor license agreements. See the NOTICE file 00006 * distributed with this work for additional information 00007 * regarding copyright ownership. The ASF licenses this file 00008 * to you under the Apache License, Version 2.0 (the 00009 * "License"); you may not use this file except in compliance 00010 * with the License. You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, 00015 * software distributed under the License is distributed on an 00016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00017 * KIND, either express or implied. See the License for the 00018 * specific language governing permissions and limitations 00019 * under the License. 00020 * ==================================================================== 00021 * @endcopyright 00022 * 00023 * @file svn_delta.h 00024 * @brief Delta-parsing 00025 */ 00026 00027 /* ==================================================================== */ 00028 00029 00030 00031 #ifndef SVN_DELTA_H 00032 #define SVN_DELTA_H 00033 00034 #include <apr.h> 00035 #include <apr_pools.h> 00036 #include <apr_hash.h> 00037 #include <apr_tables.h> 00038 #include <apr_file_io.h> /* for apr_file_t */ 00039 00040 #include "svn_types.h" 00041 #include "svn_string.h" 00042 #include "svn_io.h" 00043 #include "svn_checksum.h" 00044 00045 #ifdef __cplusplus 00046 extern "C" { 00047 #endif /* __cplusplus */ 00048 00049 00050 00051 /** This compression level effectively disables data compression. 00052 * However, the data pre-processing costs may still not be zero. 00053 * 00054 * @since New in 1.7. 00055 */ 00056 #define SVN_DELTA_COMPRESSION_LEVEL_NONE 0 00057 00058 /** This is the maximum compression level we can pass to zlib. 00059 * 00060 * @since New in 1.7. 00061 */ 00062 #define SVN_DELTA_COMPRESSION_LEVEL_MAX 9 00063 00064 /** This is the default compression level we pass to zlib. It 00065 * should be between 0 and 9, with higher numbers resulting in 00066 * better compression rates but slower operation. 00067 * 00068 * @since New in 1.7. 00069 */ 00070 #define SVN_DELTA_COMPRESSION_LEVEL_DEFAULT 5 00071 00072 /** 00073 * Get libsvn_delta version information. 00074 * 00075 * @since New in 1.1. 00076 */ 00077 const svn_version_t * 00078 svn_delta_version(void); 00079 00080 /** 00081 * @defgroup delta_support Delta generation and handling 00082 * 00083 * @{ 00084 */ 00085 00086 /** Text deltas. 00087 * 00088 * A text delta represents the difference between two strings of 00089 * bytes, the `source' string and the `target' string. Given a source 00090 * string and a target string, we can compute a text delta; given a 00091 * source string and a delta, we can reconstruct the target string. 00092 * However, note that deltas are not reversible: you cannot always 00093 * reconstruct the source string given the target string and delta. 00094 * 00095 * Since text deltas can be very large, the interface here allows us 00096 * to produce and consume them in pieces. Each piece, represented by 00097 * an #svn_txdelta_window_t structure, describes how to produce the 00098 * next section of the target string. 00099 * 00100 * To compute a new text delta: 00101 * 00102 * - We call svn_txdelta() on the streams we want to compare. That 00103 * returns us an #svn_txdelta_stream_t object. 00104 * 00105 * - We then call svn_txdelta_next_window() on the stream object 00106 * repeatedly. Each call returns a new #svn_txdelta_window_t 00107 * object, which describes the next portion of the target string. 00108 * When svn_txdelta_next_window() returns zero, we are done building 00109 * the target string. 00110 * 00111 * @defgroup svn_delta_txt_delta Text deltas 00112 * @{ 00113 */ 00114 00115 /** Action codes for text delta instructions. */ 00116 enum svn_delta_action { 00117 /* Note: The svndiff implementation relies on the values assigned in 00118 * this enumeration matching the instruction encoding values. */ 00119 00120 /** Append the @a length bytes at @a offset in the source view to the 00121 * target. 00122 * 00123 * It must be the case that 0 <= @a offset < @a offset + 00124 * @a length <= size of source view. 00125 */ 00126 svn_txdelta_source, 00127 00128 /** Append the @a length bytes at @a offset in the target view, to the 00129 * target. 00130 * 00131 * It must be the case that 0 <= @a offset < current position in the 00132 * target view. 00133 * 00134 * However! @a offset + @a length may be *beyond* the end of the existing 00135 * target data. "Where the heck does the text come from, then?" 00136 * If you start at @a offset, and append @a length bytes one at a time, 00137 * it'll work out --- you're adding new bytes to the end at the 00138 * same rate you're reading them from the middle. Thus, if your 00139 * current target text is "abcdefgh", and you get an #svn_txdelta_target 00140 * instruction whose @a offset is 6 and whose @a length is 7, 00141 * the resulting string is "abcdefghghghghg". This trick is actually 00142 * useful in encoding long runs of consecutive characters, long runs 00143 * of CR/LF pairs, etc. 00144 */ 00145 svn_txdelta_target, 00146 00147 /** Append the @a length bytes at @a offset in the window's @a new string 00148 * to the target. 00149 * 00150 * It must be the case that 0 <= @a offset < @a offset + 00151 * @a length <= length of @a new. Windows MUST use new data in ascending 00152 * order with no overlap at the moment; svn_txdelta_to_svndiff() 00153 * depends on this. 00154 */ 00155 svn_txdelta_new 00156 }; 00157 00158 /** A single text delta instruction. */ 00159 typedef struct svn_txdelta_op_t 00160 { 00161 /** Action code of delta instruction */ 00162 enum svn_delta_action action_code; 00163 /** Offset of delta, see #svn_delta_action for more details. */ 00164 apr_size_t offset; 00165 /** Number of bytes of delta, see #svn_delta_action for more details. */ 00166 apr_size_t length; 00167 } svn_txdelta_op_t; 00168 00169 00170 /** An #svn_txdelta_window_t object describes how to reconstruct a 00171 * contiguous section of the target string (the "target view") using a 00172 * specified contiguous region of the source string (the "source 00173 * view"). It contains a series of instructions which assemble the 00174 * new target string text by pulling together substrings from: 00175 * 00176 * - the source view, 00177 * 00178 * - the previously constructed portion of the target view, 00179 * 00180 * - a string of new data contained within the window structure 00181 * 00182 * The source view must always slide forward from one window to the 00183 * next; that is, neither the beginning nor the end of the source view 00184 * may move to the left as we read from a window stream. This 00185 * property allows us to apply deltas to non-seekable source streams 00186 * without making a full copy of the source stream. 00187 */ 00188 typedef struct svn_txdelta_window_t 00189 { 00190 00191 /** The offset of the source view for this window. */ 00192 svn_filesize_t sview_offset; 00193 00194 /** The length of the source view for this window. */ 00195 apr_size_t sview_len; 00196 00197 /** The length of the target view for this window, i.e. the number of 00198 * bytes which will be reconstructed by the instruction stream. */ 00199 apr_size_t tview_len; 00200 00201 /** The number of instructions in this window. */ 00202 int num_ops; 00203 00204 /** The number of svn_txdelta_source instructions in this window. If 00205 * this number is 0, we don't need to read the source in order to 00206 * reconstruct the target view. 00207 */ 00208 int src_ops; 00209 00210 /** The instructions for this window. */ 00211 const svn_txdelta_op_t *ops; 00212 00213 /** New data, for use by any `svn_txdelta_new' instructions. */ 00214 const svn_string_t *new_data; 00215 00216 } svn_txdelta_window_t; 00217 00218 /** 00219 * Return a deep copy of @a window, allocated in @a pool. 00220 * 00221 * @since New in 1.3. 00222 */ 00223 svn_txdelta_window_t * 00224 svn_txdelta_window_dup(const svn_txdelta_window_t *window, 00225 apr_pool_t *pool); 00226 00227 /** 00228 * Compose two delta windows, yielding a third, allocated in @a pool. 00229 * 00230 * @since New in 1.4 00231 * 00232 */ 00233 svn_txdelta_window_t * 00234 svn_txdelta_compose_windows(const svn_txdelta_window_t *window_A, 00235 const svn_txdelta_window_t *window_B, 00236 apr_pool_t *pool); 00237 00238 /** 00239 * Apply the instructions from @a window to a source view @a sbuf to 00240 * produce a target view @a tbuf. 00241 * 00242 * @a sbuf is assumed to have @a window->sview_len bytes of data and 00243 * @a tbuf is assumed to have room for @a tlen bytes of output. @a 00244 * tlen may be more than @a window->tview_len, so return the actual 00245 * number of bytes written. @a sbuf is not touched and may be NULL if 00246 * @a window contains no source-copy operations. This is purely a 00247 * memory operation; nothing can go wrong as long as we have a valid 00248 * window. 00249 * 00250 * @since New in 1.4 00251 * 00252 */ 00253 void 00254 svn_txdelta_apply_instructions(svn_txdelta_window_t *window, 00255 const char *sbuf, char *tbuf, 00256 apr_size_t *tlen); 00257 00258 /** A typedef for functions that consume a series of delta windows, for 00259 * use in caller-pushes interfaces. Such functions will typically 00260 * apply the delta windows to produce some file, or save the windows 00261 * somewhere. At the end of the delta window stream, you must call 00262 * this function passing zero for the @a window argument. 00263 */ 00264 typedef svn_error_t *(*svn_txdelta_window_handler_t)( 00265 svn_txdelta_window_t *window, void *baton); 00266 00267 00268 /** This function will generate delta windows that turn @a source into 00269 * @a target, and pushing these windows into the @a handler window handler 00270 * callback (passing @a handler_baton to each invocation). 00271 * 00272 * If @a checksum is not NULL, then a checksum (of kind @a checksum_kind) 00273 * will be computed for the target stream, and placed into *checksum. 00274 * 00275 * If @a cancel_func is not NULL, then it should refer to a cancellation 00276 * function (along with @a cancel_baton). 00277 * 00278 * Results (the checksum) will be allocated from @a result_pool, and all 00279 * temporary allocations will be performed in @a scratch_pool. 00280 * 00281 * Note: this function replaces the combination of svn_txdelta() and 00282 * svn_txdelta_send_txstream(). 00283 * 00284 * @since New in 1.6. 00285 */ 00286 svn_error_t * 00287 svn_txdelta_run(svn_stream_t *source, 00288 svn_stream_t *target, 00289 svn_txdelta_window_handler_t handler, 00290 void *handler_baton, 00291 svn_checksum_kind_t checksum_kind, 00292 svn_checksum_t **checksum, 00293 svn_cancel_func_t cancel_func, 00294 void *cancel_baton, 00295 apr_pool_t *result_pool, 00296 apr_pool_t *scratch_pool); 00297 00298 00299 /** A delta stream --- this is the hat from which we pull a series of 00300 * svn_txdelta_window_t objects, which, taken in order, describe the 00301 * entire target string. This type is defined within libsvn_delta, and 00302 * opaque outside that library. 00303 */ 00304 typedef struct svn_txdelta_stream_t svn_txdelta_stream_t; 00305 00306 00307 /** A typedef for a function that will set @a *window to the next 00308 * window from a #svn_txdelta_stream_t object. If there are no more 00309 * delta windows, NULL will be used. The returned window, if any, 00310 * will be allocated in @a pool. @a baton is the baton specified 00311 * when the stream was created. 00312 * 00313 * @since New in 1.4. 00314 */ 00315 typedef svn_error_t * 00316 (*svn_txdelta_next_window_fn_t)(svn_txdelta_window_t **window, 00317 void *baton, 00318 apr_pool_t *pool); 00319 00320 /** A typedef for a function that will return the md5 checksum of the 00321 * fulltext deltified by a #svn_txdelta_stream_t object. Will 00322 * return NULL if the final null window hasn't yet been returned by 00323 * the stream. The returned value will be allocated in the same pool 00324 * as the stream. @a baton is the baton specified when the stream was 00325 * created. 00326 * 00327 * @since New in 1.4. 00328 */ 00329 typedef const unsigned char * 00330 (*svn_txdelta_md5_digest_fn_t)(void *baton); 00331 00332 /** Create and return a generic text delta stream with @a baton, @a 00333 * next_window and @a md5_digest. Allocate the new stream in @a 00334 * pool. 00335 * 00336 * @since New in 1.4. 00337 */ 00338 svn_txdelta_stream_t * 00339 svn_txdelta_stream_create(void *baton, 00340 svn_txdelta_next_window_fn_t next_window, 00341 svn_txdelta_md5_digest_fn_t md5_digest, 00342 apr_pool_t *pool); 00343 00344 /** Set @a *window to a pointer to the next window from the delta stream 00345 * @a stream. When we have completely reconstructed the target string, 00346 * set @a *window to zero. 00347 * 00348 * The window will be allocated in @a pool. 00349 */ 00350 svn_error_t * 00351 svn_txdelta_next_window(svn_txdelta_window_t **window, 00352 svn_txdelta_stream_t *stream, 00353 apr_pool_t *pool); 00354 00355 00356 /** Return the md5 digest for the complete fulltext deltified by 00357 * @a stream, or @c NULL if @a stream has not yet returned its final 00358 * @c NULL window. The digest is allocated in the same memory as @a 00359 * STREAM. 00360 */ 00361 const unsigned char * 00362 svn_txdelta_md5_digest(svn_txdelta_stream_t *stream); 00363 00364 /** Set @a *stream to a pointer to a delta stream that will turn the byte 00365 * string from @a source into the byte stream from @a target. 00366 * 00367 * @a source and @a target are both readable generic streams. When we call 00368 * svn_txdelta_next_window() on @a *stream, it will read from @a source and 00369 * @a target to gather as much data as it needs. If @a calculate_checksum 00370 * is set, you may call svn_txdelta_md5_digest() to get an MD5 checksum 00371 * for @a target. 00372 * 00373 * Do any necessary allocation in a sub-pool of @a pool. 00374 * 00375 * @since New in 1.8. 00376 */ 00377 void 00378 svn_txdelta2(svn_txdelta_stream_t **stream, 00379 svn_stream_t *source, 00380 svn_stream_t *target, 00381 svn_boolean_t calculate_checksum, 00382 apr_pool_t *pool); 00383 00384 /** Similar to svn_txdelta2 but always calculating the target checksum. 00385 * 00386 * @deprecated Provided for backward compatibility with the 1.7 API. 00387 */ 00388 SVN_DEPRECATED 00389 void 00390 svn_txdelta(svn_txdelta_stream_t **stream, 00391 svn_stream_t *source, 00392 svn_stream_t *target, 00393 apr_pool_t *pool); 00394 00395 00396 /** 00397 * Return a writable stream which, when fed target data, will send 00398 * delta windows to @a handler/@a handler_baton which transform the 00399 * data in @a source to the target data. As usual, the window handler 00400 * will receive a NULL window to signify the end of the window stream. 00401 * The stream handler functions will read data from @a source as 00402 * necessary. 00403 * 00404 * @since New in 1.1. 00405 */ 00406 svn_stream_t * 00407 svn_txdelta_target_push(svn_txdelta_window_handler_t handler, 00408 void *handler_baton, 00409 svn_stream_t *source, 00410 apr_pool_t *pool); 00411 00412 00413 /** Send the contents of @a string to window-handler @a handler/@a baton. 00414 * This is effectively a 'copy' operation, resulting in delta windows that 00415 * make the target equivalent to the value of @a string. 00416 * 00417 * All temporary allocation is performed in @a pool. 00418 */ 00419 svn_error_t * 00420 svn_txdelta_send_string(const svn_string_t *string, 00421 svn_txdelta_window_handler_t handler, 00422 void *handler_baton, 00423 apr_pool_t *pool); 00424 00425 /** Send the contents of @a stream to window-handler @a handler/@a baton. 00426 * This is effectively a 'copy' operation, resulting in delta windows that 00427 * make the target equivalent to the stream. 00428 * 00429 * If @a digest is non-NULL, populate it with the md5 checksum for the 00430 * fulltext that was deltified (@a digest must be at least 00431 * @c APR_MD5_DIGESTSIZE bytes long). 00432 * 00433 * All temporary allocation is performed in @a pool. 00434 */ 00435 svn_error_t * 00436 svn_txdelta_send_stream(svn_stream_t *stream, 00437 svn_txdelta_window_handler_t handler, 00438 void *handler_baton, 00439 unsigned char *digest, 00440 apr_pool_t *pool); 00441 00442 /** Send the contents of @a txstream to window-handler @a handler/@a baton. 00443 * Windows will be extracted from the stream and delivered to the handler. 00444 * 00445 * All temporary allocation is performed in @a pool. 00446 */ 00447 svn_error_t * 00448 svn_txdelta_send_txstream(svn_txdelta_stream_t *txstream, 00449 svn_txdelta_window_handler_t handler, 00450 void *handler_baton, 00451 apr_pool_t *pool); 00452 00453 00454 /** Send the @a contents of length @a len as a txdelta against an empty 00455 * source directly to window-handler @a handler/@a handler_baton. 00456 * 00457 * All temporary allocation is performed in @a pool. 00458 * 00459 * @since New in 1.8. 00460 */ 00461 svn_error_t * 00462 svn_txdelta_send_contents(const unsigned char *contents, 00463 apr_size_t len, 00464 svn_txdelta_window_handler_t handler, 00465 void *handler_baton, 00466 apr_pool_t *pool); 00467 00468 /** Prepare to apply a text delta. @a source is a readable generic stream 00469 * yielding the source data, @a target is a writable generic stream to 00470 * write target data to, and allocation takes place in a sub-pool of 00471 * @a pool. On return, @a *handler is set to a window handler function and 00472 * @a *handler_baton is set to the value to pass as the @a baton argument to 00473 * @a *handler. 00474 * 00475 * If @a result_digest is non-NULL, it points to APR_MD5_DIGESTSIZE bytes 00476 * of storage, and the final call to @a handler populates it with the 00477 * MD5 digest of the resulting fulltext. 00478 * 00479 * If @a error_info is non-NULL, it is inserted parenthetically into 00480 * the error string for any error returned by svn_txdelta_apply() or 00481 * @a *handler. (It is normally used to provide path information, 00482 * since there's nothing else in the delta application's context to 00483 * supply a path for error messages.) 00484 * 00485 * @note To avoid lifetime issues, @a error_info is copied into 00486 * @a pool or a subpool thereof. 00487 */ 00488 void 00489 svn_txdelta_apply(svn_stream_t *source, 00490 svn_stream_t *target, 00491 unsigned char *result_digest, 00492 const char *error_info, 00493 apr_pool_t *pool, 00494 svn_txdelta_window_handler_t *handler, 00495 void **handler_baton); 00496 00497 00498 00499 00500 /*** Producing and consuming svndiff-format text deltas. ***/ 00501 00502 /** Prepare to produce an svndiff-format diff from text delta windows. 00503 * @a output is a writable generic stream to write the svndiff data to. 00504 * Allocation takes place in a sub-pool of @a pool. On return, @a *handler 00505 * is set to a window handler function and @a *handler_baton is set to 00506 * the value to pass as the @a baton argument to @a *handler. The svndiff 00507 * version is @a svndiff_version. @a compression_level is the zlib 00508 * compression level from 0 (no compression) and 9 (maximum compression). 00509 * 00510 * @since New in 1.7. 00511 */ 00512 void 00513 svn_txdelta_to_svndiff3(svn_txdelta_window_handler_t *handler, 00514 void **handler_baton, 00515 svn_stream_t *output, 00516 int svndiff_version, 00517 int compression_level, 00518 apr_pool_t *pool); 00519 00520 /** Similar to svn_txdelta_to_svndiff3(), but always using the SVN default 00521 * compression level (#SVN_DELTA_COMPRESSION_LEVEL_DEFAULT). 00522 * 00523 * @since New in 1.4. 00524 * @deprecated Provided for backward compatibility with the 1.6 API. 00525 */ 00526 SVN_DEPRECATED 00527 void 00528 svn_txdelta_to_svndiff2(svn_txdelta_window_handler_t *handler, 00529 void **handler_baton, 00530 svn_stream_t *output, 00531 int svndiff_version, 00532 apr_pool_t *pool); 00533 00534 /** Similar to svn_txdelta_to_svndiff2, but always using svndiff 00535 * version 0. 00536 * 00537 * @deprecated Provided for backward compatibility with the 1.3 API. 00538 */ 00539 SVN_DEPRECATED 00540 void 00541 svn_txdelta_to_svndiff(svn_stream_t *output, 00542 apr_pool_t *pool, 00543 svn_txdelta_window_handler_t *handler, 00544 void **handler_baton); 00545 00546 /** Return a writable generic stream which will parse svndiff-format 00547 * data into a text delta, invoking @a handler with @a handler_baton 00548 * whenever a new window is ready. If @a error_on_early_close is @c 00549 * TRUE, attempting to close this stream before it has handled the entire 00550 * svndiff data set will result in #SVN_ERR_SVNDIFF_UNEXPECTED_END, 00551 * else this error condition will be ignored. 00552 */ 00553 svn_stream_t * 00554 svn_txdelta_parse_svndiff(svn_txdelta_window_handler_t handler, 00555 void *handler_baton, 00556 svn_boolean_t error_on_early_close, 00557 apr_pool_t *pool); 00558 00559 /** 00560 * Read and parse one delta window in svndiff format from the 00561 * readable stream @a stream and place it in @a *window, allocating 00562 * the result in @a pool. The caller must take responsibility for 00563 * stripping off the four-byte 'SVN@<ver@>' header at the beginning of 00564 * the svndiff document before reading the first window, and must 00565 * provide the version number (the value of the fourth byte) to each 00566 * invocation of this routine with the @a svndiff_version argument. 00567 * 00568 * @since New in 1.1. 00569 */ 00570 svn_error_t * 00571 svn_txdelta_read_svndiff_window(svn_txdelta_window_t **window, 00572 svn_stream_t *stream, 00573 int svndiff_version, 00574 apr_pool_t *pool); 00575 00576 /** 00577 * Read and skip one delta window in svndiff format from the 00578 * file @a file. @a pool is used for temporary allocations. The 00579 * caller must take responsibility for stripping off the four-byte 00580 * 'SVN@<ver@>' header at the beginning of the svndiff document before 00581 * reading or skipping the first window, and must provide the version 00582 * number (the value of the fourth byte) to each invocation of this 00583 * routine with the @a svndiff_version argument. 00584 * 00585 * @since New in 1.1. 00586 */ 00587 svn_error_t * 00588 svn_txdelta_skip_svndiff_window(apr_file_t *file, 00589 int svndiff_version, 00590 apr_pool_t *pool); 00591 00592 /** @} */ 00593 00594 00595 /** Traversing tree deltas. 00596 * 00597 * In Subversion, we've got various producers and consumers of tree 00598 * deltas. 00599 * 00600 * In processing a `commit' command: 00601 * - The client examines its working copy data, and produces a tree 00602 * delta describing the changes to be committed. 00603 * - The client networking library consumes that delta, and sends them 00604 * across the wire as an equivalent series of network requests (for 00605 * example, to svnserve as an ra_svn protocol stream, or to an 00606 * Apache httpd server as WebDAV commands) 00607 * - The server receives those requests and produces a tree delta --- 00608 * hopefully equivalent to the one the client produced above. 00609 * - The Subversion server module consumes that delta and commits an 00610 * appropriate transaction to the filesystem. 00611 * 00612 * In processing an `update' command, the process is reversed: 00613 * - The Subversion server module talks to the filesystem and produces 00614 * a tree delta describing the changes necessary to bring the 00615 * client's working copy up to date. 00616 * - The server consumes this delta, and assembles a reply 00617 * representing the appropriate changes. 00618 * - The client networking library receives that reply, and produces a 00619 * tree delta --- hopefully equivalent to the one the Subversion 00620 * server produced above. 00621 * - The working copy library consumes that delta, and makes the 00622 * appropriate changes to the working copy. 00623 * 00624 * The simplest approach would be to represent tree deltas using the 00625 * obvious data structure. To do an update, the server would 00626 * construct a delta structure, and the working copy library would 00627 * apply that structure to the working copy; the network layer's job 00628 * would simply be to get the structure across the net intact. 00629 * 00630 * However, we expect that these deltas will occasionally be too large 00631 * to fit in a typical workstation's swap area. For example, in 00632 * checking out a 200Mb source tree, the entire source tree is 00633 * represented by a single tree delta. So it's important to handle 00634 * deltas that are too large to fit in swap all at once. 00635 * 00636 * So instead of representing the tree delta explicitly, we define a 00637 * standard way for a consumer to process each piece of a tree delta 00638 * as soon as the producer creates it. The #svn_delta_editor_t 00639 * structure is a set of callback functions to be defined by a delta 00640 * consumer, and invoked by a delta producer. Each invocation of a 00641 * callback function describes a piece of the delta --- a file's 00642 * contents changing, something being renamed, etc. 00643 * 00644 * @defgroup svn_delta_tree_deltas Tree deltas 00645 * @{ 00646 */ 00647 00648 /** A structure full of callback functions the delta source will invoke 00649 * as it produces the delta. 00650 * 00651 * @note Don't try to allocate one of these yourself. Instead, always 00652 * use svn_delta_default_editor() or some other constructor, to ensure 00653 * that unused slots are filled in with no-op functions. 00654 * 00655 * <h3>Function Usage</h3> 00656 * 00657 * Here's how to use these functions to express a tree delta. 00658 * 00659 * The delta consumer implements the callback functions described in 00660 * this structure, and the delta producer invokes them. So the 00661 * caller (producer) is pushing tree delta data at the callee 00662 * (consumer). 00663 * 00664 * At the start of traversal, the consumer provides @a edit_baton, a 00665 * baton global to the entire delta edit. If there is a target 00666 * revision that needs to be set for this operation, the producer 00667 * should call the @c set_target_revision function at this point. 00668 * 00669 * Next, if there are any tree deltas to express, the producer should 00670 * pass the @a edit_baton to the @c open_root function, to get a baton 00671 * representing root of the tree being edited. 00672 * 00673 * Most of the callbacks work in the obvious way: 00674 * 00675 * @c delete_entry 00676 * @c add_file 00677 * @c add_directory 00678 * @c open_file 00679 * @c open_directory 00680 * 00681 * Each of these takes a directory baton, indicating the directory 00682 * in which the change takes place, and a @a path argument, giving the 00683 * path of the file, subdirectory, or directory entry to change. 00684 * 00685 * The @a path argument to each of the callbacks is relative to the 00686 * root of the edit. Editors will usually want to join this relative 00687 * path with some base stored in the edit baton (e.g. a URL, or a 00688 * location in the OS filesystem). 00689 * 00690 * Since every call requires a parent directory baton, including 00691 * @c add_directory and @c open_directory, where do we ever get our 00692 * initial directory baton, to get things started? The @c open_root 00693 * function returns a baton for the top directory of the change. In 00694 * general, the producer needs to invoke the editor's @c open_root 00695 * function before it can get anything of interest done. 00696 * 00697 * While @c open_root provides a directory baton for the root of 00698 * the tree being changed, the @c add_directory and @c open_directory 00699 * callbacks provide batons for other directories. Like the 00700 * callbacks above, they take a @a parent_baton and a relative path 00701 * @a path, and then return a new baton for the subdirectory being 00702 * created / modified --- @a child_baton. The producer can then use 00703 * @a child_baton to make further changes in that subdirectory. 00704 * 00705 * So, if we already have subdirectories named `foo' and `foo/bar', 00706 * then the producer can create a new file named `foo/bar/baz.c' by 00707 * calling: 00708 * 00709 * - @c open_root () --- yielding a baton @a root for the top directory 00710 * 00711 * - @c open_directory (@a root, "foo") --- yielding a baton @a f for `foo' 00712 * 00713 * - @c open_directory (@a f, "foo/bar") --- yielding a baton @a b for 00714 * `foo/bar' 00715 * 00716 * - @c add_file (@a b, "foo/bar/baz.c") 00717 * 00718 * When the producer is finished making changes to a directory, it 00719 * should call @c close_directory. This lets the consumer do any 00720 * necessary cleanup, and free the baton's storage. 00721 * 00722 * The @c add_file and @c open_file callbacks each return a baton 00723 * for the file being created or changed. This baton can then be 00724 * passed to @c apply_textdelta to change the file's contents, or 00725 * @c change_file_prop to change the file's properties. When the 00726 * producer is finished making changes to a file, it should call 00727 * @c close_file, to let the consumer clean up and free the baton. 00728 * 00729 * The @c add_file and @c add_directory functions each take arguments 00730 * @a copyfrom_path and @a copyfrom_revision. If @a copyfrom_path is 00731 * non-@c NULL, then @a copyfrom_path and @a copyfrom_revision indicate where 00732 * the file or directory should be copied from (to create the file 00733 * or directory being added). In that case, @a copyfrom_path must be 00734 * either a path relative to the root of the edit, or a URI from the 00735 * repository being edited. If @a copyfrom_path is @c NULL, then @a 00736 * copyfrom_revision must be #SVN_INVALID_REVNUM; it is invalid to 00737 * pass a mix of valid and invalid copyfrom arguments. 00738 * 00739 * 00740 * <h3>Function Call Ordering</h3> 00741 * 00742 * There are six restrictions on the order in which the producer 00743 * may use the batons: 00744 * 00745 * 1. The producer may call @c open_directory, @c add_directory, 00746 * @c open_file, @c add_file at most once on any given directory 00747 * entry. @c delete_entry may be called at most once on any given 00748 * directory entry and may later be followed by @c add_directory or 00749 * @c add_file on the same directory entry. @c delete_entry may 00750 * not be called on any directory entry after @c open_directory, 00751 * @c add_directory, @c open_file or @c add_file has been called on 00752 * that directory entry. 00753 * 00754 * 2. The producer may not close a directory baton until it has 00755 * closed all batons for its subdirectories. 00756 * 00757 * 3. When a producer calls @c open_directory or @c add_directory, 00758 * it must specify the most recently opened of the currently open 00759 * directory batons. Put another way, the producer cannot have 00760 * two sibling directory batons open at the same time. 00761 * 00762 * 4. A producer must call @c change_dir_prop on a directory either 00763 * before opening any of the directory's subdirs or after closing 00764 * them, but not in the middle. 00765 * 00766 * 5. When the producer calls @c open_file or @c add_file, either: 00767 * 00768 * (a) The producer must follow with any changes to the file 00769 * (@c change_file_prop and/or @c apply_textdelta, as applicable), 00770 * followed by a @c close_file call, before issuing any other file 00771 * or directory calls, or 00772 * 00773 * (b) The producer must follow with a @c change_file_prop call if 00774 * it is applicable, before issuing any other file or directory 00775 * calls; later, after all directory batons including the root 00776 * have been closed, the producer must issue @c apply_textdelta 00777 * and @c close_file calls. 00778 * 00779 * 6. When the producer calls @c apply_textdelta, it must make all of 00780 * the window handler calls (including the @c NULL window at the 00781 * end) before issuing any other #svn_delta_editor_t calls. 00782 * 00783 * So, the producer needs to use directory and file batons as if it 00784 * is doing a single depth-first traversal of the tree, with the 00785 * exception that the producer may keep file batons open in order to 00786 * make @c apply_textdelta calls at the end. 00787 * 00788 * 00789 * <h3>Pool Usage</h3> 00790 * 00791 * Many editor functions are invoked multiple times, in a sequence 00792 * determined by the editor "driver". The driver is responsible for 00793 * creating a pool for use on each iteration of the editor function, 00794 * and clearing that pool between each iteration. The driver passes 00795 * the appropriate pool on each function invocation. 00796 * 00797 * Based on the requirement of calling the editor functions in a 00798 * depth-first style, it is usually customary for the driver to similarly 00799 * nest the pools. However, this is only a safety feature to ensure 00800 * that pools associated with deeper items are always cleared when the 00801 * top-level items are also cleared. The interface does not assume, nor 00802 * require, any particular organization of the pools passed to these 00803 * functions. In fact, if "postfix deltas" are used for files, the file 00804 * pools definitely need to live outside the scope of their parent 00805 * directories' pools. 00806 * 00807 * Note that close_directory can be called *before* a file in that 00808 * directory has been closed. That is, the directory's baton is 00809 * closed before the file's baton. The implication is that 00810 * @c apply_textdelta and @c close_file should not refer to a parent 00811 * directory baton UNLESS the editor has taken precautions to 00812 * allocate it in a pool of the appropriate lifetime (the @a dir_pool 00813 * passed to @c open_directory and @c add_directory definitely does not 00814 * have the proper lifetime). In general, it is recommended to simply 00815 * avoid keeping a parent directory baton in a file baton. 00816 * 00817 * 00818 * <h3>Errors</h3> 00819 * 00820 * At least one implementation of the editor interface is 00821 * asynchronous; an error from one operation may be detected some 00822 * number of operations later. As a result, an editor driver must not 00823 * assume that an error from an editing function resulted from the 00824 * particular operation being detected. Moreover, once an editing 00825 * function (including @c close_edit) returns an error, the edit is 00826 * dead; the only further operation which may be called on the editor 00827 * is @c abort_edit. 00828 */ 00829 typedef struct svn_delta_editor_t 00830 { 00831 /** Set the target revision for this edit to @a target_revision. This 00832 * call, if used, should precede all other editor calls. 00833 * 00834 * @note This is typically used only for server->client update-type 00835 * operations. It doesn't really make much sense for commit-type 00836 * operations, because the revision of a commit isn't known until 00837 * the commit is finalized. 00838 * 00839 * Any temporary allocations may be performed in @a scratch_pool. 00840 */ 00841 svn_error_t *(*set_target_revision)(void *edit_baton, 00842 svn_revnum_t target_revision, 00843 apr_pool_t *scratch_pool); 00844 00845 /** Set @a *root_baton to a baton for the top directory of the change. 00846 * (This is the top of the subtree being changed, not necessarily 00847 * the root of the filesystem.) As with any other directory baton, the 00848 * producer should call @c close_directory on @a root_baton when done. 00849 * And as with other @c open_* calls, the @a base_revision here is the 00850 * current revision of the directory (before getting bumped up to the 00851 * new target revision set with @c set_target_revision). 00852 * 00853 * Allocations for the returned @a root_baton should be performed in 00854 * @a result_pool. It is also typical to (possibly) save this pool for 00855 * later usage by @c close_directory. 00856 */ 00857 svn_error_t *(*open_root)(void *edit_baton, 00858 svn_revnum_t base_revision, 00859 apr_pool_t *result_pool, 00860 void **root_baton); 00861 00862 00863 /** Remove the directory entry at @a path, a child of the directory 00864 * represented by @a parent_baton. If @a revision is a valid 00865 * revision number, it is used as a sanity check to ensure that you 00866 * are really removing the revision of @a path that you think you are. 00867 * 00868 * Any temporary allocations may be performed in @a scratch_pool. 00869 * 00870 * @note The @a revision parameter is typically used only for 00871 * client->server commit-type operations, allowing the server to 00872 * verify that it is deleting what the client thinks it should be 00873 * deleting. It only really makes sense in the opposite direction 00874 * (during server->client update-type operations) when the trees 00875 * whose delta is being described are ancestrally related (that is, 00876 * one tree is an ancestor of the other). 00877 */ 00878 svn_error_t *(*delete_entry)(const char *path, 00879 svn_revnum_t revision, 00880 void *parent_baton, 00881 apr_pool_t *scratch_pool); 00882 00883 00884 /** We are going to add a new subdirectory at @a path, a child of 00885 * the directory represented by @a parent_baton. We will use 00886 * the value this callback stores in @a *child_baton as the 00887 * parent baton for further changes in the new subdirectory. 00888 * 00889 * If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a 00890 * copy), and the origin of the copy may be recorded as 00891 * @a copyfrom_path under @a copyfrom_revision. 00892 * 00893 * Allocations for the returned @a child_baton should be performed in 00894 * @a result_pool. It is also typical to (possibly) save this pool for 00895 * later usage by @c close_directory. 00896 */ 00897 svn_error_t *(*add_directory)(const char *path, 00898 void *parent_baton, 00899 const char *copyfrom_path, 00900 svn_revnum_t copyfrom_revision, 00901 apr_pool_t *result_pool, 00902 void **child_baton); 00903 00904 /** We are going to make changes in the subdirectory at @a path, a 00905 * child of the directory represented by @a parent_baton. 00906 * The callback must store a value in @a *child_baton that 00907 * should be used as the parent baton for subsequent changes in this 00908 * subdirectory. If a valid revnum, @a base_revision is the current 00909 * revision of the subdirectory. 00910 * 00911 * Allocations for the returned @a child_baton should be performed in 00912 * @a result_pool. It is also typical to (possibly) save this pool for 00913 * later usage by @c close_directory. 00914 */ 00915 svn_error_t *(*open_directory)(const char *path, 00916 void *parent_baton, 00917 svn_revnum_t base_revision, 00918 apr_pool_t *result_pool, 00919 void **child_baton); 00920 00921 /** Change the value of a directory's property. 00922 * - @a dir_baton specifies the directory whose property should change. 00923 * - @a name is the name of the property to change. 00924 * - @a value is the new (final) value of the property, or @c NULL if the 00925 * property should be removed altogether. 00926 * 00927 * The callback is guaranteed to be called exactly once for each property 00928 * whose value differs between the start and the end of the edit. 00929 * 00930 * Any temporary allocations may be performed in @a scratch_pool. 00931 */ 00932 svn_error_t *(*change_dir_prop)(void *dir_baton, 00933 const char *name, 00934 const svn_string_t *value, 00935 apr_pool_t *scratch_pool); 00936 00937 /** We are done processing a subdirectory, whose baton is @a dir_baton 00938 * (set by @c add_directory or @c open_directory). We won't be using 00939 * the baton any more, so whatever resources it refers to may now be 00940 * freed. 00941 * 00942 * Any temporary allocations may be performed in @a scratch_pool. 00943 */ 00944 svn_error_t *(*close_directory)(void *dir_baton, 00945 apr_pool_t *scratch_pool); 00946 00947 00948 /** In the directory represented by @a parent_baton, indicate that 00949 * @a path is present as a subdirectory in the edit source, but 00950 * cannot be conveyed to the edit consumer. Currently, this would 00951 * only occur because of authorization restrictions, but may change 00952 * in the future. 00953 * 00954 * Any temporary allocations may be performed in @a scratch_pool. 00955 */ 00956 svn_error_t *(*absent_directory)(const char *path, 00957 void *parent_baton, 00958 apr_pool_t *scratch_pool); 00959 00960 /** We are going to add a new file at @a path, a child of the 00961 * directory represented by @a parent_baton. The callback can 00962 * store a baton for this new file in @a **file_baton; whatever value 00963 * it stores there should be passed through to @c apply_textdelta. 00964 * 00965 * If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a 00966 * copy), and the origin of the copy may be recorded as 00967 * @a copyfrom_path under @a copyfrom_revision. 00968 * 00969 * Allocations for the returned @a file_baton should be performed in 00970 * @a result_pool. It is also typical to save this pool for later usage 00971 * by @c apply_textdelta and possibly @c close_file. 00972 * 00973 * @note Because the editor driver could be employing the "postfix 00974 * deltas" paradigm, @a result_pool could potentially be relatively 00975 * long-lived. Every file baton created by the editor for a given 00976 * editor drive might be resident in memory similtaneously. Editor 00977 * implementations should ideally keep their file batons as 00978 * conservative (memory-usage-wise) as possible, and use @a result_pool 00979 * only for those batons. (Consider using a subpool of @a result_pool 00980 * for scratch work, destroying the subpool before exiting this 00981 * function's implementation.) 00982 */ 00983 svn_error_t *(*add_file)(const char *path, 00984 void *parent_baton, 00985 const char *copyfrom_path, 00986 svn_revnum_t copyfrom_revision, 00987 apr_pool_t *result_pool, 00988 void **file_baton); 00989 00990 /** We are going to make changes to a file at @a path, a child of the 00991 * directory represented by @a parent_baton. 00992 * 00993 * The callback can store a baton for this new file in @a **file_baton; 00994 * whatever value it stores there should be passed through to 00995 * @c apply_textdelta. If a valid revnum, @a base_revision is the 00996 * current revision of the file. 00997 * 00998 * Allocations for the returned @a file_baton should be performed in 00999 * @a result_pool. It is also typical to save this pool for later usage 01000 * by @c apply_textdelta and possibly @c close_file. 01001 * 01002 * @note See note about memory usage on @a add_file, which also 01003 * applies here. 01004 */ 01005 svn_error_t *(*open_file)(const char *path, 01006 void *parent_baton, 01007 svn_revnum_t base_revision, 01008 apr_pool_t *result_pool, 01009 void **file_baton); 01010 01011 /** Apply a text delta, yielding the new revision of a file. 01012 * 01013 * @a file_baton indicates the file we're creating or updating, and the 01014 * ancestor file on which it is based; it is the baton set by some 01015 * prior @c add_file or @c open_file callback. 01016 * 01017 * The callback should set @a *handler to a text delta window 01018 * handler; we will then call @a *handler on successive text 01019 * delta windows as we receive them. The callback should set 01020 * @a *handler_baton to the value we should pass as the @a baton 01021 * argument to @a *handler. These values should be allocated within 01022 * @a result_pool. 01023 * 01024 * @a base_checksum is the hex MD5 digest for the base text against 01025 * which the delta is being applied; it is ignored if NULL, and may 01026 * be ignored even if not NULL. If it is not ignored, it must match 01027 * the checksum of the base text against which svndiff data is being 01028 * applied; if it does not, @c apply_textdelta or the @a *handler call 01029 * which detects the mismatch will return the error 01030 * SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may 01031 * still be an error if @a base_checksum is neither NULL nor the hex 01032 * MD5 checksum of the empty string). 01033 */ 01034 svn_error_t *(*apply_textdelta)(void *file_baton, 01035 const char *base_checksum, 01036 apr_pool_t *result_pool, 01037 svn_txdelta_window_handler_t *handler, 01038 void **handler_baton); 01039 01040 /** Change the value of a file's property. 01041 * - @a file_baton specifies the file whose property should change. 01042 * - @a name is the name of the property to change. 01043 * - @a value is the new (final) value of the property, or @c NULL if the 01044 * property should be removed altogether. 01045 * 01046 * The callback is guaranteed to be called exactly once for each property 01047 * whose value differs between the start and the end of the edit. 01048 * 01049 * Any temporary allocations may be performed in @a scratch_pool. 01050 */ 01051 svn_error_t *(*change_file_prop)(void *file_baton, 01052 const char *name, 01053 const svn_string_t *value, 01054 apr_pool_t *scratch_pool); 01055 01056 /** We are done processing a file, whose baton is @a file_baton (set by 01057 * @c add_file or @c open_file). We won't be using the baton any 01058 * more, so whatever resources it refers to may now be freed. 01059 * 01060 * @a text_checksum is the hex MD5 digest for the fulltext that 01061 * resulted from a delta application, see @c apply_textdelta. The 01062 * checksum is ignored if NULL. If not null, it is compared to the 01063 * checksum of the new fulltext, and the error 01064 * SVN_ERR_CHECKSUM_MISMATCH is returned if they do not match. If 01065 * there is no new fulltext, @a text_checksum is ignored. 01066 * 01067 * Any temporary allocations may be performed in @a scratch_pool. 01068 */ 01069 svn_error_t *(*close_file)(void *file_baton, 01070 const char *text_checksum, 01071 apr_pool_t *scratch_pool); 01072 01073 /** In the directory represented by @a parent_baton, indicate that 01074 * @a path is present as a file in the edit source, but cannot be 01075 * cannot be conveyed to the edit consumer. Currently, this would 01076 * only occur because of authorization restrictions, but may change 01077 * in the future. 01078 * 01079 * Any temporary allocations may be performed in @a scratch_pool. 01080 */ 01081 svn_error_t *(*absent_file)(const char *path, 01082 void *parent_baton, 01083 apr_pool_t *scratch_pool); 01084 01085 /** All delta processing is done. Call this, with the @a edit_baton for 01086 * the entire edit. 01087 * 01088 * Any temporary allocations may be performed in @a scratch_pool. 01089 */ 01090 svn_error_t *(*close_edit)(void *edit_baton, 01091 apr_pool_t *scratch_pool); 01092 01093 /** The editor-driver has decided to bail out. Allow the editor to 01094 * gracefully clean up things if it needs to. 01095 * 01096 * Any temporary allocations may be performed in @a scratch_pool. 01097 */ 01098 svn_error_t *(*abort_edit)(void *edit_baton, 01099 apr_pool_t *scratch_pool); 01100 01101 /* Be sure to update svn_delta_get_cancellation_editor() and 01102 * svn_delta_default_editor() if you add a new callback here. */ 01103 } svn_delta_editor_t; 01104 01105 01106 /** Return a default delta editor template, allocated in @a pool. 01107 * 01108 * The editor functions in the template do only the most basic 01109 * baton-swapping: each editor function that produces a baton does so 01110 * by copying its incoming baton into the outgoing baton reference. 01111 * 01112 * This editor is not intended to be useful by itself, but is meant to 01113 * be the basis for a useful editor. After getting a default editor, 01114 * you substitute in your own implementations for the editor functions 01115 * you care about. The ones you don't care about, you don't have to 01116 * implement -- you can rely on the template's implementation to 01117 * safely do nothing of consequence. 01118 */ 01119 svn_delta_editor_t * 01120 svn_delta_default_editor(apr_pool_t *pool); 01121 01122 /** A text-delta window handler which does nothing. 01123 * 01124 * Editors can return this handler from @c apply_textdelta if they don't 01125 * care about text delta windows. 01126 */ 01127 svn_error_t * 01128 svn_delta_noop_window_handler(svn_txdelta_window_t *window, 01129 void *baton); 01130 01131 /** Set @a *editor and @a *edit_baton to a cancellation editor that 01132 * wraps @a wrapped_editor and @a wrapped_baton. 01133 * 01134 * The @a editor will call @a cancel_func with @a cancel_baton when each of 01135 * its functions is called, continuing on to call the corresponding wrapped 01136 * function if @a cancel_func returns #SVN_NO_ERROR. 01137 * 01138 * If @a cancel_func is @c NULL, set @a *editor to @a wrapped_editor and 01139 * @a *edit_baton to @a wrapped_baton. 01140 */ 01141 svn_error_t * 01142 svn_delta_get_cancellation_editor(svn_cancel_func_t cancel_func, 01143 void *cancel_baton, 01144 const svn_delta_editor_t *wrapped_editor, 01145 void *wrapped_baton, 01146 const svn_delta_editor_t **editor, 01147 void **edit_baton, 01148 apr_pool_t *pool); 01149 01150 /** Set @a *editor and @a *edit_baton to an depth-based filtering 01151 * editor that wraps @a wrapped_editor and @a wrapped_baton. 01152 * 01153 * The @a editor will track the depth of this drive against the @a 01154 * requested_depth, taking into account whether not the edit drive is 01155 * making use of a target (via @a has_target), and forward editor 01156 * calls which operate "within" the request depth range through to @a 01157 * wrapped_editor. 01158 * 01159 * @a requested_depth must be one of the following depth values: 01160 * #svn_depth_infinity, #svn_depth_empty, #svn_depth_files, 01161 * #svn_depth_immediates, or #svn_depth_unknown. 01162 * 01163 * If filtering is deemed unnecessary (or if @a requested_depth is 01164 * #svn_depth_unknown), @a *editor and @a *edit_baton will be set to @a 01165 * wrapped_editor and @a wrapped_baton, respectively; otherwise, 01166 * they'll be set to new objects allocated from @a pool. 01167 * 01168 * @note Because the svn_delta_editor_t interface's @c delete_entry() 01169 * function doesn't carry node kind information, a depth-based 01170 * filtering editor being asked to filter for #svn_depth_files but 01171 * receiving a @c delete_entry() call on an immediate child of the 01172 * editor's target is unable to know if that deletion should be 01173 * allowed or filtered out -- a delete of a top-level file is okay in 01174 * this case, a delete of a top-level subdirectory is not. As such, 01175 * this filtering editor takes a conservative approach, and ignores 01176 * top-level deletion requests when filtering for #svn_depth_files. 01177 * Fortunately, most non-depth-aware (pre-1.5) Subversion editor 01178 * drivers can be told to drive non-recursively (where non-recursive 01179 * means essentially #svn_depth_files), which means they won't 01180 * transmit out-of-scope editor commands anyway. 01181 * 01182 * @since New in 1.5. 01183 */ 01184 svn_error_t * 01185 svn_delta_depth_filter_editor(const svn_delta_editor_t **editor, 01186 void **edit_baton, 01187 const svn_delta_editor_t *wrapped_editor, 01188 void *wrapped_edit_baton, 01189 svn_depth_t requested_depth, 01190 svn_boolean_t has_target, 01191 apr_pool_t *pool); 01192 01193 /** @} */ 01194 01195 01196 /** Path-based editor drives. 01197 * 01198 * @defgroup svn_delta_path_delta_drivers Path-based delta drivers 01199 * @{ 01200 */ 01201 01202 /** Callback function type for svn_delta_path_driver(). 01203 * 01204 * The handler of this callback is given the callback baton @a 01205 * callback_baton, @a path which is a relpath relative to the 01206 * root of the edit, and the @a parent_baton which represents 01207 * path's parent directory as created by the editor passed to 01208 * svn_delta_path_driver(). 01209 * 01210 * If @a path represents a directory, the handler must return a @a 01211 * *dir_baton for @a path, generated from the same editor (so that the 01212 * driver can later close that directory). 01213 * 01214 * If, however, @a path represents a file, the handler should NOT 01215 * return any file batons. It can close any opened or added files 01216 * immediately, or delay that close until the end of the edit when 01217 * svn_delta_path_driver() returns. 01218 * 01219 * Finally, if @a parent_baton is @c NULL, then the root of the edit 01220 * is also one of the paths passed to svn_delta_path_driver(). The 01221 * handler of this callback must call the editor's open_root() 01222 * function and return the top-level root dir baton in @a *dir_baton. 01223 */ 01224 typedef svn_error_t *(*svn_delta_path_driver_cb_func_t)( 01225 void **dir_baton, 01226 void *parent_baton, 01227 void *callback_baton, 01228 const char *path, 01229 apr_pool_t *pool); 01230 01231 01232 /** Drive @a editor (with its @a edit_baton) to visit each path in @a paths. 01233 * As each path is hit as part of the editor drive, use 01234 * @a callback_func and @a callback_baton to allow the caller to handle 01235 * the portion of the editor drive related to that path. 01236 * 01237 * Each path in @a paths is a (const char *) relpath, relative 01238 * to the root path of the @a edit. The editor drive will be 01239 * performed in the same order as @a paths. The paths should be sorted 01240 * using something like svn_sort_compare_paths to ensure that a depth-first 01241 * pattern is observed for directory/file baton creation. If @a sort_paths 01242 * is set, the function will sort the paths for you. Some callers may need 01243 * further customization of the order (ie. libsvn_delta/compat.c). 01244 * 01245 * Use @a scratch_pool for all necessary allocations. 01246 * 01247 * @since New in 1.8. 01248 */ 01249 svn_error_t * 01250 svn_delta_path_driver2(const svn_delta_editor_t *editor, 01251 void *edit_baton, 01252 const apr_array_header_t *paths, 01253 svn_boolean_t sort_paths, 01254 svn_delta_path_driver_cb_func_t callback_func, 01255 void *callback_baton, 01256 apr_pool_t *scratch_pool); 01257 01258 01259 /** Similar to svn_delta_path_driver2, but takes an (unused) revision, 01260 * and will sort the provided @a paths using svn_sort_compare_paths. 01261 * 01262 * @note In versions prior to 1.8, this function would modify the order 01263 * of elements in @a paths, despite the 'const' marker on the parameter. 01264 * This has been fixed in 1.8. 01265 * 01266 * @deprecated Provided for backward compatibility with the 1.7 API. 01267 */ 01268 SVN_DEPRECATED 01269 svn_error_t * 01270 svn_delta_path_driver(const svn_delta_editor_t *editor, 01271 void *edit_baton, 01272 svn_revnum_t revision, 01273 const apr_array_header_t *paths, 01274 svn_delta_path_driver_cb_func_t callback_func, 01275 void *callback_baton, 01276 apr_pool_t *scratch_pool); 01277 01278 /** @} */ 01279 01280 01281 /*** File revision iterator types ***/ 01282 01283 /** 01284 * The callback invoked by file rev loopers, such as 01285 * svn_ra_plugin_t.get_file_revs2() and svn_repos_get_file_revs2(). 01286 * 01287 * @a baton is provided by the caller, @a path is the pathname of the file 01288 * in revision @a rev and @a rev_props are the revision properties. 01289 * 01290 * If @a delta_handler and @a delta_baton are non-NULL, they may be set to a 01291 * handler/baton which will be called with the delta between the previous 01292 * revision and this one after the return of this callback. They may be 01293 * left as NULL/NULL. 01294 * 01295 * @a result_of_merge will be @c TRUE if the revision being returned was 01296 * included as the result of a merge. 01297 * 01298 * @a prop_diffs is an array of svn_prop_t elements indicating the property 01299 * delta for this and the previous revision. 01300 * 01301 * @a pool may be used for temporary allocations, but you can't rely 01302 * on objects allocated to live outside of this particular call and 01303 * the immediately following calls to @a *delta_handler if any. (Pass 01304 * in a pool via @a baton if need be.) 01305 * 01306 * @since New in 1.5. 01307 */ 01308 typedef svn_error_t *(*svn_file_rev_handler_t)( 01309 void *baton, 01310 const char *path, 01311 svn_revnum_t rev, 01312 apr_hash_t *rev_props, 01313 svn_boolean_t result_of_merge, 01314 svn_txdelta_window_handler_t *delta_handler, 01315 void **delta_baton, 01316 apr_array_header_t *prop_diffs, 01317 apr_pool_t *pool); 01318 01319 /** 01320 * The old file rev handler interface. 01321 * 01322 * @note #svn_file_rev_handler_old_t is a placeholder type for both 01323 * #svn_repos_file_rev_handler_t and #svn_ra_file_rev_handler_t. It is 01324 * reproduced here for dependency reasons. 01325 * 01326 * @deprecated This type is provided for the svn_compat_wrap_file_rev_handler() 01327 * compatibility wrapper, and should not be used for new development. 01328 * @since New in 1.5. 01329 */ 01330 typedef svn_error_t *(*svn_file_rev_handler_old_t)( 01331 void *baton, 01332 const char *path, 01333 svn_revnum_t rev, 01334 apr_hash_t *rev_props, 01335 svn_txdelta_window_handler_t *delta_handler, 01336 void **delta_baton, 01337 apr_array_header_t *prop_diffs, 01338 apr_pool_t *pool); 01339 01340 /** Return, in @a *handler2 and @a *handler2_baton a function/baton that 01341 * will call @a handler/@a handler_baton, allocating the @a *handler2_baton 01342 * in @a pool. 01343 * 01344 * @note This is used by compatibility wrappers, which exist in more than 01345 * Subversion core library. 01346 * 01347 * @note #svn_file_rev_handler_old_t is a placeholder type for both 01348 * #svn_repos_file_rev_handler_t and #svn_ra_file_rev_handler_t. It is 01349 * reproduced here for dependency reasons. 01350 * 01351 * @since New in 1.5. 01352 */ 01353 void 01354 svn_compat_wrap_file_rev_handler(svn_file_rev_handler_t *handler2, 01355 void **handler2_baton, 01356 svn_file_rev_handler_old_t handler, 01357 void *handler_baton, 01358 apr_pool_t *pool); 01359 01360 /** @} end group: delta_support */ 01361 01362 01363 #ifdef __cplusplus 01364 } 01365 #endif /* __cplusplus */ 01366 01367 #endif /* SVN_DELTA_H */