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