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