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