svn_delta.h

linux subdivision ying gai ke yi le ba

/**
 * @copyright
 * ====================================================================
 * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at http://subversion.tigris.org/license-1.html.
 * If newer versions of this license are posted there, you may use a
 * newer version instead, at your option.
 *
 * This software consists of voluntary contributions made by many
 * individuals.  For exact contribution history, see the revision
 * history and logs, available at http://subversion.tigris.org/.
 * ====================================================================
 * @endcopyright
 *
 * @file svn_delta.h
 * @brief Structures related to delta-parsing
 */

/* ==================================================================== */



#ifndef SVN_DELTA_H
#define SVN_DELTA_H

#include <apr.h>
#include <apr_pools.h>

#include "svn_types.h"
#include "svn_string.h"
#include "svn_error.h"
#include "svn_io.h"
#include "svn_version.h"

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */



/**
 * Get libsvn_delta version information.
 * @since New in 1.1.
 */
const svn_version_t *svn_delta_version (void);


/**  Text deltas.
 *
 * A text delta represents the difference between two strings of
 * bytes, the `source' string and the `target' string.  Given a source
 * string and a target string, we can compute a text delta; given a
 * source string and a delta, we can reconstruct the target string.
 * However, note that deltas are not reversible: you cannot always
 * reconstruct the source string given the target string and delta.
 *
 * Since text deltas can be very large, the interface here allows us
 * to produce and consume them in pieces.  Each piece, represented by
 * an @c svn_txdelta_window_t structure, describes how to produce the
 * next section of the target string.
 *
 * To compute a new text delta:
 *
 * - We call @c svn_txdelta on the streams we want to compare.  That
 *   returns us an @c svn_txdelta_stream_t object.
 *
 * - We then call @c svn_txdelta_next_window on the stream object
 *   repeatedly.  Each call returns a new @c svn_txdelta_window_t
 *   object, which describes the next portion of the target string.
 *   When @c svn_txdelta_next_window returns zero, we are done building
 *   the target string.
 *
 * @defgroup svn_delta_txt_delta text deltas
 * @{
 */


enum svn_delta_action {
    /** Append the @a len bytes at @a offset in the source view to the
     * target.
     *
     * It must be the case that @a 0 <= @a offset < @a offset + 
     * @a len <= size of source view.
     */
    svn_txdelta_source,

    /** Append the @a len bytes at @a offset in the target view, to the
     * target.
     *
     * It must be the case that @a 0 <= @a offset < current position in the 
     * target view.
     *
     * However!  @a offset + @a len may be *beyond* the end of the existing
     * target data.  "Where the heck does the text come from, then?"
     * If you start at @a offset, and append @a len bytes one at a time,
     * it'll work out --- you're adding new bytes to the end at the
     * same rate you're reading them from the middle.  Thus, if your
     * current target text is "abcdefgh", and you get an @c svn_delta_target
     * instruction whose @a offset is @a 6 and whose @a len is @a 7, 
     * the resulting string is "abcdefghghghghg".  This trick is actually 
     * useful in encoding long runs of consecutive characters, long runs 
     * of CR/LF pairs, etc.
     */
    svn_txdelta_target,

    /** Append the @a len bytes at @a offset in the window's @a new string 
     * to the target.
     *
     * It must be the case that @a 0 <= @a offset < @a offset +
     * @a len <= length of @a new.  Windows MUST use new data in ascending
     * order with no overlap at the moment; @c svn_txdelta_to_svndiff
     * depends on this.
     */
    svn_txdelta_new
};

/** A single text delta instruction.  */
typedef struct svn_txdelta_op_t
{
  enum svn_delta_action action_code;
  apr_size_t offset;
  apr_size_t length;
} svn_txdelta_op_t;


/** An @c svn_txdelta_window_t object describes how to reconstruct a
 * contiguous section of the target string (the "target view") using a
 * specified contiguous region of the source string (the "source
 * view").  It contains a series of instructions which assemble the
 * new target string text by pulling together substrings from:
 *
 *   - the source view,
 *
 *   - the previously constructed portion of the target view,
 *
 *   - a string of new data contained within the window structure
 *
 * The source view must always slide forward from one window to the
 * next; that is, neither the beginning nor the end of the source view
 * may move to the left as we read from a window stream.  This
 * property allows us to apply deltas to non-seekable source streams
 * without making a full copy of the source stream.
 */
typedef struct svn_txdelta_window_t
{

  /** The offset of the source view for this window.  */
  svn_filesize_t sview_offset;

  /** The length of the source view for this window.  */
  apr_size_t sview_len;

  /** The length of the target view for this window, i.e. the number of
   * bytes which will be reconstructed by the instruction stream.  */
  apr_size_t tview_len;

  /** The number of instructions in this window.  */
  int num_ops;

  /** The number of svn_txdelta_source instructions in this window. If
   * this number is 0, we don't need to read the source in order to
   * reconstruct the target view.
   */
  int src_ops;

  /** The instructions for this window.  */
  const svn_txdelta_op_t *ops;

  /** New data, for use by any `svn_delta_new' instructions.  */
  const svn_string_t *new_data;

} svn_txdelta_window_t;


/** A typedef for functions that consume a series of delta windows, for
 * use in caller-pushes interfaces.  Such functions will typically
 * apply the delta windows to produce some file, or save the windows
 * somewhere.  At the end of the delta window stream, you must call
 * this function passing zero for the @a window argument.
 */
typedef svn_error_t * (*svn_txdelta_window_handler_t)
                      (svn_txdelta_window_t *window, void *baton);


/** A delta stream --- this is the hat from which we pull a series of
 * svn_txdelta_window_t objects, which, taken in order, describe the
 * entire target string.  This type is defined within libsvn_delta, and
 * opaque outside that library.
 */
typedef struct svn_txdelta_stream_t svn_txdelta_stream_t;


/** Set @a *window to a pointer to the next window from the delta stream
 * @a stream.  When we have completely reconstructed the target string,
 * set @a *window to zero.
 *
 * The window will be allocated in @a pool.
 */
svn_error_t *svn_txdelta_next_window (svn_txdelta_window_t **window,
                                      svn_txdelta_stream_t *stream,
                                      apr_pool_t *pool);


/** Return the @a md5 digest for the complete fulltext deltified by
 * @a stream, or @c NULL if @a stream has not yet returned its final 
 * @c NULL window.  The digest is allocated in the same memory as @a 
 * STREAM.
 */
const unsigned char *svn_txdelta_md5_digest (svn_txdelta_stream_t *stream);

/** Set @a *stream to a pointer to a delta stream that will turn the byte
 * string from @a source into the byte stream from @a target.
 *
 * @a source and @a target are both readable generic streams.  When we call
 * @c svn_txdelta_next_window on @a *stream, it will read from @a source and
 * @a target to gather as much data as it needs.
 *
 * Do any necessary allocation in a sub-pool of @a pool.
 */
void svn_txdelta (svn_txdelta_stream_t **stream,
                  svn_stream_t *source,
                  svn_stream_t *target,
                  apr_pool_t *pool);


/** 
 * @since New in 1.1.
 *
 * Return a writable stream which, when fed target data, will send
 * delta windows to @a handler/@a handler_baton which transform the
 * data in @a source to the target data.  As usual, the window handler
 * will receive a NULL window to signify the end of the window stream.
 * The stream handler functions will read data from @a source as
 * necessary.
 */
svn_stream_t *svn_txdelta_target_push (svn_txdelta_window_handler_t handler,
                                       void *handler_baton,
                                       svn_stream_t *source,
                                       apr_pool_t *pool);


/** Send the contents of @a string to window-handler @a handler/@a baton. 
 * This is effectively a 'copy' operation, resulting in delta windows that 
 * make the target equivalent to the value of @a string.
 *
 * All temporary allocation is performed in @a pool.
 */
svn_error_t *svn_txdelta_send_string (const svn_string_t *string,
                                      svn_txdelta_window_handler_t handler,
                                      void *handler_baton,
                                      apr_pool_t *pool);

/** Send the contents of @a stream to window-handler @a handler/@a baton. 
 * This is effectively a 'copy' operation, resulting in delta windows that 
 * make the target equivalent to the stream.
 *
 * If @a digest is non-null, populate it with the md5 checksum for the
 * fulltext that was deltified (@a digest must be at least
 * @c APR_MD5_DIGESTSIZE bytes long).
 *
 * All temporary allocation is performed in @a pool.
 */
svn_error_t *svn_txdelta_send_stream (svn_stream_t *stream,
                                      svn_txdelta_window_handler_t handler,
                                      void *handler_baton,
                                      unsigned char *digest,
                                      apr_pool_t *pool);

/** Send the contents of @a txstream to window-handler @a handler/@a baton. 
 * Windows will be extracted from the stream and delivered to the handler.
 *
 * All temporary allocation is performed in @a pool.
 */
svn_error_t *svn_txdelta_send_txstream (svn_txdelta_stream_t *txstream,
                                        svn_txdelta_window_handler_t handler,
                                        void *handler_baton,
                                        apr_pool_t *pool);


/** Prepare to apply a text delta.  @a source is a readable generic stream
 * yielding the source data, @a target is a writable generic stream to
 * write target data to, and allocation takes place in a sub-pool of
 * @a pool.  On return, @a *handler is set to a window handler function and
 * @a *handler_baton is set to the value to pass as the @a baton argument to
 * @a *handler.
 *
 * If @a result_digest is non-null, it points to APR_MD5_DIGESTSIZE bytes
 * of storage, and the final call to @a handler populates it with the
 * MD5 digest of the resulting fulltext.
 *
 * If @a error_info is non-null, it is inserted parenthetically into
 * the error string for any error returned by svn_txdelta_apply() or
 * @a *handler.  (It is normally used to provide path information,
 * since there's nothing else in the delta application's context to
 * supply a path for error messages.)
 *
 * Note: To avoid lifetime issues, @a error_info is copied into 
 * @a pool or a subpool thereof.
 */
void svn_txdelta_apply (svn_stream_t *source,
                        svn_stream_t *target,
                        unsigned char *result_digest,
                        const char *error_info,
                        apr_pool_t *pool,