3
* ====================================================================
4
* Copyright (c) 2000-2004 CollabNet. All rights reserved.
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.
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
* ====================================================================
19
* @brief Delta-parsing
22
/* ==================================================================== */
30
#include <apr_pools.h>
32
#include "svn_types.h"
33
#include "svn_string.h"
34
#include "svn_error.h"
36
#include "svn_version.h"
40
#endif /* __cplusplus */
47
* Get libsvn_delta version information.
49
const svn_version_t *svn_delta_version (void);
54
* A text delta represents the difference between two strings of
55
* bytes, the `source' string and the `target' string. Given a source
56
* string and a target string, we can compute a text delta; given a
57
* source string and a delta, we can reconstruct the target string.
58
* However, note that deltas are not reversible: you cannot always
59
* reconstruct the source string given the target string and delta.
61
* Since text deltas can be very large, the interface here allows us
62
* to produce and consume them in pieces. Each piece, represented by
63
* an @c svn_txdelta_window_t structure, describes how to produce the
64
* next section of the target string.
66
* To compute a new text delta:
68
* - We call @c svn_txdelta on the streams we want to compare. That
69
* returns us an @c svn_txdelta_stream_t object.
71
* - We then call @c svn_txdelta_next_window on the stream object
72
* repeatedly. Each call returns a new @c svn_txdelta_window_t
73
* object, which describes the next portion of the target string.
74
* When @c svn_txdelta_next_window returns zero, we are done building
77
* @defgroup svn_delta_txt_delta text deltas
82
enum svn_delta_action {
83
/** Append the @a len bytes at @a offset in the source view to the
86
* It must be the case that @a 0 <= @a offset < @a offset +
87
* @a len <= size of source view.
91
/** Append the @a len bytes at @a offset in the target view, to the
94
* It must be the case that @a 0 <= @a offset < current position in the
97
* However! @a offset + @a len may be *beyond* the end of the existing
98
* target data. "Where the heck does the text come from, then?"
99
* If you start at @a offset, and append @a len bytes one at a time,
100
* it'll work out --- you're adding new bytes to the end at the
101
* same rate you're reading them from the middle. Thus, if your
102
* current target text is "abcdefgh", and you get an @c svn_delta_target
103
* instruction whose @a offset is @a 6 and whose @a len is @a 7,
104
* the resulting string is "abcdefghghghghg". This trick is actually
105
* useful in encoding long runs of consecutive characters, long runs
106
* of CR/LF pairs, etc.
110
/** Append the @a len bytes at @a offset in the window's @a new string
113
* It must be the case that @a 0 <= @a offset < @a offset +
114
* @a len <= length of @a new. Windows MUST use new data in ascending
115
* order with no overlap at the moment; @c svn_txdelta_to_svndiff
121
/** A single text delta instruction. */
122
typedef struct svn_txdelta_op_t
124
enum svn_delta_action action_code;
130
/** An @c svn_txdelta_window_t object describes how to reconstruct a
131
* contiguous section of the target string (the "target view") using a
132
* specified contiguous region of the source string (the "source
133
* view"). It contains a series of instructions which assemble the
134
* new target string text by pulling together substrings from:
138
* - the previously constructed portion of the target view,
140
* - a string of new data contained within the window structure
142
* The source view must always slide forward from one window to the
143
* next; that is, neither the beginning nor the end of the source view
144
* may move to the left as we read from a window stream. This
145
* property allows us to apply deltas to non-seekable source streams
146
* without making a full copy of the source stream.
148
typedef struct svn_txdelta_window_t
151
/** The offset of the source view for this window. */
152
svn_filesize_t sview_offset;
154
/** The length of the source view for this window. */
155
apr_size_t sview_len;
157
/** The length of the target view for this window, i.e. the number of
158
* bytes which will be reconstructed by the instruction stream. */
159
apr_size_t tview_len;
161
/** The number of instructions in this window. */
164
/** The number of svn_txdelta_source instructions in this window. If
165
* this number is 0, we don't need to read the source in order to
166
* reconstruct the target view.
170
/** The instructions for this window. */
171
const svn_txdelta_op_t *ops;
173
/** New data, for use by any `svn_delta_new' instructions. */
174
const svn_string_t *new_data;
176
} svn_txdelta_window_t;
179
/** A typedef for functions that consume a series of delta windows, for
180
* use in caller-pushes interfaces. Such functions will typically
181
* apply the delta windows to produce some file, or save the windows
182
* somewhere. At the end of the delta window stream, you must call
183
* this function passing zero for the @a window argument.
185
typedef svn_error_t * (*svn_txdelta_window_handler_t)
186
(svn_txdelta_window_t *window, void *baton);
189
/** A delta stream --- this is the hat from which we pull a series of
190
* svn_txdelta_window_t objects, which, taken in order, describe the
191
* entire target string. This type is defined within libsvn_delta, and
192
* opaque outside that library.
194
typedef struct svn_txdelta_stream_t svn_txdelta_stream_t;
197
/** Set @a *window to a pointer to the next window from the delta stream
198
* @a stream. When we have completely reconstructed the target string,
199
* set @a *window to zero.
201
* The window will be allocated in @a pool.
203
svn_error_t *svn_txdelta_next_window (svn_txdelta_window_t **window,
204
svn_txdelta_stream_t *stream,
208
/** Return the @a md5 digest for the complete fulltext deltified by
209
* @a stream, or @c NULL if @a stream has not yet returned its final
210
* @c NULL window. The digest is allocated in the same memory as @a
213
const unsigned char *svn_txdelta_md5_digest (svn_txdelta_stream_t *stream);
215
/** Set @a *stream to a pointer to a delta stream that will turn the byte
216
* string from @a source into the byte stream from @a target.
218
* @a source and @a target are both readable generic streams. When we call
219
* @c svn_txdelta_next_window on @a *stream, it will read from @a source and
220
* @a target to gather as much data as it needs.
222
* Do any necessary allocation in a sub-pool of @a pool.
224
void svn_txdelta (svn_txdelta_stream_t **stream,
225
svn_stream_t *source,
226
svn_stream_t *target,
233
* Return a writable stream which, when fed target data, will send
234
* delta windows to @a handler/@a handler_baton which transform the
235
* data in @a source to the target data. As usual, the window handler
236
* will receive a NULL window to signify the end of the window stream.
237
* The stream handler functions will read data from @a source as
240
svn_stream_t *svn_txdelta_target_push (svn_txdelta_window_handler_t handler,
242
svn_stream_t *source,
246
/** Send the contents of @a string to window-handler @a handler/@a baton.
247
* This is effectively a 'copy' operation, resulting in delta windows that
248
* make the target equivalent to the value of @a string.
250
* All temporary allocation is performed in @a pool.
252
svn_error_t *svn_txdelta_send_string (const svn_string_t *string,
253
svn_txdelta_window_handler_t handler,
257
/** Send the contents of @a stream to window-handler @a handler/@a baton.
258
* This is effectively a 'copy' operation, resulting in delta windows that
259
* make the target equivalent to the stream.
261
* If @a digest is non-null, populate it with the md5 checksum for the
262
* fulltext that was deltified (@a digest must be at least
263
* @c APR_MD5_DIGESTSIZE bytes long).
265
* All temporary allocation is performed in @a pool.
267
svn_error_t *svn_txdelta_send_stream (svn_stream_t *stream,
268
svn_txdelta_window_handler_t handler,
270
unsigned char *digest,
273
/** Send the contents of @a txstream to window-handler @a handler/@a baton.
274
* Windows will be extracted from the stream and delivered to the handler.
276
* All temporary allocation is performed in @a pool.
278
svn_error_t *svn_txdelta_send_txstream (svn_txdelta_stream_t *txstream,
279
svn_txdelta_window_handler_t handler,
284
/** Prepare to apply a text delta. @a source is a readable generic stream
285
* yielding the source data, @a target is a writable generic stream to
286
* write target data to, and allocation takes place in a sub-pool of
287
* @a pool. On return, @a *handler is set to a window handler function and
288
* @a *handler_baton is set to the value to pass as the @a baton argument to
291
* If @a result_digest is non-null, it points to APR_MD5_DIGESTSIZE bytes
292
* of storage, and the final call to @a handler populates it with the
293
* MD5 digest of the resulting fulltext.
295
* If @a error_info is non-null, it is inserted parenthetically into
296
* the error string for any error returned by svn_txdelta_apply() or
297
* @a *handler. (It is normally used to provide path information,
298
* since there's nothing else in the delta application's context to
299
* supply a path for error messages.)
301
* Note: To avoid lifetime issues, @a error_info is copied into
302
* @a pool or a subpool thereof.
304
void svn_txdelta_apply (svn_stream_t *source,
305
svn_stream_t *target,
306
unsigned char *result_digest,
307
const char *error_info,
309
svn_txdelta_window_handler_t *handler,
310
void **handler_baton);
314
/*** Producing and consuming svndiff-format text deltas. ***/
316
/** Prepare to produce an svndiff-format diff from text delta windows.
317
* @a output is a writable generic stream to write the svndiff data to.
318
* Allocation takes place in a sub-pool of @a pool. On return, @a *handler
319
* is set to a window handler function and @a *handler_baton is set to
320
* the value to pass as the @a baton argument to @a *handler.
322
void svn_txdelta_to_svndiff (svn_stream_t *output,
324
svn_txdelta_window_handler_t *handler,
325
void **handler_baton);
327
/** Return a writable generic stream which will parse svndiff-format
328
* data into a text delta, invoking @a handler with @a handler_baton
329
* whenever a new window is ready. If @a error_on_early_close is @c
330
* TRUE, attempting to close this stream before it has handled the entire
331
* svndiff data set will result in @c SVN_ERR_SVNDIFF_UNEXPECTED_END,
332
* else this error condition will be ignored.
334
svn_stream_t *svn_txdelta_parse_svndiff (svn_txdelta_window_handler_t handler,
336
svn_boolean_t error_on_early_close,
342
* Read and parse one delta window in svndiff format from the
343
* readable stream @a stream and place it in @a *window, allocating
344
* the result in @a pool. The caller must take responsibility for
345
* stripping off the four-byte 'SVN@<ver@>' header at the beginning of
346
* the svndiff document before reading the first window, and must
347
* provide the version number (the value of the fourth byte) to each
348
* invocation of this routine with the @a svndiff_version argument. */
349
svn_error_t *svn_txdelta_read_svndiff_window (svn_txdelta_window_t **window,
350
svn_stream_t *stream,
357
* Skip one delta window in svndiff format in the file @a file. and
358
* place it in @a *window, allocating the result in @a pool. The
359
* caller must take responsibility for stripping off the four-byte
360
* 'SVN@<ver@>' header at the beginning of the svndiff document before
361
* reading or skipping the first window, and must provide the version
362
* number (the value of the fourth byte) to each invocation of this
363
* routine with the @a svndiff_version argument. */
364
svn_error_t *svn_txdelta_skip_svndiff_window (apr_file_t *file,
371
/** Traversing tree deltas.
373
* In Subversion, we've got various producers and consumers of tree
376
* In processing a `commit' command:
377
* - The client examines its working copy data, and produces a tree
378
* delta describing the changes to be committed.
379
* - The client networking library consumes that delta, and sends them
380
* across the wire as an equivalent series of WebDAV requests.
381
* - The Apache WebDAV module receives those requests and produces a
382
* tree delta --- hopefully equivalent to the one the client
384
* - The Subversion server module consumes that delta and commits an
385
* appropriate transaction to the filesystem.
387
* In processing an `update' command, the process is reversed:
388
* - The Subversion server module talks to the filesystem and produces
389
* a tree delta describing the changes necessary to bring the
390
* client's working copy up to date.
391
* - The Apache WebDAV module consumes this delta, and assembles a
392
* WebDAV reply representing the appropriate changes.
393
* - The client networking library receives that WebDAV reply, and
394
* produces a tree delta --- hopefully equivalent to the one the
395
* Subversion server produced above.
396
* - The working copy library consumes that delta, and makes the
397
* appropriate changes to the working copy.
399
* The simplest approach would be to represent tree deltas using the
400
* obvious data structure. To do an update, the server would
401
* construct a delta structure, and the working copy library would
402
* apply that structure to the working copy; WebDAV's job would simply
403
* be to get the structure across the net intact.
405
* However, we expect that these deltas will occasionally be too large
406
* to fit in a typical workstation's swap area. For example, in
407
* checking out a 200Mb source tree, the entire source tree is
408
* represented by a single tree delta. So it's important to handle
409
* deltas that are too large to fit in swap all at once.
411
* So instead of representing the tree delta explicitly, we define a
412
* standard way for a consumer to process each piece of a tree delta
413
* as soon as the producer creates it. The @c svn_delta_editor_t
414
* structure is a set of callback functions to be defined by a delta
415
* consumer, and invoked by a delta producer. Each invocation of a
416
* callback function describes a piece of the delta --- a file's
417
* contents changing, something being renamed, etc.
419
* @defgroup svn_delta_tree_deltas tree deltas
423
/** A structure full of callback functions the delta source will invoke
424
* as it produces the delta.
426
* <h3>Function Usage</h3>
428
* Here's how to use these functions to express a tree delta.
430
* The delta consumer implements the callback functions described in
431
* this structure, and the delta producer invokes them. So the
432
* caller (producer) is pushing tree delta data at the callee
435
* At the start of traversal, the consumer provides @a edit_baton, a
436
* baton global to the entire delta edit. If there is a target
437
* revision that needs to be set for this operation, the producer
438
* should called the @c set_target_revision function at this point.
440
* Next, if there are any tree deltas to express, the producer should
441
* pass the @a edit_baton to the @c open_root function, to get a baton
442
* representing root of the tree being edited.
444
* Most of the callbacks work in the obvious way:
452
* Each of these takes a directory baton, indicating the directory
453
* in which the change takes place, and a @a path argument, giving the
454
* path (relative to the root of the edit) of the file,
455
* subdirectory, or directory entry to change. Editors will usually
456
* want to join this relative path with some base stored in the edit
457
* baton (e.g. a URL, a location in the OS filesystem).
459
* Since every call requires a parent directory baton, including
460
* add_directory and open_directory, where do we ever get our
461
* initial directory baton, to get things started? The @c open_root
462
* function returns a baton for the top directory of the change. In
463
* general, the producer needs to invoke the editor's @c open_root
464
* function before it can get anything of interest done.
466
* While @c open_root provides a directory baton for the root of
467
* the tree being changed, the @c add_directory and @c open_directory
468
* callbacks provide batons for other directories. Like the
469
* callbacks above, they take a @a parent_baton and a relative path
470
* @a path, and then return a new baton for the subdirectory being
471
* created / modified --- @a child_baton. The producer can then use
472
* @a child_baton to make further changes in that subdirectory.
474
* So, if we already have subdirectories named `foo' and `foo/bar',
475
* then the producer can create a new file named `foo/bar/baz.c' by
478
* - @c open_root () --- yielding a baton @a root for the top directory
480
* - @c open_directory (@a root, "foo") --- yielding a baton @a f for `foo'
482
* - @c open_directory (@a f, "foo/bar") --- yielding a baton @a b for
485
* - @c add_file (@a b, "foo/bar/baz.c")
487
* When the producer is finished making changes to a directory, it
488
* should call @c close_directory. This lets the consumer do any
489
* necessary cleanup, and free the baton's storage.
491
* The @c add_file and @c open_file callbacks each return a baton
492
* for the file being created or changed. This baton can then be
493
* passed to @c apply_textdelta to change the file's contents, or
494
* @c change_file_prop to change the file's properties. When the
495
* producer is finished making changes to a file, it should call
496
* @c close_file, to let the consumer clean up and free the baton.
498
* The @c add_file and @c add_directory functions each take arguments
499
* @a copyfrom_path and @a copyfrom_revision. If @a copyfrom_path is
500
* non-@c NULL, then @a copyfrom_path and @a copyfrom_revision indicate where
501
* the file or directory should be copied from (to create the file
502
* or directory being added). If @a copyfrom_path is @c NULL, then
503
* @a copyfrom_revision must be @c SVN_INVALID_REVNUM; it is invalid to
504
* pass a mix of valid and invalid copyfrom arguments.
507
* <h3>Function Call Ordering</h3>
509
* There are six restrictions on the order in which the producer
510
* may use the batons:
512
* 1. The producer may call @c open_directory, @c add_directory,
513
* @c open_file, @c add_file at most once on any given directory
514
* entry. @c delete_entry may be called at most once on any given
515
* directory entry and may later be followed by @c add_directory or
516
* @c add_file on the same directory entry. @c delete_entry may
517
* not be called on any directory entry after @c open_directory,
518
* @c add_directory, @c open_file or @c add_file has been called on
519
* that directory entry.
521
* 2. The producer may not close a directory baton until it has
522
* closed all batons for its subdirectories.
524
* 3. When a producer calls @c open_directory or @c add_directory,
525
* it must specify the most recently opened of the currently open
526
* directory batons. Put another way, the producer cannot have
527
* two sibling directory batons open at the same time.
529
* 4. A producer must call @c change_dir_prop on a directory either
530
* before opening any of the directory's subdirs or after closing
531
* them, but not in the middle.
533
* 5. When the producer calls @c open_file or @c add_file, either:
535
* (a) The producer must follow with the changes to the file
536
* (@c change_file_prop and/or @c apply_textdelta, as applicable)
537
* followed by a @c close_file call, before issuing any other file
538
* or directory calls, or
540
* (b) The producer must follow with a @c change_file_prop call if
541
* it is applicable, before issuing any other file or directory
542
* calls; later, after all directory batons including the root
543
* have been closed, the producer must issue @c apply_textdelta
544
* and @c close_file calls.
546
* 6. When the producer calls @c apply_textdelta, it must make all of
547
* the window handler calls (including the @c NULL window at the
548
* end) before issuing any other @c svn_delta_editor_t calls.
550
* So, the producer needs to use directory and file batons as if it
551
* is doing a single depth-first traversal of the tree, with the
552
* exception that the producer may keep file batons open in order to
553
* make apply_textdelta calls at the end.
556
* <h3>Pool Usage</h3>
558
* Many editor functions are invoked multiple times, in a sequence
559
* determined by the editor "driver". The driver is responsible for
560
* creating a pool for use on each iteration of the editor function,
561
* and clearing that pool between each iteration. The driver passes
562
* the appropriate pool on each function invocation.
564
* Based on the requirement of calling the editor functions in a
565
* depth-first style, it is usually customary for the driver to similar
566
* nest the pools. However, this is only a safety feature to ensure
567
* that pools associated with deeper items are always cleared when the
568
* top-level items are also cleared. The interface does not assume, nor
569
* require, any particular organization of the pools passed to these
570
* functions. In fact, if "postfix deltas" are used for files, the file
571
* pools definitely need to live outside the scope of their parent
572
* directories' pools.
574
* Note that close_directory can be called *before* a file in that
575
* directory has been closed. That is, the directory's baton is
576
* closed before the file's baton. The implication is that
577
* @c apply_textdelta and @c close_file should not refer to a parent
578
* directory baton UNLESS the editor has taken precautions to
579
* allocate it in a pool of the appropriate lifetime (the @a dir_pool
580
* passed to @c open_directory and @c add_directory definitely does not
581
* have the proper lifetime). In general, it is recommended to simply
582
* avoid keeping a parent directory baton in a file baton.
587
* At least one implementation of the editor interface is
588
* asynchronous; an error from one operation may be detected some
589
* number of operations later. As a result, an editor driver must not
590
* assume that an error from an editing function resulted from the
591
* particular operation being detected. Moreover, once an editing
592
* function returns an error, the edit is dead; the only further
593
* operation which may be called on the editor is abort_edit.
595
typedef struct svn_delta_editor_t
597
/** Set the target revision for this edit to @a target_revision. This
598
* call, if used, should precede all other editor calls.
600
svn_error_t *(*set_target_revision) (void *edit_baton,
601
svn_revnum_t target_revision,
604
/** Set @a *root_baton to a baton for the top directory of the change.
605
* (This is the top of the subtree being changed, not necessarily
606
* the root of the filesystem.) Like any other directory baton, the
607
* producer should call @c close_directory on @a root_baton when they're
608
* done. And like other @c open_* calls, the @a base_revision here is
609
* the current revision of the directory (before getting bumped up
610
* to the new target revision set with @c set_target_revision).
612
* Allocations for the returned @a root_baton should be performed in
613
* @a dir_pool. It is also typical to (possibly) save this pool for later
614
* usage by @c close_directory.
616
svn_error_t *(*open_root) (void *edit_baton,
617
svn_revnum_t base_revision,
618
apr_pool_t *dir_pool,
622
/** Remove the directory entry named @a path, a child of the directory
623
* represented by @a parent_baton. If @a revision is set, it is used as a
624
* sanity check to ensure that you are removing the revision of @a path
625
* that you really think you are.
627
* All allocations should be performed in @a pool.
629
svn_error_t *(*delete_entry) (const char *path,
630
svn_revnum_t revision,
635
/** We are going to add a new subdirectory named @a path. We will use
636
* the value this callback stores in @a *child_baton as the
637
* @a parent_baton for further changes in the new subdirectory.
639
* If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a
640
* copy), and the origin of the copy may be recorded as
641
* @a copyfrom_path under @a copyfrom_revision.
643
* Allocations for the returned @a child_baton should be performed in
644
* @a dir_pool. It is also typical to (possibly) save this pool for later
645
* usage by @c close_directory.
647
svn_error_t *(*add_directory) (const char *path,
649
const char *copyfrom_path,
650
svn_revnum_t copyfrom_revision,
651
apr_pool_t *dir_pool,
654
/** We are going to make changes in a subdirectory (of the directory
655
* identified by @a parent_baton). The subdirectory is specified by
656
* @a path. The callback must store a value in @a *child_baton that
657
* should be used as the @a parent_baton for subsequent changes in this
658
* subdirectory. If a valid revnum, @a base_revision is the current
659
* revision of the subdirectory.
661
* Allocations for the returned @a child_baton should be performed in
662
* @a dir_pool. It is also typical to (possibly) save this pool for later
663
* usage by @c close_directory.
665
svn_error_t *(*open_directory) (const char *path,
667
svn_revnum_t base_revision,
668
apr_pool_t *dir_pool,
671
/** Change the value of a directory's property.
672
* - @a dir_baton specifies the directory whose property should change.
673
* - @a name is the name of the property to change.
674
* - @a value is the new value of the property, or @c NULL if the property
675
* should be removed altogether.
677
* All allocations should be performed in @a pool.
679
svn_error_t *(*change_dir_prop) (void *dir_baton,
681
const svn_string_t *value,
684
/** We are done processing a subdirectory, whose baton is @a dir_baton
685
* (set by @c add_directory or @c open_directory). We won't be using
686
* the baton any more, so whatever resources it refers to may now be
689
svn_error_t *(*close_directory) (void *dir_baton,
693
/** In the directory represented by @a parent_baton, indicate that
694
* @a path is present as a subdirectory in the edit source, but
695
* cannot be conveyed to the edit consumer (perhaps because of
696
* authorization restrictions).
698
svn_error_t *(*absent_directory) (const char *path,
702
/** We are going to add a new file named @a path. The callback can
703
* store a baton for this new file in @a **file_baton; whatever value
704
* it stores there should be passed through to @c apply_textdelta.
706
* If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a
707
* copy), and the origin of the copy may be recorded as
708
* @a copyfrom_path under @a copyfrom_revision.
710
* Allocations for the returned @a file_baton should be performed in
711
* @a file_pool. It is also typical to save this pool for later usage
712
* by @c apply_textdelta and possibly @c close_file.
714
svn_error_t *(*add_file) (const char *path,
716
const char *copy_path,
717
svn_revnum_t copy_revision,
718
apr_pool_t *file_pool,
721
/** We are going to make change to a file named @a path, which resides
722
* in the directory identified by @a parent_baton.
724
* The callback can store a baton for this new file in @a **file_baton;
725
* whatever value it stores there should be passed through to
726
* apply_textdelta. If a valid revnum, @a base_revision is the
727
* current revision of the file.
729
* Allocations for the returned @a file_baton should be performed in
730
* @a file_pool. It is also typical to save this pool for later usage
731
* by @c apply_textdelta and possibly @c close_file.
733
svn_error_t *(*open_file) (const char *path,
735
svn_revnum_t base_revision,
736
apr_pool_t *file_pool,
739
/** Apply a text delta, yielding the new revision of a file.
741
* @a file_baton indicates the file we're creating or updating, and the
742
* ancestor file on which it is based; it is the baton set by some
743
* prior @c add_file or @c open_file callback.
745
* The callback should set @a *handler to a text delta window
746
* handler; we will then call @a *handler on successive text
747
* delta windows as we receive them. The callback should set
748
* @a *handler_baton to the value we should pass as the @a baton
749
* argument to @a *handler.
751
* @a base_checksum is the hex MD5 digest for the base text against
752
* which the delta is being applied; it is ignored if null, and may
753
* be ignored even if not null. If it is not ignored, it must match
754
* the checksum of the base text against which svndiff data is being
755
* applied; if it does not, apply_textdelta or the @a *handler call
756
* which detects the mismatch will return the error
757
* SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may
758
* still be an error if @a base_checksum is neither null nor the hex
759
* MD5 checksum of the empty string).
761
svn_error_t *(*apply_textdelta) (void *file_baton,
762
const char *base_checksum,
764
svn_txdelta_window_handler_t *handler,
765
void **handler_baton);
767
/** Change the value of a file's property.
768
* - @a file_baton specifies the file whose property should change.
769
* - @a name is the name of the property to change.
770
* - @a value is the new value of the property, or @c NULL if the property
771
* should be removed altogether.
773
* All allocations should be performed in @a pool.
775
svn_error_t *(*change_file_prop) (void *file_baton,
777
const svn_string_t *value,
780
/** We are done processing a file, whose baton is @a file_baton (set by
781
* @c add_file or @c open_file). We won't be using the baton any
782
* more, so whatever resources it refers to may now be freed.
784
* @a text_checksum is the hex MD5 digest for the fulltext that
785
* resulted from a delta application, see @c apply_textdelta. The
786
* checksum is ignored if null. If not null, it is compared to the
787
* checksum of the new fulltext, and the error
788
* SVN_ERR_CHECKSUM_MISMATCH is returned if they do not match. If
789
* there is no new fulltext, @a text_checksum is ignored.
791
svn_error_t *(*close_file) (void *file_baton,
792
const char *text_checksum,
795
/** In the directory represented by @a parent_baton, indicate that
796
* @a path is present as a file in the edit source, but cannot be
797
* conveyed to the edit consumer (perhaps because of authorization
800
svn_error_t *(*absent_file) (const char *path,
804
/** All delta processing is done. Call this, with the @a edit_baton for
807
svn_error_t *(*close_edit) (void *edit_baton,
810
/** The editor-driver has decided to bail out. Allow the editor to
811
* gracefully clean up things if it needs to.
813
svn_error_t *(*abort_edit) (void *edit_baton,
816
} svn_delta_editor_t;
819
/** Return a default delta editor template, allocated in @a pool.
821
* The editor functions in the template do only the most basic
822
* baton-swapping: each editor function that produces a baton does so
823
* by copying its incoming baton into the outgoing baton reference.
825
* This editor is not intended to be useful by itself, but is meant to
826
* be the basis for a useful editor. After getting a default editor,
827
* you substitute in your own implementations for the editor functions
828
* you care about. The ones you don't care about, you don't have to
829
* implement -- you can rely on the template's implementation to
830
* safely do nothing of consequence.
832
svn_delta_editor_t *svn_delta_default_editor (apr_pool_t *pool);
834
/** A text-delta window handler which does nothing.
836
* Editors can return this handler from apply_textdelta if they don't
837
* care about text delta windows.
839
svn_error_t *svn_delta_noop_window_handler (svn_txdelta_window_t *window,
842
/** Return a cancellation editor that wraps @a wrapped_editor.
844
* The @a editor will call @a cancel_func with @a cancel_baton when each of
845
* its functions is called, continuing on to call the corresponding wrapped
846
* function if it returns @c SVN_NO_ERROR.
848
* If @a cancel_func is @c NULL, @a *editor is set to @a wrapped_editor and
849
* @a *edit_baton is set to @a wrapped_baton.
852
svn_delta_get_cancellation_editor (svn_cancel_func_t cancel_func,
854
const svn_delta_editor_t *wrapped_editor,
856
const svn_delta_editor_t **editor,
863
/** Path-based editor drives.
865
* @defgroup svn_delta_path_delta_drivers path-based delta drivers
869
/** Callback function type for svn_delta_path_driver().
871
* The handler of this callback is given the callback baton @a
872
* callback_baton, @a path, and the @a parent_baton which represents
873
* path's parent directory as created by the editor passed to
874
* svn_delta_path_driver().
876
* If @a path represents a directory, the handler must return a @a
877
* *dir_baton for @a path, generated from the same editor (so that the
878
* driver can later close that directory).
880
* If, however, @a path represents a file, the handler should NOT
881
* return any file batons. It can close any opened or added files
882
* immediately, or delay that close until the end of the edit when
883
* svn_delta_path_driver() returns.
885
* Finally, if @a parent_baton is @c NULL, then the root of the edit
886
* is also one of the paths passed to svn_delta_path_driver(). The
887
* handler of this callback must call the editor's open_root()
888
* function and return the top-level root dir baton in @a *dir_baton.
890
typedef svn_error_t *
891
(*svn_delta_path_driver_cb_func_t) (void **dir_baton,
893
void *callback_baton,
898
/** Drive @a editor (with its @a edit_baton) in such a way that
899
* each path in @a paths is traversed in a depth-first fashion. As
900
* each path is hit as part of the editor drive, use @a
901
* callback_func and @a callback_baton to allow the caller to handle
902
* the portion of the editor drive related to that path.
904
* Use @a revision as the revision number passed to intermediate
905
* directory openings.
907
* Use @a pool for all necessary allocations.
910
svn_delta_path_driver (const svn_delta_editor_t *editor,
912
svn_revnum_t revision,
913
apr_array_header_t *paths,
914
svn_delta_path_driver_cb_func_t callback_func,
915
void *callback_baton,
923
#endif /* __cplusplus */
925
#endif /* SVN_DELTA_H */
added
removed
subversion/include/svn_delta.h
