svn_delta.h revision 299742
1221345Sdim/** 2218885Sdim * @copyright 3218885Sdim * ==================================================================== 4218885Sdim * Licensed to the Apache Software Foundation (ASF) under one 5218885Sdim * or more contributor license agreements. See the NOTICE file 6218885Sdim * distributed with this work for additional information 7218885Sdim * regarding copyright ownership. The ASF licenses this file 8218885Sdim * to you under the Apache License, Version 2.0 (the 9218885Sdim * "License"); you may not use this file except in compliance 10218885Sdim * with the License. You may obtain a copy of the License at 11218885Sdim * 12218885Sdim * http://www.apache.org/licenses/LICENSE-2.0 13218885Sdim * 14218885Sdim * Unless required by applicable law or agreed to in writing, 15218885Sdim * software distributed under the License is distributed on an 16218885Sdim * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17249423Sdim * KIND, either express or implied. See the License for the 18249423Sdim * specific language governing permissions and limitations 19218885Sdim * under the License. 20243830Sdim * ==================================================================== 21243830Sdim * @endcopyright 22218885Sdim * 23218885Sdim * @file svn_delta.h 24218885Sdim * @brief Delta-parsing 25218885Sdim */ 26218885Sdim 27218885Sdim/* ==================================================================== */ 28218885Sdim 29218885Sdim 30218885Sdim 31218885Sdim#ifndef SVN_DELTA_H 32218885Sdim#define SVN_DELTA_H 33218885Sdim 34218885Sdim#include <apr.h> 35218885Sdim#include <apr_pools.h> 36218885Sdim#include <apr_hash.h> 37218885Sdim#include <apr_tables.h> 38218885Sdim#include <apr_file_io.h> /* for apr_file_t */ 39218885Sdim 40218885Sdim#include "svn_types.h" 41218885Sdim#include "svn_string.h" 42218885Sdim#include "svn_io.h" 43218885Sdim#include "svn_checksum.h" 44218885Sdim 45218885Sdim#ifdef __cplusplus 46218885Sdimextern "C" { 47218885Sdim#endif /* __cplusplus */ 48218885Sdim 49218885Sdim 50218885Sdim 51218885Sdim/** This compression level effectively disables data compression. 52218885Sdim * However, the data pre-processing costs may still not be zero. 53218885Sdim * 54218885Sdim * @since New in 1.7. 55218885Sdim */ 56218885Sdim#define SVN_DELTA_COMPRESSION_LEVEL_NONE 0 57218885Sdim 58218885Sdim/** This is the maximum compression level we can pass to zlib. 59218885Sdim * 60218885Sdim * @since New in 1.7. 61218885Sdim */ 62218885Sdim#define SVN_DELTA_COMPRESSION_LEVEL_MAX 9 63218885Sdim 64218885Sdim/** This is the default compression level we pass to zlib. It 65218885Sdim * should be between 0 and 9, with higher numbers resulting in 66218885Sdim * better compression rates but slower operation. 67218885Sdim * 68218885Sdim * @since New in 1.7. 69218885Sdim */ 70218885Sdim#define SVN_DELTA_COMPRESSION_LEVEL_DEFAULT 5 71218885Sdim 72218885Sdim/** 73218885Sdim * Get libsvn_delta version information. 74218885Sdim * 75218885Sdim * @since New in 1.1. 76218885Sdim */ 77218885Sdimconst svn_version_t * 78218885Sdimsvn_delta_version(void); 79218885Sdim 80218885Sdim/** 81218885Sdim * @defgroup delta_support Delta generation and handling 82218885Sdim * 83218885Sdim * @{ 84218885Sdim */ 85218885Sdim 86218885Sdim/** Text deltas. 87218885Sdim * 88218885Sdim * A text delta represents the difference between two strings of 89218885Sdim * bytes, the `source' string and the `target' string. Given a source 90218885Sdim * string and a target string, we can compute a text delta; given a 91218885Sdim * source string and a delta, we can reconstruct the target string. 92218885Sdim * However, note that deltas are not reversible: you cannot always 93218885Sdim * reconstruct the source string given the target string and delta. 94218885Sdim * 95218885Sdim * Since text deltas can be very large, the interface here allows us 96218885Sdim * to produce and consume them in pieces. Each piece, represented by 97218885Sdim * an #svn_txdelta_window_t structure, describes how to produce the 98218885Sdim * next section of the target string. 99218885Sdim * 100218885Sdim * To compute a new text delta: 101218885Sdim * 102218885Sdim * - We call svn_txdelta() on the streams we want to compare. That 103218885Sdim * returns us an #svn_txdelta_stream_t object. 104218885Sdim * 105218885Sdim * - We then call svn_txdelta_next_window() on the stream object 106218885Sdim * repeatedly. Each call returns a new #svn_txdelta_window_t 107218885Sdim * object, which describes the next portion of the target string. 108218885Sdim * When svn_txdelta_next_window() returns zero, we are done building 109218885Sdim * the target string. 110218885Sdim * 111218885Sdim * @defgroup svn_delta_txt_delta Text deltas 112218885Sdim * @{ 113218885Sdim */ 114218885Sdim 115218885Sdim/** Action codes for text delta instructions. */ 116218885Sdimenum svn_delta_action { 117218885Sdim /* Note: The svndiff implementation relies on the values assigned in 118218885Sdim * this enumeration matching the instruction encoding values. */ 119218885Sdim 120218885Sdim /** Append the @a length bytes at @a offset in the source view to the 121218885Sdim * target. 122218885Sdim * 123218885Sdim * It must be the case that 0 <= @a offset < @a offset + 124218885Sdim * @a length <= size of source view. 125218885Sdim */ 126218885Sdim svn_txdelta_source, 127218885Sdim 128218885Sdim /** Append the @a length bytes at @a offset in the target view, to the 129218885Sdim * target. 130218885Sdim * 131218885Sdim * It must be the case that 0 <= @a offset < current position in the 132218885Sdim * target view. 133218885Sdim * 134218885Sdim * However! @a offset + @a length may be *beyond* the end of the existing 135218885Sdim * target data. "Where the heck does the text come from, then?" 136218885Sdim * If you start at @a offset, and append @a length bytes one at a time, 137218885Sdim * it'll work out --- you're adding new bytes to the end at the 138218885Sdim * same rate you're reading them from the middle. Thus, if your 139218885Sdim * current target text is "abcdefgh", and you get an #svn_txdelta_target 140218885Sdim * instruction whose @a offset is 6 and whose @a length is 7, 141218885Sdim * the resulting string is "abcdefghghghghg". This trick is actually 142218885Sdim * useful in encoding long runs of consecutive characters, long runs 143218885Sdim * of CR/LF pairs, etc. 144218885Sdim */ 145218885Sdim svn_txdelta_target, 146218885Sdim 147218885Sdim /** Append the @a length bytes at @a offset in the window's @a new string 148218885Sdim * to the target. 149218885Sdim * 150218885Sdim * It must be the case that 0 <= @a offset < @a offset + 151218885Sdim * @a length <= length of @a new. Windows MUST use new data in ascending 152218885Sdim * order with no overlap at the moment; svn_txdelta_to_svndiff() 153218885Sdim * depends on this. 154218885Sdim */ 155218885Sdim svn_txdelta_new 156218885Sdim}; 157218885Sdim 158218885Sdim/** A single text delta instruction. */ 159218885Sdimtypedef struct svn_txdelta_op_t 160218885Sdim{ 161218885Sdim /** Action code of delta instruction */ 162218885Sdim enum svn_delta_action action_code; 163218885Sdim /** Offset of delta, see #svn_delta_action for more details. */ 164218885Sdim apr_size_t offset; 165218885Sdim /** Number of bytes of delta, see #svn_delta_action for more details. */ 166218885Sdim apr_size_t length; 167218885Sdim} svn_txdelta_op_t; 168218885Sdim 169218885Sdim 170218885Sdim/** An #svn_txdelta_window_t object describes how to reconstruct a 171218885Sdim * contiguous section of the target string (the "target view") using a 172218885Sdim * specified contiguous region of the source string (the "source 173218885Sdim * view"). It contains a series of instructions which assemble the 174218885Sdim * new target string text by pulling together substrings from: 175218885Sdim * 176218885Sdim * - the source view, 177218885Sdim * 178218885Sdim * - the previously constructed portion of the target view, 179218885Sdim * 180218885Sdim * - a string of new data contained within the window structure 181218885Sdim * 182218885Sdim * The source view must always slide forward from one window to the 183218885Sdim * next; that is, neither the beginning nor the end of the source view 184218885Sdim * may move to the left as we read from a window stream. This 185218885Sdim * property allows us to apply deltas to non-seekable source streams 186218885Sdim * without making a full copy of the source stream. 187218885Sdim */ 188218885Sdimtypedef struct svn_txdelta_window_t 189218885Sdim{ 190218885Sdim 191218885Sdim /** The offset of the source view for this window. */ 192218885Sdim svn_filesize_t sview_offset; 193218885Sdim 194218885Sdim /** The length of the source view for this window. */ 195218885Sdim apr_size_t sview_len; 196218885Sdim 197218885Sdim /** The length of the target view for this window, i.e. the number of 198218885Sdim * bytes which will be reconstructed by the instruction stream. */ 199218885Sdim apr_size_t tview_len; 200218885Sdim 201218885Sdim /** The number of instructions in this window. */ 202218885Sdim int num_ops; 203218885Sdim 204218885Sdim /** The number of svn_txdelta_source instructions in this window. If 205218885Sdim * this number is 0, we don't need to read the source in order to 206218885Sdim * reconstruct the target view. 207218885Sdim */ 208218885Sdim int src_ops; 209218885Sdim 210218885Sdim /** The instructions for this window. */ 211218885Sdim const svn_txdelta_op_t *ops; 212218885Sdim 213218885Sdim /** New data, for use by any `svn_txdelta_new' instructions. */ 214218885Sdim const svn_string_t *new_data; 215218885Sdim 216218885Sdim} svn_txdelta_window_t; 217218885Sdim 218218885Sdim/** 219218885Sdim * Return a deep copy of @a window, allocated in @a pool. 220218885Sdim * 221218885Sdim * @since New in 1.3. 222218885Sdim */ 223218885Sdimsvn_txdelta_window_t * 224218885Sdimsvn_txdelta_window_dup(const svn_txdelta_window_t *window, 225218885Sdim apr_pool_t *pool); 226218885Sdim 227224145Sdim/** 228218885Sdim * Compose two delta windows, yielding a third, allocated in @a pool. 229218885Sdim * 230218885Sdim * @since New in 1.4 231218885Sdim * 232218885Sdim */ 233218885Sdimsvn_txdelta_window_t * 234218885Sdimsvn_txdelta_compose_windows(const svn_txdelta_window_t *window_A, 235218885Sdim const svn_txdelta_window_t *window_B, 236218885Sdim apr_pool_t *pool); 237218885Sdim 238218885Sdim/** 239218885Sdim * Apply the instructions from @a window to a source view @a sbuf to 240218885Sdim * produce a target view @a tbuf. 241218885Sdim * 242218885Sdim * @a sbuf is assumed to have @a window->sview_len bytes of data and 243218885Sdim * @a tbuf is assumed to have room for @a tlen bytes of output. @a 244218885Sdim * tlen may be more than @a window->tview_len, so return the actual 245218885Sdim * number of bytes written. @a sbuf is not touched and may be NULL if 246218885Sdim * @a window contains no source-copy operations. This is purely a 247218885Sdim * memory operation; nothing can go wrong as long as we have a valid 248218885Sdim * window. 249218885Sdim * 250218885Sdim * @since New in 1.4 251218885Sdim * 252218885Sdim * @since Since 1.9, @a tbuf may be NULL if @a *tlen is 0. 253218885Sdim */ 254218885Sdimvoid 255218885Sdimsvn_txdelta_apply_instructions(svn_txdelta_window_t *window, 256218885Sdim const char *sbuf, char *tbuf, 257218885Sdim apr_size_t *tlen); 258218885Sdim 259218885Sdim/** A typedef for functions that consume a series of delta windows, for 260218885Sdim * use in caller-pushes interfaces. Such functions will typically 261218885Sdim * apply the delta windows to produce some file, or save the windows 262218885Sdim * somewhere. At the end of the delta window stream, you must call 263218885Sdim * this function passing zero for the @a window argument. 264218885Sdim */ 265218885Sdimtypedef svn_error_t *(*svn_txdelta_window_handler_t)( 266218885Sdim svn_txdelta_window_t *window, void *baton); 267218885Sdim 268218885Sdim 269218885Sdim/** This function will generate delta windows that turn @a source into 270218885Sdim * @a target, and pushing these windows into the @a handler window handler 271218885Sdim * callback (passing @a handler_baton to each invocation). 272218885Sdim * 273218885Sdim * If @a checksum is not NULL, then a checksum (of kind @a checksum_kind) 274218885Sdim * will be computed for the target stream, and placed into *checksum. 275218885Sdim * 276218885Sdim * If @a cancel_func is not NULL, then it should refer to a cancellation 277218885Sdim * function (along with @a cancel_baton). 278218885Sdim * 279218885Sdim * Results (the checksum) will be allocated from @a result_pool, and all 280218885Sdim * temporary allocations will be performed in @a scratch_pool. 281218885Sdim * 282218885Sdim * Note: this function replaces the combination of svn_txdelta() and 283218885Sdim * svn_txdelta_send_txstream(). 284218885Sdim * 285218885Sdim * @since New in 1.6. 286218885Sdim */ 287218885Sdimsvn_error_t * 288218885Sdimsvn_txdelta_run(svn_stream_t *source, 289218885Sdim svn_stream_t *target, 290218885Sdim svn_txdelta_window_handler_t handler, 291218885Sdim void *handler_baton, 292218885Sdim svn_checksum_kind_t checksum_kind, 293218885Sdim svn_checksum_t **checksum, 294218885Sdim svn_cancel_func_t cancel_func, 295218885Sdim void *cancel_baton, 296218885Sdim apr_pool_t *result_pool, 297218885Sdim apr_pool_t *scratch_pool); 298218885Sdim 299218885Sdim 300218885Sdim/** A delta stream --- this is the hat from which we pull a series of 301218885Sdim * svn_txdelta_window_t objects, which, taken in order, describe the 302218885Sdim * entire target string. This type is defined within libsvn_delta, and 303218885Sdim * opaque outside that library. 304218885Sdim */ 305218885Sdimtypedef struct svn_txdelta_stream_t svn_txdelta_stream_t; 306218885Sdim 307218885Sdim 308218885Sdim/** A typedef for a function that will set @a *window to the next 309218885Sdim * window from a #svn_txdelta_stream_t object. If there are no more 310218885Sdim * delta windows, NULL will be used. The returned window, if any, 311218885Sdim * will be allocated in @a pool. @a baton is the baton specified 312218885Sdim * when the stream was created. 313218885Sdim * 314218885Sdim * @since New in 1.4. 315218885Sdim */ 316218885Sdimtypedef svn_error_t * 317218885Sdim(*svn_txdelta_next_window_fn_t)(svn_txdelta_window_t **window, 318218885Sdim void *baton, 319218885Sdim apr_pool_t *pool); 320218885Sdim 321218885Sdim/** A typedef for a function that will return the md5 checksum of the 322218885Sdim * fulltext deltified by a #svn_txdelta_stream_t object. Will 323218885Sdim * return NULL if the final null window hasn't yet been returned by 324218885Sdim * the stream. The returned value will be allocated in the same pool 325218885Sdim * as the stream. @a baton is the baton specified when the stream was 326218885Sdim * created. 327218885Sdim * 328218885Sdim * @since New in 1.4. 329218885Sdim */ 330218885Sdimtypedef const unsigned char * 331218885Sdim(*svn_txdelta_md5_digest_fn_t)(void *baton); 332218885Sdim 333218885Sdim/** Create and return a generic text delta stream with @a baton, @a 334218885Sdim * next_window and @a md5_digest. Allocate the new stream in @a 335218885Sdim * pool. 336218885Sdim * 337218885Sdim * @since New in 1.4. 338218885Sdim */ 339218885Sdimsvn_txdelta_stream_t * 340218885Sdimsvn_txdelta_stream_create(void *baton, 341218885Sdim svn_txdelta_next_window_fn_t next_window, 342218885Sdim svn_txdelta_md5_digest_fn_t md5_digest, 343218885Sdim apr_pool_t *pool); 344218885Sdim 345218885Sdim/** Set @a *window to a pointer to the next window from the delta stream 346218885Sdim * @a stream. When we have completely reconstructed the target string, 347218885Sdim * set @a *window to zero. 348218885Sdim * 349218885Sdim * The window will be allocated in @a pool. 350218885Sdim */ 351218885Sdimsvn_error_t * 352218885Sdimsvn_txdelta_next_window(svn_txdelta_window_t **window, 353218885Sdim svn_txdelta_stream_t *stream, 354218885Sdim apr_pool_t *pool); 355218885Sdim 356218885Sdim 357218885Sdim/** Return the md5 digest for the complete fulltext deltified by 358218885Sdim * @a stream, or @c NULL if @a stream has not yet returned its final 359218885Sdim * @c NULL window. The digest is allocated in the same memory as @a 360218885Sdim * STREAM. 361218885Sdim */ 362218885Sdimconst unsigned char * 363218885Sdimsvn_txdelta_md5_digest(svn_txdelta_stream_t *stream); 364218885Sdim 365218885Sdim/** Set @a *stream to a pointer to a delta stream that will turn the byte 366218885Sdim * string from @a source into the byte stream from @a target. 367218885Sdim * 368218885Sdim * @a source and @a target are both readable generic streams. When we call 369218885Sdim * svn_txdelta_next_window() on @a *stream, it will read from @a source and 370218885Sdim * @a target to gather as much data as it needs. If @a calculate_checksum 371218885Sdim * is set, you may call svn_txdelta_md5_digest() to get an MD5 checksum 372218885Sdim * for @a target. 373218885Sdim * 374218885Sdim * Do any necessary allocation in a sub-pool of @a pool. 375218885Sdim * 376218885Sdim * @since New in 1.8. 377218885Sdim */ 378218885Sdimvoid 379218885Sdimsvn_txdelta2(svn_txdelta_stream_t **stream, 380218885Sdim svn_stream_t *source, 381218885Sdim svn_stream_t *target, 382218885Sdim svn_boolean_t calculate_checksum, 383218885Sdim apr_pool_t *pool); 384218885Sdim 385218885Sdim/** Similar to svn_txdelta2 but always calculating the target checksum. 386218885Sdim * 387218885Sdim * @deprecated Provided for backward compatibility with the 1.7 API. 388218885Sdim */ 389218885SdimSVN_DEPRECATED 390218885Sdimvoid 391218885Sdimsvn_txdelta(svn_txdelta_stream_t **stream, 392218885Sdim svn_stream_t *source, 393218885Sdim svn_stream_t *target, 394218885Sdim apr_pool_t *pool); 395218885Sdim 396218885Sdim 397218885Sdim/** 398218885Sdim * Return a writable stream which, when fed target data, will send 399218885Sdim * delta windows to @a handler/@a handler_baton which transform the 400218885Sdim * data in @a source to the target data. As usual, the window handler 401218885Sdim * will receive a NULL window to signify the end of the window stream. 402218885Sdim * The stream handler functions will read data from @a source as 403218885Sdim * necessary. 404218885Sdim * 405218885Sdim * @since New in 1.1. 406218885Sdim */ 407218885Sdimsvn_stream_t * 408218885Sdimsvn_txdelta_target_push(svn_txdelta_window_handler_t handler, 409218885Sdim void *handler_baton, 410218885Sdim svn_stream_t *source, 411218885Sdim apr_pool_t *pool); 412218885Sdim 413218885Sdim 414218885Sdim/** Send the contents of @a string to window-handler @a handler/@a baton. 415218885Sdim * This is effectively a 'copy' operation, resulting in delta windows that 416218885Sdim * make the target equivalent to the value of @a string. 417218885Sdim * 418218885Sdim * All temporary allocation is performed in @a pool. 419218885Sdim */ 420218885Sdimsvn_error_t * 421218885Sdimsvn_txdelta_send_string(const svn_string_t *string, 422218885Sdim svn_txdelta_window_handler_t handler, 423218885Sdim void *handler_baton, 424218885Sdim apr_pool_t *pool); 425218885Sdim 426218885Sdim/** Send the contents of @a stream to window-handler @a handler/@a baton. 427218885Sdim * This is effectively a 'copy' operation, resulting in delta windows that 428218885Sdim * make the target equivalent to the stream. 429218885Sdim * 430218885Sdim * If @a digest is non-NULL, populate it with the md5 checksum for the 431218885Sdim * fulltext that was deltified (@a digest must be at least 432218885Sdim * @c APR_MD5_DIGESTSIZE bytes long). 433218885Sdim * 434218885Sdim * All temporary allocation is performed in @a pool. 435218885Sdim */ 436218885Sdimsvn_error_t * 437218885Sdimsvn_txdelta_send_stream(svn_stream_t *stream, 438218885Sdim svn_txdelta_window_handler_t handler, 439218885Sdim void *handler_baton, 440218885Sdim unsigned char *digest, 441218885Sdim apr_pool_t *pool); 442218885Sdim 443218885Sdim/** Send the contents of @a txstream to window-handler @a handler/@a baton. 444218885Sdim * Windows will be extracted from the stream and delivered to the handler. 445218885Sdim * 446218885Sdim * All temporary allocation is performed in @a pool. 447218885Sdim */ 448218885Sdimsvn_error_t * 449218885Sdimsvn_txdelta_send_txstream(svn_txdelta_stream_t *txstream, 450218885Sdim svn_txdelta_window_handler_t handler, 451218885Sdim void *handler_baton, 452218885Sdim apr_pool_t *pool); 453218885Sdim 454218885Sdim 455218885Sdim/** Send the @a contents of length @a len as a txdelta against an empty 456218885Sdim * source directly to window-handler @a handler/@a handler_baton. 457218885Sdim * 458218885Sdim * All temporary allocation is performed in @a pool. 459218885Sdim * 460218885Sdim * @since New in 1.8. 461218885Sdim */ 462218885Sdimsvn_error_t * 463218885Sdimsvn_txdelta_send_contents(const unsigned char *contents, 464218885Sdim apr_size_t len, 465218885Sdim svn_txdelta_window_handler_t handler, 466218885Sdim void *handler_baton, 467218885Sdim apr_pool_t *pool); 468218885Sdim 469218885Sdim/** Prepare to apply a text delta. @a source is a readable generic stream 470218885Sdim * yielding the source data, @a target is a writable generic stream to 471218885Sdim * write target data to, and allocation takes place in a sub-pool of 472218885Sdim * @a pool. On return, @a *handler is set to a window handler function and 473218885Sdim * @a *handler_baton is set to the value to pass as the @a baton argument to 474218885Sdim * @a *handler. 475218885Sdim * 476218885Sdim * If @a result_digest is non-NULL, it points to APR_MD5_DIGESTSIZE bytes 477218885Sdim * of storage, and the final call to @a handler populates it with the 478218885Sdim * MD5 digest of the resulting fulltext. 479218885Sdim * 480218885Sdim * If @a error_info is non-NULL, it is inserted parenthetically into 481218885Sdim * the error string for any error returned by svn_txdelta_apply() or 482218885Sdim * @a *handler. (It is normally used to provide path information, 483218885Sdim * since there's nothing else in the delta application's context to 484218885Sdim * supply a path for error messages.) 485218885Sdim * 486218885Sdim * @note To avoid lifetime issues, @a error_info is copied into 487218885Sdim * @a pool or a subpool thereof. 488218885Sdim */ 489218885Sdimvoid 490218885Sdimsvn_txdelta_apply(svn_stream_t *source, 491218885Sdim svn_stream_t *target, 492218885Sdim unsigned char *result_digest, 493218885Sdim const char *error_info, 494218885Sdim apr_pool_t *pool, 495218885Sdim svn_txdelta_window_handler_t *handler, 496218885Sdim void **handler_baton); 497218885Sdim 498218885Sdim 499218885Sdim 500218885Sdim 501218885Sdim/*** Producing and consuming svndiff-format text deltas. ***/ 502218885Sdim 503218885Sdim/** Prepare to produce an svndiff-format diff from text delta windows. 504218885Sdim * @a output is a writable generic stream to write the svndiff data to. 505218885Sdim * Allocation takes place in a sub-pool of @a pool. On return, @a *handler 506218885Sdim * is set to a window handler function and @a *handler_baton is set to 507218885Sdim * the value to pass as the @a baton argument to @a *handler. The svndiff 508218885Sdim * version is @a svndiff_version. @a compression_level is the zlib 509218885Sdim * compression level from 0 (no compression) and 9 (maximum compression). 510218885Sdim * 511218885Sdim * @since New in 1.7. 512218885Sdim */ 513218885Sdimvoid 514218885Sdimsvn_txdelta_to_svndiff3(svn_txdelta_window_handler_t *handler, 515218885Sdim void **handler_baton, 516218885Sdim svn_stream_t *output, 517218885Sdim int svndiff_version, 518218885Sdim int compression_level, 519218885Sdim apr_pool_t *pool); 520218885Sdim 521218885Sdim/** Similar to svn_txdelta_to_svndiff3(), but always using the SVN default 522218885Sdim * compression level (#SVN_DELTA_COMPRESSION_LEVEL_DEFAULT). 523218885Sdim * 524218885Sdim * @since New in 1.4. 525218885Sdim * @deprecated Provided for backward compatibility with the 1.6 API. 526218885Sdim */ 527218885SdimSVN_DEPRECATED 528218885Sdimvoid 529218885Sdimsvn_txdelta_to_svndiff2(svn_txdelta_window_handler_t *handler, 530218885Sdim void **handler_baton, 531218885Sdim svn_stream_t *output, 532218885Sdim int svndiff_version, 533218885Sdim apr_pool_t *pool); 534218885Sdim 535218885Sdim/** Similar to svn_txdelta_to_svndiff2, but always using svndiff 536218885Sdim * version 0. 537218885Sdim * 538218885Sdim * @deprecated Provided for backward compatibility with the 1.3 API. 539218885Sdim */ 540218885SdimSVN_DEPRECATED 541218885Sdimvoid 542218885Sdimsvn_txdelta_to_svndiff(svn_stream_t *output, 543218885Sdim apr_pool_t *pool, 544218885Sdim svn_txdelta_window_handler_t *handler, 545218885Sdim void **handler_baton); 546218885Sdim 547218885Sdim/** Return a writable generic stream which will parse svndiff-format 548218885Sdim * data into a text delta, invoking @a handler with @a handler_baton 549218885Sdim * whenever a new window is ready. 550218885Sdim * 551218885Sdim * When the caller closes this stream, this will signal completion to 552218885Sdim * the window handler by invoking @a handler once more, passing zero for 553218885Sdim * the @c window argument. 554218885Sdim * 555218885Sdim * If @a error_on_early_close is @c TRUE, then attempt to avoid 556218885Sdim * signaling completion to the window handler if the delta was 557218885Sdim * incomplete. Specifically, attempting to close the stream will be 558218885Sdim * successful only if the data written to the stream consisted of one or 559218885Sdim * more complete windows of svndiff data and no extra bytes. Otherwise, 560218885Sdim * closing the stream will not signal completion to the window handler, 561218885Sdim * and will return a #SVN_ERR_SVNDIFF_UNEXPECTED_END error. Note that if 562218885Sdim * no data at all was written, the delta is considered incomplete. 563218885Sdim * 564218885Sdim * If @a error_on_early_close is @c FALSE, closing the stream will 565218885Sdim * signal completion to the window handler, regardless of how much data 566218885Sdim * was written, and discard any pending incomplete data. 567218885Sdim * 568218885Sdim * Allocate the stream in @a pool. 569218885Sdim */ 570218885Sdimsvn_stream_t * 571218885Sdimsvn_txdelta_parse_svndiff(svn_txdelta_window_handler_t handler, 572218885Sdim void *handler_baton, 573218885Sdim svn_boolean_t error_on_early_close, 574218885Sdim apr_pool_t *pool); 575218885Sdim 576218885Sdim/** 577218885Sdim * Read and parse one delta window in svndiff format from the 578218885Sdim * readable stream @a stream and place it in @a *window, allocating 579218885Sdim * the result in @a pool. The caller must take responsibility for 580218885Sdim * stripping off the four-byte 'SVN@<ver@>' header at the beginning of 581218885Sdim * the svndiff document before reading the first window, and must 582218885Sdim * provide the version number (the value of the fourth byte) to each 583218885Sdim * invocation of this routine with the @a svndiff_version argument. 584218885Sdim * 585218885Sdim * @since New in 1.1. 586218885Sdim */ 587218885Sdimsvn_error_t * 588218885Sdimsvn_txdelta_read_svndiff_window(svn_txdelta_window_t **window, 589218885Sdim svn_stream_t *stream, 590218885Sdim int svndiff_version, 591218885Sdim apr_pool_t *pool); 592218885Sdim 593218885Sdim/** 594218885Sdim * Read and skip one delta window in svndiff format from the 595218885Sdim * file @a file. @a pool is used for temporary allocations. The 596218885Sdim * caller must take responsibility for stripping off the four-byte 597218885Sdim * 'SVN@<ver@>' header at the beginning of the svndiff document before 598218885Sdim * reading or skipping the first window, and must provide the version 599218885Sdim * number (the value of the fourth byte) to each invocation of this 600218885Sdim * routine with the @a svndiff_version argument. 601218885Sdim * 602218885Sdim * @since New in 1.1. 603218885Sdim */ 604218885Sdimsvn_error_t * 605218885Sdimsvn_txdelta_skip_svndiff_window(apr_file_t *file, 606218885Sdim int svndiff_version, 607218885Sdim apr_pool_t *pool); 608218885Sdim 609218885Sdim/** @} */ 610218885Sdim 611218885Sdim 612218885Sdim/** Traversing tree deltas. 613218885Sdim * 614218885Sdim * In Subversion, we've got various producers and consumers of tree 615218885Sdim * deltas. 616218885Sdim * 617218885Sdim * In processing a `commit' command: 618218885Sdim * - The client examines its working copy data, and produces a tree 619218885Sdim * delta describing the changes to be committed. 620218885Sdim * - The client networking library consumes that delta, and sends them 621218885Sdim * across the wire as an equivalent series of network requests (for 622218885Sdim * example, to svnserve as an ra_svn protocol stream, or to an 623218885Sdim * Apache httpd server as WebDAV commands) 624218885Sdim * - The server receives those requests and produces a tree delta --- 625218885Sdim * hopefully equivalent to the one the client produced above. 626218885Sdim * - The Subversion server module consumes that delta and commits an 627218885Sdim * appropriate transaction to the filesystem. 628218885Sdim * 629218885Sdim * In processing an `update' command, the process is reversed: 630218885Sdim * - The Subversion server module talks to the filesystem and produces 631218885Sdim * a tree delta describing the changes necessary to bring the 632218885Sdim * client's working copy up to date. 633218885Sdim * - The server consumes this delta, and assembles a reply 634243830Sdim * representing the appropriate changes. 635243830Sdim * - The client networking library receives that reply, and produces a 636218885Sdim * tree delta --- hopefully equivalent to the one the Subversion 637218885Sdim * server produced above. 638218885Sdim * - The working copy library consumes that delta, and makes the 639218885Sdim * appropriate changes to the working copy. 640218885Sdim * 641218885Sdim * The simplest approach would be to represent tree deltas using the 642218885Sdim * obvious data structure. To do an update, the server would 643218885Sdim * construct a delta structure, and the working copy library would 644218885Sdim * apply that structure to the working copy; the network layer's job 645218885Sdim * would simply be to get the structure across the net intact. 646218885Sdim * 647218885Sdim * However, we expect that these deltas will occasionally be too large 648218885Sdim * to fit in a typical workstation's swap area. For example, in 649218885Sdim * checking out a 200Mb source tree, the entire source tree is 650218885Sdim * represented by a single tree delta. So it's important to handle 651218885Sdim * deltas that are too large to fit in swap all at once. 652218885Sdim * 653218885Sdim * So instead of representing the tree delta explicitly, we define a 654218885Sdim * standard way for a consumer to process each piece of a tree delta 655218885Sdim * as soon as the producer creates it. The #svn_delta_editor_t 656243830Sdim * structure is a set of callback functions to be defined by a delta 657218885Sdim * consumer, and invoked by a delta producer. Each invocation of a 658218885Sdim * callback function describes a piece of the delta --- a file's 659218885Sdim * contents changing, something being renamed, etc. 660218885Sdim * 661218885Sdim * @defgroup svn_delta_tree_deltas Tree deltas 662218885Sdim * @{ 663224145Sdim */ 664218885Sdim 665218885Sdim/** A structure full of callback functions the delta source will invoke 666218885Sdim * as it produces the delta. 667218885Sdim * 668218885Sdim * @note Don't try to allocate one of these yourself. Instead, always 669218885Sdim * use svn_delta_default_editor() or some other constructor, to ensure 670218885Sdim * that unused slots are filled in with no-op functions. 671218885Sdim * 672218885Sdim * <h3>Function Usage</h3> 673218885Sdim * 674218885Sdim * Here's how to use these functions to express a tree delta. 675218885Sdim * 676218885Sdim * The delta consumer implements the callback functions described in 677218885Sdim * this structure, and the delta producer invokes them. So the 678218885Sdim * caller (producer) is pushing tree delta data at the callee 679218885Sdim * (consumer). 680218885Sdim * 681218885Sdim * At the start of traversal, the consumer provides @a edit_baton, a 682218885Sdim * baton global to the entire delta edit. If there is a target 683218885Sdim * revision that needs to be set for this operation, the producer 684218885Sdim * should call the @c set_target_revision function at this point. 685218885Sdim * 686218885Sdim * Next, if there are any tree deltas to express, the producer should 687218885Sdim * pass the @a edit_baton to the @c open_root function, to get a baton 688218885Sdim * representing root of the tree being edited. 689218885Sdim * 690218885Sdim * Most of the callbacks work in the obvious way: 691218885Sdim * 692218885Sdim * @c delete_entry 693218885Sdim * @c add_file 694218885Sdim * @c add_directory 695218885Sdim * @c open_file 696218885Sdim * @c open_directory 697218885Sdim * 698218885Sdim * Each of these takes a directory baton, indicating the directory 699218885Sdim * in which the change takes place, and a @a path argument, giving the 700218885Sdim * path of the file, subdirectory, or directory entry to change. 701218885Sdim * 702218885Sdim * The @a path argument to each of the callbacks is relative to the 703218885Sdim * root of the edit. Editors will usually want to join this relative 704218885Sdim * path with some base stored in the edit baton (e.g. a URL, or a 705218885Sdim * location in the OS filesystem). 706218885Sdim * 707218885Sdim * Since every call requires a parent directory baton, including 708218885Sdim * @c add_directory and @c open_directory, where do we ever get our 709218885Sdim * initial directory baton, to get things started? The @c open_root 710218885Sdim * function returns a baton for the top directory of the change. In 711218885Sdim * general, the producer needs to invoke the editor's @c open_root 712218885Sdim * function before it can get anything of interest done. 713218885Sdim * 714218885Sdim * While @c open_root provides a directory baton for the root of 715218885Sdim * the tree being changed, the @c add_directory and @c open_directory 716218885Sdim * callbacks provide batons for other directories. Like the 717218885Sdim * callbacks above, they take a @a parent_baton and a relative path 718218885Sdim * @a path, and then return a new baton for the subdirectory being 719218885Sdim * created / modified --- @a child_baton. The producer can then use 720218885Sdim * @a child_baton to make further changes in that subdirectory. 721218885Sdim * 722218885Sdim * So, if we already have subdirectories named `foo' and `foo/bar', 723218885Sdim * then the producer can create a new file named `foo/bar/baz.c' by 724218885Sdim * calling: 725218885Sdim * 726218885Sdim * - @c open_root () --- yielding a baton @a root for the top directory 727218885Sdim * 728218885Sdim * - @c open_directory (@a root, "foo") --- yielding a baton @a f for `foo' 729218885Sdim * 730218885Sdim * - @c open_directory (@a f, "foo/bar") --- yielding a baton @a b for 731218885Sdim * `foo/bar' 732234353Sdim * 733234353Sdim * - @c add_file (@a b, "foo/bar/baz.c") 734234353Sdim * 735234353Sdim * When the producer is finished making changes to a directory, it 736218885Sdim * should call @c close_directory. This lets the consumer do any 737218885Sdim * necessary cleanup, and free the baton's storage. 738218885Sdim * 739218885Sdim * The @c add_file and @c open_file callbacks each return a baton 740218885Sdim * for the file being created or changed. This baton can then be 741218885Sdim * passed to @c apply_textdelta to change the file's contents, or 742218885Sdim * @c change_file_prop to change the file's properties. When the 743218885Sdim * producer is finished making changes to a file, it should call 744218885Sdim * @c close_file, to let the consumer clean up and free the baton. 745218885Sdim * 746218885Sdim * The @c add_file and @c add_directory functions each take arguments 747218885Sdim * @a copyfrom_path and @a copyfrom_revision. If @a copyfrom_path is 748218885Sdim * non-@c NULL, then @a copyfrom_path and @a copyfrom_revision indicate where 749218885Sdim * the file or directory should be copied from (to create the file 750218885Sdim * or directory being added). In that case, @a copyfrom_path must be 751218885Sdim * either a path relative to the root of the edit, or a URI from the 752218885Sdim * repository being edited. If @a copyfrom_path is @c NULL, then @a 753218885Sdim * copyfrom_revision must be #SVN_INVALID_REVNUM; it is invalid to 754218885Sdim * pass a mix of valid and invalid copyfrom arguments. 755218885Sdim * 756218885Sdim * 757218885Sdim * <h3>Function Call Ordering</h3> 758218885Sdim * 759218885Sdim * There are six restrictions on the order in which the producer 760218885Sdim * may use the batons: 761218885Sdim * 762218885Sdim * 1. The producer may call @c open_directory, @c add_directory, 763218885Sdim * @c open_file, @c add_file at most once on any given directory 764218885Sdim * entry. @c delete_entry may be called at most once on any given 765218885Sdim * directory entry and may later be followed by @c add_directory or 766218885Sdim * @c add_file on the same directory entry. @c delete_entry may 767218885Sdim * not be called on any directory entry after @c open_directory, 768218885Sdim * @c add_directory, @c open_file or @c add_file has been called on 769218885Sdim * that directory entry. 770218885Sdim * 771218885Sdim * 2. The producer may not close a directory baton until it has 772218885Sdim * closed all batons for its subdirectories. 773218885Sdim * 774218885Sdim * 3. When a producer calls @c open_directory or @c add_directory, 775218885Sdim * it must specify the most recently opened of the currently open 776218885Sdim * directory batons. Put another way, the producer cannot have 777218885Sdim * two sibling directory batons open at the same time. 778218885Sdim * 779218885Sdim * 4. A producer must call @c change_dir_prop on a directory either 780218885Sdim * before opening any of the directory's subdirs or after closing 781218885Sdim * them, but not in the middle. 782218885Sdim * 783218885Sdim * 5. When the producer calls @c open_file or @c add_file, either: 784218885Sdim * 785218885Sdim * (a) The producer must follow with any changes to the file 786218885Sdim * (@c change_file_prop and/or @c apply_textdelta, as applicable), 787218885Sdim * followed by a @c close_file call, before issuing any other file 788218885Sdim * or directory calls, or 789218885Sdim * 790218885Sdim * (b) The producer must follow with a @c change_file_prop call if 791218885Sdim * it is applicable, before issuing any other file or directory 792218885Sdim * calls; later, after all directory batons including the root 793218885Sdim * have been closed, the producer must issue @c apply_textdelta 794218885Sdim * and @c close_file calls. 795218885Sdim * 796218885Sdim * 6. When the producer calls @c apply_textdelta, it must make all of 797218885Sdim * the window handler calls (including the @c NULL window at the 798218885Sdim * end) before issuing any other #svn_delta_editor_t calls. 799218885Sdim * 800218885Sdim * So, the producer needs to use directory and file batons as if it 801218885Sdim * is doing a single depth-first traversal of the tree, with the 802218885Sdim * exception that the producer may keep file batons open in order to 803218885Sdim * make @c apply_textdelta calls at the end. 804218885Sdim * 805218885Sdim * 806218885Sdim * <h3>Pool Usage</h3> 807218885Sdim * 808218885Sdim * Many editor functions are invoked multiple times, in a sequence 809218885Sdim * determined by the editor "driver". The driver is responsible for 810218885Sdim * creating a pool for use on each iteration of the editor function, 811218885Sdim * and clearing that pool between each iteration. The driver passes 812218885Sdim * the appropriate pool on each function invocation. 813218885Sdim * 814218885Sdim * Based on the requirement of calling the editor functions in a 815218885Sdim * depth-first style, it is usually customary for the driver to similarly 816218885Sdim * nest the pools. However, this is only a safety feature to ensure 817218885Sdim * that pools associated with deeper items are always cleared when the 818218885Sdim * top-level items are also cleared. The interface does not assume, nor 819218885Sdim * require, any particular organization of the pools passed to these 820218885Sdim * functions. In fact, if "postfix deltas" are used for files, the file 821218885Sdim * pools definitely need to live outside the scope of their parent 822218885Sdim * directories' pools. 823218885Sdim * 824218885Sdim * Note that close_directory can be called *before* a file in that 825218885Sdim * directory has been closed. That is, the directory's baton is 826218885Sdim * closed before the file's baton. The implication is that 827218885Sdim * @c apply_textdelta and @c close_file should not refer to a parent 828218885Sdim * directory baton UNLESS the editor has taken precautions to 829218885Sdim * allocate it in a pool of the appropriate lifetime (the @a dir_pool 830218885Sdim * passed to @c open_directory and @c add_directory definitely does not 831218885Sdim * have the proper lifetime). In general, it is recommended to simply 832218885Sdim * avoid keeping a parent directory baton in a file baton. 833218885Sdim * 834218885Sdim * 835218885Sdim * <h3>Errors</h3> 836218885Sdim * 837218885Sdim * At least one implementation of the editor interface is 838218885Sdim * asynchronous; an error from one operation may be detected some 839218885Sdim * number of operations later. As a result, an editor driver must not 840218885Sdim * assume that an error from an editing function resulted from the 841218885Sdim * particular operation being detected. Moreover, once an editing 842218885Sdim * function (including @c close_edit) returns an error, the edit is 843218885Sdim * dead; the only further operation which may be called on the editor 844218885Sdim * is @c abort_edit. 845218885Sdim */ 846218885Sdimtypedef struct svn_delta_editor_t 847218885Sdim{ 848218885Sdim /** Set the target revision for this edit to @a target_revision. This 849218885Sdim * call, if used, should precede all other editor calls. 850218885Sdim * 851218885Sdim * @note This is typically used only for server->client update-type 852218885Sdim * operations. It doesn't really make much sense for commit-type 853218885Sdim * operations, because the revision of a commit isn't known until 854218885Sdim * the commit is finalized. 855218885Sdim * 856218885Sdim * Any temporary allocations may be performed in @a scratch_pool. 857218885Sdim */ 858218885Sdim svn_error_t *(*set_target_revision)(void *edit_baton, 859218885Sdim svn_revnum_t target_revision, 860218885Sdim apr_pool_t *scratch_pool); 861218885Sdim 862218885Sdim /** Set @a *root_baton to a baton for the top directory of the change. 863218885Sdim * (This is the top of the subtree being changed, not necessarily 864218885Sdim * the root of the filesystem.) As with any other directory baton, the 865218885Sdim * producer should call @c close_directory on @a root_baton when done. 866218885Sdim * And as with other @c open_* calls, the @a base_revision here is the 867218885Sdim * current revision of the directory (before getting bumped up to the 868218885Sdim * new target revision set with @c set_target_revision). 869218885Sdim * 870218885Sdim * Allocations for the returned @a root_baton should be performed in 871218885Sdim * @a result_pool. It is also typical to (possibly) save this pool for 872218885Sdim * later usage by @c close_directory. 873218885Sdim */ 874218885Sdim svn_error_t *(*open_root)(void *edit_baton, 875218885Sdim svn_revnum_t base_revision, 876218885Sdim apr_pool_t *result_pool, 877218885Sdim void **root_baton); 878218885Sdim 879218885Sdim 880218885Sdim /** Remove the directory entry at @a path, a child of the directory 881218885Sdim * represented by @a parent_baton. If @a revision is a valid 882218885Sdim * revision number, it is used as a sanity check to ensure that you 883218885Sdim * are really removing the revision of @a path that you think you are. 884218885Sdim * 885218885Sdim * Any temporary allocations may be performed in @a scratch_pool. 886218885Sdim * 887218885Sdim * @note The @a revision parameter is typically used only for 888218885Sdim * client->server commit-type operations, allowing the server to 889218885Sdim * verify that it is deleting what the client thinks it should be 890218885Sdim * deleting. It only really makes sense in the opposite direction 891218885Sdim * (during server->client update-type operations) when the trees 892218885Sdim * whose delta is being described are ancestrally related (that is, 893218885Sdim * one tree is an ancestor of the other). 894218885Sdim */ 895218885Sdim svn_error_t *(*delete_entry)(const char *path, 896218885Sdim svn_revnum_t revision, 897218885Sdim void *parent_baton, 898218885Sdim apr_pool_t *scratch_pool); 899218885Sdim 900218885Sdim 901218885Sdim /** We are going to add a new subdirectory at @a path, a child of 902218885Sdim * the directory represented by @a parent_baton. We will use 903218885Sdim * the value this callback stores in @a *child_baton as the 904218885Sdim * parent baton for further changes in the new subdirectory. 905218885Sdim * 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, 1054 svn_txdelta_window_handler_t *handler, 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. */ 1120} svn_delta_editor_t; 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 */ 1136svn_delta_editor_t * 1137svn_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 */ 1144svn_error_t * 1145svn_delta_noop_window_handler(svn_txdelta_window_t *window, 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 */ 1158svn_error_t * 1159svn_delta_get_cancellation_editor(svn_cancel_func_t cancel_func, 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 */ 1201svn_error_t * 1202svn_delta_depth_filter_editor(const svn_delta_editor_t **editor, 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 */ 1241typedef 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 */ 1266svn_error_t * 1267svn_delta_path_driver2(const svn_delta_editor_t *editor, 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 */ 1285SVN_DEPRECATED 1286svn_error_t * 1287svn_delta_path_driver(const svn_delta_editor_t *editor, 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 */ 1325typedef 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 */ 1347typedef 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 */ 1370void 1371svn_compat_wrap_file_rev_handler(svn_file_rev_handler_t *handler2, 1372 void **handler2_baton, 1373 svn_file_rev_handler_old_t handler, 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 */ 1385