Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_delta.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Copyright (c) 2000-2008 CollabNet. All rights reserved.
5  *
6  * This software is licensed as described in the file COPYING, which
7  * you should have received as part of this distribution. The terms
8  * are also available at http://subversion.tigris.org/license-1.html.
9  * If newer versions of this license are posted there, you may use a
10  * newer version instead, at your option.
11  *
12  * This software consists of voluntary contributions made by many
13  * individuals. For exact contribution history, see the revision
14  * history and logs, available at http://subversion.tigris.org/.
15  * ====================================================================
16  * @endcopyright
17  *
18  * @file svn_delta.h
19  * @brief Delta-parsing
20  */
21 
22 /* ==================================================================== */
23 
24 
25 
26 #ifndef SVN_DELTA_H
27 #define SVN_DELTA_H
28 
29 #include <apr.h>
30 #include <apr_pools.h>
31 #include <apr_hash.h>
32 #include <apr_tables.h>
33 #include <apr_file_io.h> /* for apr_file_t */
34 
35 #include "svn_types.h"
36 #include "svn_string.h"
37 #include "svn_io.h"
38 #include "svn_version.h"
39 #include "svn_checksum.h"
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif /* __cplusplus */
44 
45 
46 
47 /**
48  * Get libsvn_delta version information.
49  *
50  * @since New in 1.1.
51  */
52 const svn_version_t *
53 svn_delta_version(void);
54 
55 /**
56  * @defgroup delta_support Delta generation and handling
57  *
58  * @{
59  */
60 
61 /** Text deltas.
62  *
63  * A text delta represents the difference between two strings of
64  * bytes, the `source' string and the `target' string. Given a source
65  * string and a target string, we can compute a text delta; given a
66  * source string and a delta, we can reconstruct the target string.
67  * However, note that deltas are not reversible: you cannot always
68  * reconstruct the source string given the target string and delta.
69  *
70  * Since text deltas can be very large, the interface here allows us
71  * to produce and consume them in pieces. Each piece, represented by
72  * an @c svn_txdelta_window_t structure, describes how to produce the
73  * next section of the target string.
74  *
75  * To compute a new text delta:
76  *
77  * - We call svn_txdelta() on the streams we want to compare. That
78  * returns us an @c svn_txdelta_stream_t object.
79  *
80  * - We then call svn_txdelta_next_window() on the stream object
81  * repeatedly. Each call returns a new @c svn_txdelta_window_t
82  * object, which describes the next portion of the target string.
83  * When svn_txdelta_next_window() returns zero, we are done building
84  * the target string.
85  *
86  * @defgroup svn_delta_txt_delta Text deltas
87  * @{
88  */
89 
90 /** Action codes for text delta instructions. */
92  /** Append the @a length bytes at @a offset in the source view to the
93  * target.
94  *
95  * It must be the case that 0 <= @a offset < @a offset +
96  * @a length <= size of source view.
97  */
99 
100  /** Append the @a length bytes at @a offset in the target view, to the
101  * target.
102  *
103  * It must be the case that 0 <= @a offset < current position in the
104  * target view.
105  *
106  * However! @a offset + @a length may be *beyond* the end of the existing
107  * target data. "Where the heck does the text come from, then?"
108  * If you start at @a offset, and append @a length bytes one at a time,
109  * it'll work out --- you're adding new bytes to the end at the
110  * same rate you're reading them from the middle. Thus, if your
111  * current target text is "abcdefgh", and you get an @c svn_txdelta_target
112  * instruction whose @a offset is 6 and whose @a length is 7,
113  * the resulting string is "abcdefghghghghg". This trick is actually
114  * useful in encoding long runs of consecutive characters, long runs
115  * of CR/LF pairs, etc.
116  */
118 
119  /** Append the @a length bytes at @a offset in the window's @a new string
120  * to the target.
121  *
122  * It must be the case that 0 <= @a offset < @a offset +
123  * @a length <= length of @a new. Windows MUST use new data in ascending
124  * order with no overlap at the moment; svn_txdelta_to_svndiff()
125  * depends on this.
126  */
128 };
129 
130 /** A single text delta instruction. */
131 typedef struct svn_txdelta_op_t
132 {
133  /** Action code of delta instruction */
135  /** Offset of delta, see #svn_delta_action for more details. */
136  apr_size_t offset;
137  /** Number of bytes of delta, see #svn_delta_action for more details. */
138  apr_size_t length;
140 
141 
142 /** An @c svn_txdelta_window_t object describes how to reconstruct a
143  * contiguous section of the target string (the "target view") using a
144  * specified contiguous region of the source string (the "source
145  * view"). It contains a series of instructions which assemble the
146  * new target string text by pulling together substrings from:
147  *
148  * - the source view,
149  *
150  * - the previously constructed portion of the target view,
151  *
152  * - a string of new data contained within the window structure
153  *
154  * The source view must always slide forward from one window to the
155  * next; that is, neither the beginning nor the end of the source view
156  * may move to the left as we read from a window stream. This
157  * property allows us to apply deltas to non-seekable source streams
158  * without making a full copy of the source stream.
159  */
160 typedef struct svn_txdelta_window_t
161 {
162 
163  /** The offset of the source view for this window. */
165 
166  /** The length of the source view for this window. */
167  apr_size_t sview_len;
168 
169  /** The length of the target view for this window, i.e. the number of
170  * bytes which will be reconstructed by the instruction stream. */
171  apr_size_t tview_len;
172 
173  /** The number of instructions in this window. */
174  int num_ops;
175 
176  /** The number of svn_txdelta_source instructions in this window. If
177  * this number is 0, we don't need to read the source in order to
178  * reconstruct the target view.
179  */
180  int src_ops;
181 
182  /** The instructions for this window. */
184 
185  /** New data, for use by any `svn_txdelta_new' instructions. */
187 
189 
190 /**
191  * Return a deep copy of @a window, allocated in @a pool.
192  *
193  * @since New in 1.3.
194  */
197  apr_pool_t *pool);
198 
199 /**
200  * Compose two delta windows, yielding a third, allocated in @a pool.
201  *
202  * @since New in 1.4
203  *
204  */
207  const svn_txdelta_window_t *window_B,
208  apr_pool_t *pool);
209 
210 /**
211  * Apply the instructions from @a window to a source view @a sbuf to
212  * produce a target view @a tbuf.
213  *
214  * @a sbuf is assumed to have @a window->sview_len bytes of data and
215  * @a tbuf is assumed to have room for @a tlen bytes of output. @a
216  * tlen may be more than @a window->tview_len, so return the actual
217  * number of bytes written. @a sbuf is not touched and may be NULL if
218  * @a window contains no source-copy operations. This is purely a
219  * memory operation; nothing can go wrong as long as we have a valid
220  * window.
221  *
222  * @since New in 1.4
223  *
224  */
225 void
227  const char *sbuf, char *tbuf,
228  apr_size_t *tlen);
229 
230 /** A typedef for functions that consume a series of delta windows, for
231  * use in caller-pushes interfaces. Such functions will typically
232  * apply the delta windows to produce some file, or save the windows
233  * somewhere. At the end of the delta window stream, you must call
234  * this function passing zero for the @a window argument.
235  */
236 typedef svn_error_t *(*svn_txdelta_window_handler_t)
237  (svn_txdelta_window_t *window, void *baton);
238 
239 
240 /** This function will generate delta windows that turn @a source into
241  * @a target, and pushing these windows into the @a handler window handler
242  * callback (passing @a handler_baton to each invocation).
243  *
244  * If @a checksum is not NULL, then a checksum (of kind @a checksum_kind)
245  * will be computed for the target stream, and placed into *checksum.
246  *
247  * If @a cancel_func is not NULL, then it should refer to a cancellation
248  * function (along with @a cancel_baton).
249  *
250  * Results (the checksum) will be allocated from @a result_pool, and all
251  * temporary allocations will be performed in @a scratch_pool.
252  *
253  * Note: this function replaces the combination of svn_txdelta() and
254  * svn_txdelta_send_txstream().
255  *
256  * @since New in 1.6.
257  */
258 svn_error_t *
260  svn_stream_t *target,
262  void *handler_baton,
263  svn_checksum_kind_t checksum_kind,
264  svn_checksum_t **checksum,
265  svn_cancel_func_t cancel_func,
266  void *cancel_baton,
267  apr_pool_t *result_pool,
268  apr_pool_t *scratch_pool);
269 
270 
271 /** A delta stream --- this is the hat from which we pull a series of
272  * svn_txdelta_window_t objects, which, taken in order, describe the
273  * entire target string. This type is defined within libsvn_delta, and
274  * opaque outside that library.
275  */
277 
278 
279 /** A typedef for a function that will set @a *window to the next
280  * window from a @c svn_txdelta_stream_t object. If there are no more
281  * delta windows, NULL will be used. The returned window, if any,
282  * will be allocated in @a pool. @a baton is the baton specified
283  * when the stream was created.
284  *
285  * @since New in 1.4.
286  */
287 typedef svn_error_t *
288 (*svn_txdelta_next_window_fn_t)(svn_txdelta_window_t **window,
289  void *baton,
290  apr_pool_t *pool);
291 
292 /** A typedef for a function that will return the md5 checksum of the
293  * fulltext deltified by a @c svn_txdelta_stream_t object. Will
294  * return NULL if the final null window hasn't yet been returned by
295  * the stream. The returned value will be allocated in the same pool
296  * as the stream. @a baton is the baton specified when the stream was
297  * created.
298  *
299  * @since New in 1.4.
300  */
301 typedef const unsigned char *
302 (*svn_txdelta_md5_digest_fn_t)(void *baton);
303 
304 /** Create and return a generic text delta stream with @a baton, @a
305  * next_window and @a md5_digest. Allocate the new stream in @a
306  * pool.
307  *
308  * @since New in 1.4.
309  */
311 svn_txdelta_stream_create(void *baton,
312  svn_txdelta_next_window_fn_t next_window,
313  svn_txdelta_md5_digest_fn_t md5_digest,
314  apr_pool_t *pool);
315 
316 /** Set @a *window to a pointer to the next window from the delta stream
317  * @a stream. When we have completely reconstructed the target string,
318  * set @a *window to zero.
319  *
320  * The window will be allocated in @a pool.
321  */
322 svn_error_t *
324  svn_txdelta_stream_t *stream,
325  apr_pool_t *pool);
326 
327 
328 /** Return the md5 digest for the complete fulltext deltified by
329  * @a stream, or @c NULL if @a stream has not yet returned its final
330  * @c NULL window. The digest is allocated in the same memory as @a
331  * STREAM.
332  */
333 const unsigned char *
335 
336 /** Set @a *stream to a pointer to a delta stream that will turn the byte
337  * string from @a source into the byte stream from @a target.
338  *
339  * @a source and @a target are both readable generic streams. When we call
340  * svn_txdelta_next_window() on @a *stream, it will read from @a source and
341  * @a target to gather as much data as it needs.
342  *
343  * Do any necessary allocation in a sub-pool of @a pool.
344  */
345 void
347  svn_stream_t *source,
348  svn_stream_t *target,
349  apr_pool_t *pool);
350 
351 
352 /**
353  * Return a writable stream which, when fed target data, will send
354  * delta windows to @a handler/@a handler_baton which transform the
355  * data in @a source to the target data. As usual, the window handler
356  * will receive a NULL window to signify the end of the window stream.
357  * The stream handler functions will read data from @a source as
358  * necessary.
359  *
360  * @since New in 1.1.
361  */
362 svn_stream_t *
364  void *handler_baton,
365  svn_stream_t *source,
366  apr_pool_t *pool);
367 
368 
369 /** Send the contents of @a string to window-handler @a handler/@a baton.
370  * This is effectively a 'copy' operation, resulting in delta windows that
371  * make the target equivalent to the value of @a string.
372  *
373  * All temporary allocation is performed in @a pool.
374  */
375 svn_error_t *
378  void *handler_baton,
379  apr_pool_t *pool);
380 
381 /** Send the contents of @a stream to window-handler @a handler/@a baton.
382  * This is effectively a 'copy' operation, resulting in delta windows that
383  * make the target equivalent to the stream.
384  *
385  * If @a digest is non-NULL, populate it with the md5 checksum for the
386  * fulltext that was deltified (@a digest must be at least
387  * @c APR_MD5_DIGESTSIZE bytes long).
388  *
389  * All temporary allocation is performed in @a pool.
390  */
391 svn_error_t *
394  void *handler_baton,
395  unsigned char *digest,
396  apr_pool_t *pool);
397 
398 /** Send the contents of @a txstream to window-handler @a handler/@a baton.
399  * Windows will be extracted from the stream and delivered to the handler.
400  *
401  * All temporary allocation is performed in @a pool.
402  */
403 svn_error_t *
406  void *handler_baton,
407  apr_pool_t *pool);
408 
409 
410 /** Prepare to apply a text delta. @a source is a readable generic stream
411  * yielding the source data, @a target is a writable generic stream to
412  * write target data to, and allocation takes place in a sub-pool of
413  * @a pool. On return, @a *handler is set to a window handler function and
414  * @a *handler_baton is set to the value to pass as the @a baton argument to
415  * @a *handler.
416  *
417  * If @a result_digest is non-NULL, it points to APR_MD5_DIGESTSIZE bytes
418  * of storage, and the final call to @a handler populates it with the
419  * MD5 digest of the resulting fulltext.
420  *
421  * If @a error_info is non-NULL, it is inserted parenthetically into
422  * the error string for any error returned by svn_txdelta_apply() or
423  * @a *handler. (It is normally used to provide path information,
424  * since there's nothing else in the delta application's context to
425  * supply a path for error messages.)
426  *
427  * @note To avoid lifetime issues, @a error_info is copied into
428  * @a pool or a subpool thereof.
429  */
430 void
432  svn_stream_t *target,
433  unsigned char *result_digest,
434  const char *error_info,
435  apr_pool_t *pool,
437  void **handler_baton);
438 
439 
440 
441 /*** Producing and consuming svndiff-format text deltas. ***/
442 
443 /** Prepare to produce an svndiff-format diff from text delta windows.
444  * @a output is a writable generic stream to write the svndiff data to.
445  * Allocation takes place in a sub-pool of @a pool. On return, @a *handler
446  * is set to a window handler function and @a *handler_baton is set to
447  * the value to pass as the @a baton argument to @a *handler. The svndiff
448  * version is @a svndiff_version.
449  *
450  * @since New in 1.4.
451  */
452 void
454  void **handler_baton,
455  svn_stream_t *output,
456  int svndiff_version,
457  apr_pool_t *pool);
458 
459 /** Similar to svn_txdelta_to_svndiff2, but always using svndiff
460  * version 0.
461  *
462  * @deprecated Provided for backward compatibility with the 1.3 API.
463  */
465 void
467  apr_pool_t *pool,
469  void **handler_baton);
470 
471 /** Return a writable generic stream which will parse svndiff-format
472  * data into a text delta, invoking @a handler with @a handler_baton
473  * whenever a new window is ready. If @a error_on_early_close is @c
474  * TRUE, attempting to close this stream before it has handled the entire
475  * svndiff data set will result in @c SVN_ERR_SVNDIFF_UNEXPECTED_END,
476  * else this error condition will be ignored.
477  */
478 svn_stream_t *
480  void *handler_baton,
481  svn_boolean_t error_on_early_close,
482  apr_pool_t *pool);
483 
484 /**
485  * Read and parse one delta window in svndiff format from the
486  * readable stream @a stream and place it in @a *window, allocating
487  * the result in @a pool. The caller must take responsibility for
488  * stripping off the four-byte 'SVN@<ver@>' header at the beginning of
489  * the svndiff document before reading the first window, and must
490  * provide the version number (the value of the fourth byte) to each
491  * invocation of this routine with the @a svndiff_version argument.
492  *
493  * @since New in 1.1.
494  */
495 svn_error_t *
497  svn_stream_t *stream,
498  int svndiff_version,
499  apr_pool_t *pool);
500 
501 /**
502  * Read and skip one delta window in svndiff format from the
503  * file @a file. @a pool is used for temporary allocations. The
504  * caller must take responsibility for stripping off the four-byte
505  * 'SVN@<ver@>' header at the beginning of the svndiff document before
506  * reading or skipping the first window, and must provide the version
507  * number (the value of the fourth byte) to each invocation of this
508  * routine with the @a svndiff_version argument.
509  *
510  * @since New in 1.1.
511  */
512 svn_error_t *
513 svn_txdelta_skip_svndiff_window(apr_file_t *file,
514  int svndiff_version,
515  apr_pool_t *pool);
516 
517 /** @} */
518 
519 
520 /** Traversing tree deltas.
521  *
522  * In Subversion, we've got various producers and consumers of tree
523  * deltas.
524  *
525  * In processing a `commit' command:
526  * - The client examines its working copy data, and produces a tree
527  * delta describing the changes to be committed.
528  * - The client networking library consumes that delta, and sends them
529  * across the wire as an equivalent series of network requests (for
530  * example, to svnserve as an ra_svn protocol stream, or to an
531  * Apache httpd server as WebDAV commands)
532  * - The server receives those requests and produces a tree delta ---
533  * hopefully equivalent to the one the client produced above.
534  * - The Subversion server module consumes that delta and commits an
535  * appropriate transaction to the filesystem.
536  *
537  * In processing an `update' command, the process is reversed:
538  * - The Subversion server module talks to the filesystem and produces
539  * a tree delta describing the changes necessary to bring the
540  * client's working copy up to date.
541  * - The server consumes this delta, and assembles a reply
542  * representing the appropriate changes.
543  * - The client networking library receives that reply, and produces a
544  * tree delta --- hopefully equivalent to the one the Subversion
545  * server produced above.
546  * - The working copy library consumes that delta, and makes the
547  * appropriate changes to the working copy.
548  *
549  * The simplest approach would be to represent tree deltas using the
550  * obvious data structure. To do an update, the server would
551  * construct a delta structure, and the working copy library would
552  * apply that structure to the working copy; the network layer's job
553  * would simply be to get the structure across the net intact.
554  *
555  * However, we expect that these deltas will occasionally be too large
556  * to fit in a typical workstation's swap area. For example, in
557  * checking out a 200Mb source tree, the entire source tree is
558  * represented by a single tree delta. So it's important to handle
559  * deltas that are too large to fit in swap all at once.
560  *
561  * So instead of representing the tree delta explicitly, we define a
562  * standard way for a consumer to process each piece of a tree delta
563  * as soon as the producer creates it. The @c svn_delta_editor_t
564  * structure is a set of callback functions to be defined by a delta
565  * consumer, and invoked by a delta producer. Each invocation of a
566  * callback function describes a piece of the delta --- a file's
567  * contents changing, something being renamed, etc.
568  *
569  * @defgroup svn_delta_tree_deltas Tree deltas
570  * @{
571  */
572 
573 /** A structure full of callback functions the delta source will invoke
574  * as it produces the delta.
575  *
576  * Note: Don't try to allocate one of these yourself. Instead, always
577  * use svn_delta_default_editor() or some other constructor, to ensure
578  * that unused slots are filled in with no-op functions.
579  *
580  * <h3>Function Usage</h3>
581  *
582  * Here's how to use these functions to express a tree delta.
583  *
584  * The delta consumer implements the callback functions described in
585  * this structure, and the delta producer invokes them. So the
586  * caller (producer) is pushing tree delta data at the callee
587  * (consumer).
588  *
589  * At the start of traversal, the consumer provides @a edit_baton, a
590  * baton global to the entire delta edit. If there is a target
591  * revision that needs to be set for this operation, the producer
592  * should call the @c set_target_revision function at this point.
593  *
594  * Next, if there are any tree deltas to express, the producer should
595  * pass the @a edit_baton to the @c open_root function, to get a baton
596  * representing root of the tree being edited.
597  *
598  * Most of the callbacks work in the obvious way:
599  *
600  * @c delete_entry
601  * @c add_file
602  * @c add_directory
603  * @c open_file
604  * @c open_directory
605  *
606  * Each of these takes a directory baton, indicating the directory
607  * in which the change takes place, and a @a path argument, giving the
608  * path (relative to the root of the edit) of the file,
609  * subdirectory, or directory entry to change. Editors will usually
610  * want to join this relative path with some base stored in the edit
611  * baton (e.g. a URL, a location in the OS filesystem).
612  *
613  * Since every call requires a parent directory baton, including
614  * @c add_directory and @c open_directory, where do we ever get our
615  * initial directory baton, to get things started? The @c open_root
616  * function returns a baton for the top directory of the change. In
617  * general, the producer needs to invoke the editor's @c open_root
618  * function before it can get anything of interest done.
619  *
620  * While @c open_root provides a directory baton for the root of
621  * the tree being changed, the @c add_directory and @c open_directory
622  * callbacks provide batons for other directories. Like the
623  * callbacks above, they take a @a parent_baton and a relative path
624  * @a path, and then return a new baton for the subdirectory being
625  * created / modified --- @a child_baton. The producer can then use
626  * @a child_baton to make further changes in that subdirectory.
627  *
628  * So, if we already have subdirectories named `foo' and `foo/bar',
629  * then the producer can create a new file named `foo/bar/baz.c' by
630  * calling:
631  *
632  * - @c open_root () --- yielding a baton @a root for the top directory
633  *
634  * - @c open_directory (@a root, "foo") --- yielding a baton @a f for `foo'
635  *
636  * - @c open_directory (@a f, "foo/bar") --- yielding a baton @a b for
637  * `foo/bar'
638  *
639  * - @c add_file (@a b, "foo/bar/baz.c")
640  *
641  * When the producer is finished making changes to a directory, it
642  * should call @c close_directory. This lets the consumer do any
643  * necessary cleanup, and free the baton's storage.
644  *
645  * The @c add_file and @c open_file callbacks each return a baton
646  * for the file being created or changed. This baton can then be
647  * passed to @c apply_textdelta to change the file's contents, or
648  * @c change_file_prop to change the file's properties. When the
649  * producer is finished making changes to a file, it should call
650  * @c close_file, to let the consumer clean up and free the baton.
651  *
652  * The @c add_file and @c add_directory functions each take arguments
653  * @a copyfrom_path and @a copyfrom_revision. If @a copyfrom_path is
654  * non-@c NULL, then @a copyfrom_path and @a copyfrom_revision indicate where
655  * the file or directory should be copied from (to create the file
656  * or directory being added). In that case, @a copyfrom_path must be
657  * either a path relative to the root of the edit, or a URI from the
658  * repository being edited. If @a copyfrom_path is @c NULL, then @a
659  * copyfrom_revision must be @c SVN_INVALID_REVNUM; it is invalid to
660  * pass a mix of valid and invalid copyfrom arguments.
661  *
662  *
663  * <h3>Function Call Ordering</h3>
664  *
665  * There are six restrictions on the order in which the producer
666  * may use the batons:
667  *
668  * 1. The producer may call @c open_directory, @c add_directory,
669  * @c open_file, @c add_file at most once on any given directory
670  * entry. @c delete_entry may be called at most once on any given
671  * directory entry and may later be followed by @c add_directory or
672  * @c add_file on the same directory entry. @c delete_entry may
673  * not be called on any directory entry after @c open_directory,
674  * @c add_directory, @c open_file or @c add_file has been called on
675  * that directory entry.
676  *
677  * 2. The producer may not close a directory baton until it has
678  * closed all batons for its subdirectories.
679  *
680  * 3. When a producer calls @c open_directory or @c add_directory,
681  * it must specify the most recently opened of the currently open
682  * directory batons. Put another way, the producer cannot have
683  * two sibling directory batons open at the same time.
684  *
685  * 4. A producer must call @c change_dir_prop on a directory either
686  * before opening any of the directory's subdirs or after closing
687  * them, but not in the middle.
688  *
689  * 5. When the producer calls @c open_file or @c add_file, either:
690  *
691  * (a) The producer must follow with any changes to the file
692  * (@c change_file_prop and/or @c apply_textdelta, as applicable),
693  * followed by a @c close_file call, before issuing any other file
694  * or directory calls, or
695  *
696  * (b) The producer must follow with a @c change_file_prop call if
697  * it is applicable, before issuing any other file or directory
698  * calls; later, after all directory batons including the root
699  * have been closed, the producer must issue @c apply_textdelta
700  * and @c close_file calls.
701  *
702  * 6. When the producer calls @c apply_textdelta, it must make all of
703  * the window handler calls (including the @c NULL window at the
704  * end) before issuing any other @c svn_delta_editor_t calls.
705  *
706  * So, the producer needs to use directory and file batons as if it
707  * is doing a single depth-first traversal of the tree, with the
708  * exception that the producer may keep file batons open in order to
709  * make @c apply_textdelta calls at the end.
710  *
711  *
712  * <h3>Pool Usage</h3>
713  *
714  * Many editor functions are invoked multiple times, in a sequence
715  * determined by the editor "driver". The driver is responsible for
716  * creating a pool for use on each iteration of the editor function,
717  * and clearing that pool between each iteration. The driver passes
718  * the appropriate pool on each function invocation.
719  *
720  * Based on the requirement of calling the editor functions in a
721  * depth-first style, it is usually customary for the driver to similarly
722  * nest the pools. However, this is only a safety feature to ensure
723  * that pools associated with deeper items are always cleared when the
724  * top-level items are also cleared. The interface does not assume, nor
725  * require, any particular organization of the pools passed to these
726  * functions. In fact, if "postfix deltas" are used for files, the file
727  * pools definitely need to live outside the scope of their parent
728  * directories' pools.
729  *
730  * Note that close_directory can be called *before* a file in that
731  * directory has been closed. That is, the directory's baton is
732  * closed before the file's baton. The implication is that
733  * @c apply_textdelta and @c close_file should not refer to a parent
734  * directory baton UNLESS the editor has taken precautions to
735  * allocate it in a pool of the appropriate lifetime (the @a dir_pool
736  * passed to @c open_directory and @c add_directory definitely does not
737  * have the proper lifetime). In general, it is recommended to simply
738  * avoid keeping a parent directory baton in a file baton.
739  *
740  *
741  * <h3>Errors</h3>
742  *
743  * At least one implementation of the editor interface is
744  * asynchronous; an error from one operation may be detected some
745  * number of operations later. As a result, an editor driver must not
746  * assume that an error from an editing function resulted from the
747  * particular operation being detected. Moreover, once an editing
748  * function returns an error, the edit is dead; the only further
749  * operation which may be called on the editor is abort_edit.
750  */
751 typedef struct svn_delta_editor_t
752 {
753  /** Set the target revision for this edit to @a target_revision. This
754  * call, if used, should precede all other editor calls.
755  *
756  * @note This is typically used only for server->client update-type
757  * operations. It doesn't really make much sense for commit-type
758  * operations, because the revision of a commit isn't known until
759  * the commit is finalized.
760  */
761  svn_error_t *(*set_target_revision)(void *edit_baton,
762  svn_revnum_t target_revision,
763  apr_pool_t *pool);
764 
765  /** Set @a *root_baton to a baton for the top directory of the change.
766  * (This is the top of the subtree being changed, not necessarily
767  * the root of the filesystem.) As with any other directory baton, the
768  * producer should call @c close_directory on @a root_baton when done.
769  * And as with other @c open_* calls, the @a base_revision here is the
770  * current revision of the directory (before getting bumped up to the
771  * new target revision set with @c set_target_revision).
772  *
773  * Allocations for the returned @a root_baton should be performed in
774  * @a dir_pool. It is also typical to (possibly) save this pool for later
775  * usage by @c close_directory.
776  */
777  svn_error_t *(*open_root)(void *edit_baton,
778  svn_revnum_t base_revision,
779  apr_pool_t *dir_pool,
780  void **root_baton);
781 
782 
783  /** Remove the directory entry named @a path, a child of the directory
784  * represented by @a parent_baton. If @a revision is a valid
785  * revision number, it is used as a sanity check to ensure that you
786  * are really removing the revision of @a path that you think you are.
787  *
788  * All allocations should be performed in @a pool.
789  *
790  * @note The @a revision parameter is typically used only for
791  * client->server commit-type operations, allowing the server to
792  * verify that it is deleting what the client thinks it should be
793  * deleting. It only really makes sense in the opposite direction
794  * (during server->client update-type operations) when the trees
795  * whose delta is being described are ancestrally related (that is,
796  * one tree is an ancestor of the other).
797  */
798  svn_error_t *(*delete_entry)(const char *path,
799  svn_revnum_t revision,
800  void *parent_baton,
801  apr_pool_t *pool);
802 
803 
804  /** We are going to add a new subdirectory named @a path. We will use
805  * the value this callback stores in @a *child_baton as the
806  * @a parent_baton for further changes in the new subdirectory.
807  *
808  * If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a
809  * copy), and the origin of the copy may be recorded as
810  * @a copyfrom_path under @a copyfrom_revision.
811  *
812  * Allocations for the returned @a child_baton should be performed in
813  * @a dir_pool. It is also typical to (possibly) save this pool for later
814  * usage by @c close_directory.
815  */
816  svn_error_t *(*add_directory)(const char *path,
817  void *parent_baton,
818  const char *copyfrom_path,
819  svn_revnum_t copyfrom_revision,
820  apr_pool_t *dir_pool,
821  void **child_baton);
822 
823  /** We are going to make changes in a subdirectory (of the directory
824  * identified by @a parent_baton). The subdirectory is specified by
825  * @a path. The callback must store a value in @a *child_baton that
826  * should be used as the @a parent_baton for subsequent changes in this
827  * subdirectory. If a valid revnum, @a base_revision is the current
828  * revision of the subdirectory.
829  *
830  * Allocations for the returned @a child_baton should be performed in
831  * @a dir_pool. It is also typical to (possibly) save this pool for later
832  * usage by @c close_directory.
833  */
834  svn_error_t *(*open_directory)(const char *path,
835  void *parent_baton,
836  svn_revnum_t base_revision,
837  apr_pool_t *dir_pool,
838  void **child_baton);
839 
840  /** Change the value of a directory's property.
841  * - @a dir_baton specifies the directory whose property should change.
842  * - @a name is the name of the property to change.
843  * - @a value is the new (final) value of the property, or @c NULL if the
844  * property should be removed altogether.
845  *
846  * The callback is guaranteed to be called exactly once for each property
847  * whose value differs between the start and the end of the edit.
848  *
849  * All allocations should be performed in @a pool.
850  */
851  svn_error_t *(*change_dir_prop)(void *dir_baton,
852  const char *name,
853  const svn_string_t *value,
854  apr_pool_t *pool);
855 
856  /** We are done processing a subdirectory, whose baton is @a dir_baton
857  * (set by @c add_directory or @c open_directory). We won't be using
858  * the baton any more, so whatever resources it refers to may now be
859  * freed.
860  */
861  svn_error_t *(*close_directory)(void *dir_baton,
862  apr_pool_t *pool);
863 
864 
865  /** In the directory represented by @a parent_baton, indicate that
866  * @a path is present as a subdirectory in the edit source, but
867  * cannot be conveyed to the edit consumer (perhaps because of
868  * authorization restrictions).
869  */
870  svn_error_t *(*absent_directory)(const char *path,
871  void *parent_baton,
872  apr_pool_t *pool);
873 
874  /** We are going to add a new file named @a path. The callback can
875  * store a baton for this new file in @a **file_baton; whatever value
876  * it stores there should be passed through to @c apply_textdelta.
877  *
878  * If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a
879  * copy), and the origin of the copy may be recorded as
880  * @a copyfrom_path under @a copyfrom_revision.
881  *
882  * Allocations for the returned @a file_baton should be performed in
883  * @a file_pool. It is also typical to save this pool for later usage
884  * by @c apply_textdelta and possibly @c close_file.
885  */
886  svn_error_t *(*add_file)(const char *path,
887  void *parent_baton,
888  const char *copyfrom_path,
889  svn_revnum_t copyfrom_revision,
890  apr_pool_t *file_pool,
891  void **file_baton);
892 
893  /** We are going to make change to a file named @a path, which resides
894  * in the directory identified by @a parent_baton.
895  *
896  * The callback can store a baton for this new file in @a **file_baton;
897  * whatever value it stores there should be passed through to
898  * @c apply_textdelta. If a valid revnum, @a base_revision is the
899  * current revision of the file.
900  *
901  * Allocations for the returned @a file_baton should be performed in
902  * @a file_pool. It is also typical to save this pool for later usage
903  * by @c apply_textdelta and possibly @c close_file.
904  */
905  svn_error_t *(*open_file)(const char *path,
906  void *parent_baton,
907  svn_revnum_t base_revision,
908  apr_pool_t *file_pool,
909  void **file_baton);
910 
911  /** Apply a text delta, yielding the new revision of a file.
912  *
913  * @a file_baton indicates the file we're creating or updating, and the
914  * ancestor file on which it is based; it is the baton set by some
915  * prior @c add_file or @c open_file callback.
916  *
917  * The callback should set @a *handler to a text delta window
918  * handler; we will then call @a *handler on successive text
919  * delta windows as we receive them. The callback should set
920  * @a *handler_baton to the value we should pass as the @a baton
921  * argument to @a *handler.
922  *
923  * @a base_checksum is the hex MD5 digest for the base text against
924  * which the delta is being applied; it is ignored if NULL, and may
925  * be ignored even if not NULL. If it is not ignored, it must match
926  * the checksum of the base text against which svndiff data is being
927  * applied; if it does not, @c apply_textdelta or the @a *handler call
928  * which detects the mismatch will return the error
929  * SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may
930  * still be an error if @a base_checksum is neither NULL nor the hex
931  * MD5 checksum of the empty string).
932  */
933  svn_error_t *(*apply_textdelta)(void *file_baton,
934  const char *base_checksum,
935  apr_pool_t *pool,
937  void **handler_baton);
938 
939  /** Change the value of a file's property.
940  * - @a file_baton specifies the file whose property should change.
941  * - @a name is the name of the property to change.
942  * - @a value is the new (final) value of the property, or @c NULL if the
943  * property should be removed altogether.
944  *
945  * The callback is guaranteed to be called exactly once for each property
946  * whose value differs between the start and the end of the edit.
947  *
948  * All allocations should be performed in @a pool.
949  */
950  svn_error_t *(*change_file_prop)(void *file_baton,
951  const char *name,
952  const svn_string_t *value,
953  apr_pool_t *pool);
954 
955  /** We are done processing a file, whose baton is @a file_baton (set by
956  * @c add_file or @c open_file). We won't be using the baton any
957  * more, so whatever resources it refers to may now be freed.
958  *
959  * @a text_checksum is the hex MD5 digest for the fulltext that
960  * resulted from a delta application, see @c apply_textdelta. The
961  * checksum is ignored if NULL. If not null, it is compared to the
962  * checksum of the new fulltext, and the error
963  * SVN_ERR_CHECKSUM_MISMATCH is returned if they do not match. If
964  * there is no new fulltext, @a text_checksum is ignored.
965  */
966  svn_error_t *(*close_file)(void *file_baton,
967  const char *text_checksum,
968  apr_pool_t *pool);
969 
970  /** In the directory represented by @a parent_baton, indicate that
971  * @a path is present as a file in the edit source, but cannot be
972  * conveyed to the edit consumer (perhaps because of authorization
973  * restrictions).
974  */
975  svn_error_t *(*absent_file)(const char *path,
976  void *parent_baton,
977  apr_pool_t *pool);
978 
979  /** All delta processing is done. Call this, with the @a edit_baton for
980  * the entire edit.
981  */
982  svn_error_t *(*close_edit)(void *edit_baton,
983  apr_pool_t *pool);
984 
985  /** The editor-driver has decided to bail out. Allow the editor to
986  * gracefully clean up things if it needs to.
987  */
988  svn_error_t *(*abort_edit)(void *edit_baton,
989  apr_pool_t *pool);
990 
991  /* Be sure to update svn_delta_get_cancellation_editor() and
992  * svn_delta_default_editor() if you add a new callback here. */
994 
995 
996 /** Return a default delta editor template, allocated in @a pool.
997  *
998  * The editor functions in the template do only the most basic
999  * baton-swapping: each editor function that produces a baton does so
1000  * by copying its incoming baton into the outgoing baton reference.
1001  *
1002  * This editor is not intended to be useful by itself, but is meant to
1003  * be the basis for a useful editor. After getting a default editor,
1004  * you substitute in your own implementations for the editor functions
1005  * you care about. The ones you don't care about, you don't have to
1006  * implement -- you can rely on the template's implementation to
1007  * safely do nothing of consequence.
1008  */
1010 svn_delta_default_editor(apr_pool_t *pool);
1011 
1012 /** A text-delta window handler which does nothing.
1013  *
1014  * Editors can return this handler from @c apply_textdelta if they don't
1015  * care about text delta windows.
1016  */
1017 svn_error_t *
1019  void *baton);
1020 
1021 /** Set @a *editor and @a *edit_baton to a cancellation editor that
1022  * wraps @a wrapped_editor and @a wrapped_baton.
1023  *
1024  * The @a editor will call @a cancel_func with @a cancel_baton when each of
1025  * its functions is called, continuing on to call the corresponding wrapped
1026  * function if @a cancel_func returns @c SVN_NO_ERROR.
1027  *
1028  * If @a cancel_func is @c NULL, set @a *editor to @a wrapped_editor and
1029  * @a *edit_baton to @a wrapped_baton.
1030  */
1031 svn_error_t *
1033  void *cancel_baton,
1034  const svn_delta_editor_t *wrapped_editor,
1035  void *wrapped_baton,
1036  const svn_delta_editor_t **editor,
1037  void **edit_baton,
1038  apr_pool_t *pool);
1039 
1040 /** Set @a *editor and @a *edit_baton to an depth-based filtering
1041  * editor that wraps @a wrapped_editor and @a wrapped_baton.
1042  *
1043  * The @a editor will track the depth of this drive against the @a
1044  * requested_depth, taking into account whether not the edit drive is
1045  * making use of a target (via @a has_target), and forward editor
1046  * calls which operate "within" the request depth range through to @a
1047  * wrapped_editor.
1048  *
1049  * @a requested_depth must be one of the following depth values:
1050  * @c svn_depth_infinity, @c svn_depth_empty, @c svn_depth_files,
1051  * @c svn_depth_immediates, or @c svn_depth_unknown.
1052  *
1053  * If filtering is deemed unncessary (or if @a requested_depth is @c
1054  * svn_depth_unknown), @a *editor and @a *edit_baton will be set to @a
1055  * wrapped_editor and @a wrapped_baton, respectively; otherwise,
1056  * they'll be set to new objects allocated from @a pool.
1057  *
1058  * @note Because the svn_delta_editor_t interface's @c delete_entry()
1059  * function doesn't carry node kind information, a depth-based
1060  * filtering editor being asked to filter for @c svn_depth_files but
1061  * receiving a @c delete_entry() call on an immediate child of the
1062  * editor's target is unable to know if that deletion should be
1063  * allowed or filtered out -- a delete of a top-level file is okay in
1064  * this case, a delete of a top-level subdirectory is not. As such,
1065  * this filtering editor takes a conservative approach, and ignores
1066  * top-level deletion requests when filtering for @c svn_depth_files.
1067  * Fortunately, most non-depth-aware (pre-1.5) Subversion editor
1068  * drivers can be told to drive non-recursively (where non-recursive
1069  * means essentially @c svn_depth_files), which means they won't
1070  * transmit out-of-scope editor commands anyway.
1071  *
1072  * @since New in 1.5.
1073  */
1074 svn_error_t *
1076  void **edit_baton,
1077  const svn_delta_editor_t *wrapped_editor,
1078  void *wrapped_edit_baton,
1079  svn_depth_t requested_depth,
1080  svn_boolean_t has_target,
1081  apr_pool_t *pool);
1082 
1083 /** @} */
1084 
1085 
1086 /** Path-based editor drives.
1087  *
1088  * @defgroup svn_delta_path_delta_drivers Path-based delta drivers
1089  * @{
1090  */
1091 
1092 /** Callback function type for svn_delta_path_driver().
1093  *
1094  * The handler of this callback is given the callback baton @a
1095  * callback_baton, @a path, and the @a parent_baton which represents
1096  * path's parent directory as created by the editor passed to
1097  * svn_delta_path_driver().
1098  *
1099  * If @a path represents a directory, the handler must return a @a
1100  * *dir_baton for @a path, generated from the same editor (so that the
1101  * driver can later close that directory).
1102  *
1103  * If, however, @a path represents a file, the handler should NOT
1104  * return any file batons. It can close any opened or added files
1105  * immediately, or delay that close until the end of the edit when
1106  * svn_delta_path_driver() returns.
1107  *
1108  * Finally, if @a parent_baton is @c NULL, then the root of the edit
1109  * is also one of the paths passed to svn_delta_path_driver(). The
1110  * handler of this callback must call the editor's open_root()
1111  * function and return the top-level root dir baton in @a *dir_baton.
1112  */
1113 typedef svn_error_t *(*svn_delta_path_driver_cb_func_t)
1114  (void **dir_baton,
1115  void *parent_baton,
1116  void *callback_baton,
1117  const char *path,
1118  apr_pool_t *pool);
1119 
1120 
1121 /** Drive @a editor (with its @a edit_baton) in such a way that
1122  * each path in @a paths is traversed in a depth-first fashion. As
1123  * each path is hit as part of the editor drive, use @a
1124  * callback_func and @a callback_baton to allow the caller to handle
1125  * the portion of the editor drive related to that path.
1126  *
1127  * Use @a revision as the revision number passed to intermediate
1128  * directory openings.
1129  *
1130  * Use @a pool for all necessary allocations.
1131  */
1132 svn_error_t *
1134  void *edit_baton,
1135  svn_revnum_t revision,
1136  apr_array_header_t *paths,
1137  svn_delta_path_driver_cb_func_t callback_func,
1138  void *callback_baton,
1139  apr_pool_t *pool);
1140 
1141 /** @} */
1142 
1143 
1144 /*** File revision iterator types ***/
1145 
1146 /**
1147  * The callback invoked by file rev loopers, such as
1148  * svn_ra_plugin_t.get_file_revs2() and svn_repos_get_file_revs2().
1149  *
1150  * @a baton is provided by the caller, @a path is the pathname of the file
1151  * in revision @a rev and @a rev_props are the revision properties.
1152  *
1153  * If @a delta_handler and @a delta_baton are non-NULL, they may be set to a
1154  * handler/baton which will be called with the delta between the previous
1155  * revision and this one after the return of this callback. They may be
1156  * left as NULL/NULL.
1157  *
1158  * @a result_of_merge will be @c TRUE if the revision being returned was
1159  * included as the result of a merge.
1160  *
1161  * @a prop_diffs is an array of svn_prop_t elements indicating the property
1162  * delta for this and the previous revision.
1163  *
1164  * @a pool may be used for temporary allocations, but you can't rely
1165  * on objects allocated to live outside of this particular call and
1166  * the immediately following calls to @a *delta_handler if any. (Pass
1167  * in a pool via @a baton if need be.)
1168  *
1169  * @since New in 1.5.
1170  */
1171 typedef svn_error_t *(*svn_file_rev_handler_t)
1172  (void *baton,
1173  const char *path,
1174  svn_revnum_t rev,
1175  apr_hash_t *rev_props,
1176  svn_boolean_t result_of_merge,
1177  svn_txdelta_window_handler_t *delta_handler,
1178  void **delta_baton,
1179  apr_array_header_t *prop_diffs,
1180  apr_pool_t *pool);
1181 
1182 /**
1183  * The old file rev handler interface.
1184  *
1185  * @note @c svn_file_rev_handler_old_t is a placeholder type for both
1186  * @c svn_repos_file_rev_handler_t and @c svn_ra_file_rev_handler_t. It is
1187  * reproduced here for dependency reasons.
1188  *
1189  * @deprecated This type is provided for the svn_compat_wrap_file_rev_handler()
1190  * compatibilty wrapper, and should not be used for new development.
1191  * @since New in 1.5.
1192  */
1193 typedef svn_error_t *(*svn_file_rev_handler_old_t)
1194  (void *baton,
1195  const char *path,
1196  svn_revnum_t rev,
1197  apr_hash_t *rev_props,
1198  svn_txdelta_window_handler_t *delta_handler,
1199  void **delta_baton,
1200  apr_array_header_t *prop_diffs,
1201  apr_pool_t *pool);
1202 
1203 /** Return, in @a *handler2 and @a *handler2_baton a function/baton that
1204  * will call @a handler/@a handler_baton, allocating the @a *handler2_baton
1205  * in @a pool.
1206  *
1207  * @note This is used by compatibility wrappers, which exist in more than
1208  * Subversion core library.
1209  *
1210  * @note @c svn_file_rev_handler_old_t is a placeholder type for both
1211  * @c svn_repos_file_rev_handler_t and @c svn_ra_file_rev_handler_t. It is
1212  * reproduced here for dependency reasons.
1213  *
1214  * @since New in 1.5.
1215  */
1216 void
1218  void **handler2_baton,
1220  void *handler_baton,
1221  apr_pool_t *pool);
1222 
1223 /** @} end group: delta_support */
1224 
1225 
1226 #ifdef __cplusplus
1227 }
1228 #endif /* __cplusplus */
1229 
1230 #endif /* SVN_DELTA_H */