Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

svn_delta.h

Go to the documentation of this file.
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 */

Generated on Sat Jun 30 13:41:55 2007 for Subversion by  doxygen 1.3.9.1