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