- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# svn_delta.h

Go to the documentation of this file.

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

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines