svn_delta.h

linux subdivision ying gai ke yi le ba

  /** Remove the directory entry named @a path, a child of the directory
   * represented by @a parent_baton.  If @a revision is set, it is used as a
   * sanity check to ensure that you are removing the revision of @a path
   * that you really think you are.
   *
   * All allocations should be performed in @a pool.
   */
  svn_error_t *(*delete_entry) (const char *path,
                                svn_revnum_t revision,
                                void *parent_baton,
                                apr_pool_t *pool);


  /** We are going to add a new subdirectory named @a path.  We will use
   * the value this callback stores in @a *child_baton as the
   * @a parent_baton for further changes in the new subdirectory.  
   *
   * If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a
   * copy), and the origin of the copy may be recorded as
   * @a copyfrom_path under @a copyfrom_revision.
   *
   * Allocations for the returned @a child_baton should be performed in
   * @a dir_pool. It is also typical to (possibly) save this pool for later
   * usage by @c close_directory.
   */
  svn_error_t *(*add_directory) (const char *path,
                                 void *parent_baton,
                                 const char *copyfrom_path,
                                 svn_revnum_t copyfrom_revision,
                                 apr_pool_t *dir_pool,
                                 void **child_baton);

  /** We are going to make changes in a subdirectory (of the directory
   * identified by @a parent_baton). The subdirectory is specified by
   * @a path. The callback must store a value in @a *child_baton that 
   * should be used as the @a parent_baton for subsequent changes in this
   * subdirectory.  If a valid revnum, @a base_revision is the current
   * revision of the subdirectory.
   *
   * Allocations for the returned @a child_baton should be performed in
   * @a dir_pool. It is also typical to (possibly) save this pool for later
   * usage by @c close_directory.
   */
  svn_error_t *(*open_directory) (const char *path,
                                  void *parent_baton,
                                  svn_revnum_t base_revision,
                                  apr_pool_t *dir_pool,
                                  void **child_baton);

  /** Change the value of a directory's property.
   * - @a dir_baton specifies the directory whose property should change.
   * - @a name is the name of the property to change.
   * - @a value is the new value of the property, or @c NULL if the property
   *   should be removed altogether.  
   *
   * All allocations should be performed in @a pool.
   */
  svn_error_t *(*change_dir_prop) (void *dir_baton,
                                   const char *name,
                                   const svn_string_t *value,
                                   apr_pool_t *pool);

  /** We are done processing a subdirectory, whose baton is @a dir_baton
   * (set by @c add_directory or @c open_directory).  We won't be using
   * the baton any more, so whatever resources it refers to may now be
   * freed.
   */
  svn_error_t *(*close_directory) (void *dir_baton,
                                   apr_pool_t *pool);


  /** In the directory represented by @a parent_baton, indicate that
   * @a path is present as a subdirectory in the edit source, but
   * cannot be conveyed to the edit consumer (perhaps because of
   * authorization restrictions).
   */
  svn_error_t *(*absent_directory) (const char *path,
                                    void *parent_baton,
                                    apr_pool_t *pool);

  /** We are going to add a new file named @a path.  The callback can
   * store a baton for this new file in @a **file_baton; whatever value
   * it stores there should be passed through to @c apply_textdelta.
   *
   * If @a copyfrom_path is non-@c NULL, this add has history (i.e., is a
   * copy), and the origin of the copy may be recorded as
   * @a copyfrom_path under @a copyfrom_revision.
   *
   * Allocations for the returned @a file_baton should be performed in
   * @a file_pool. It is also typical to save this pool for later usage
   * by @c apply_textdelta and possibly @c close_file.
   */
  svn_error_t *(*add_file) (const char *path,
                            void *parent_baton,
                            const char *copy_path,
                            svn_revnum_t copy_revision,
                            apr_pool_t *file_pool,
                            void **file_baton);

  /** We are going to make change to a file named @a path, which resides
   * in the directory identified by @a parent_baton.
   *
   * The callback can store a baton for this new file in @a **file_baton;
   * whatever value it stores there should be passed through to
   * apply_textdelta.  If a valid revnum, @a base_revision is the
   * current revision of the file.
   *
   * Allocations for the returned @a file_baton should be performed in
   * @a file_pool. It is also typical to save this pool for later usage
   * by @c apply_textdelta and possibly @c close_file.
   */
  svn_error_t *(*open_file) (const char *path,
                             void *parent_baton,
                             svn_revnum_t base_revision,
                             apr_pool_t *file_pool,
                             void **file_baton);

  /** Apply a text delta, yielding the new revision of a file.
   *
   * @a file_baton indicates the file we're creating or updating, and the
   * ancestor file on which it is based; it is the baton set by some
   * prior @c add_file or @c open_file callback.
   *
   * The callback should set @a *handler to a text delta window
   * handler; we will then call @a *handler on successive text
   * delta windows as we receive them.  The callback should set
   * @a *handler_baton to the value we should pass as the @a baton
   * argument to @a *handler.
   *
   * @a base_checksum is the hex MD5 digest for the base text against
   * which the delta is being applied; it is ignored if null, and may
   * be ignored even if not null.  If it is not ignored, it must match
   * the checksum of the base text against which svndiff data is being
   * applied; if it does not, apply_textdelta or the @a *handler call
   * which detects the mismatch will return the error
   * SVN_ERR_CHECKSUM_MISMATCH (if there is no base text, there may
   * still be an error if @a base_checksum is neither null nor the hex
   * MD5 checksum of the empty string).
   */
  svn_error_t *(*apply_textdelta) (void *file_baton,
                                   const char *base_checksum,
                                   apr_pool_t *pool,
                                   svn_txdelta_window_handler_t *handler,
                                   void **handler_baton);

  /** Change the value of a file's property.
   * - @a file_baton specifies the file whose property should change.
   * - @a name is the name of the property to change.
   * - @a value is the new value of the property, or @c NULL if the property
   *   should be removed altogether.
   *
   * All allocations should be performed in @a pool.
   */
  svn_error_t *(*change_file_prop) (void *file_baton,
                                    const char *name,
                                    const svn_string_t *value,
                                    apr_pool_t *pool);

  /** We are done processing a file, whose baton is @a file_baton (set by
   * @c add_file or @c open_file).  We won't be using the baton any
   * more, so whatever resources it refers to may now be freed.
   *
   * @a text_checksum is the hex MD5 digest for the fulltext that
   * resulted from a delta application, see @c apply_textdelta.  The
   * checksum is ignored if null.  If not null, it is compared to the
   * checksum of the new fulltext, and the error
   * SVN_ERR_CHECKSUM_MISMATCH is returned if they do not match.  If
   * there is no new fulltext, @a text_checksum is ignored.
   */
  svn_error_t *(*close_file) (void *file_baton,
                              const char *text_checksum,
                              apr_pool_t *pool);

  /** In the directory represented by @a parent_baton, indicate that
   * @a path is present as a file in the edit source, but cannot be
   * conveyed to the edit consumer (perhaps because of authorization
   * restrictions).
   */
  svn_error_t *(*absent_file) (const char *path,
                               void *parent_baton,
                               apr_pool_t *pool);

  /** All delta processing is done.  Call this, with the @a edit_baton for
   * the entire edit.
   */
  svn_error_t *(*close_edit) (void *edit_baton, 
                              apr_pool_t *pool);

  /** The editor-driver has decided to bail out.  Allow the editor to
   * gracefully clean up things if it needs to.
   */
  svn_error_t *(*abort_edit) (void *edit_baton,
                              apr_pool_t *pool);

} svn_delta_editor_t;  


/** Return a default delta editor template, allocated in @a pool.
 *
 * The editor functions in the template do only the most basic
 * baton-swapping: each editor function that produces a baton does so
 * by copying its incoming baton into the outgoing baton reference.
 *
 * This editor is not intended to be useful by itself, but is meant to
 * be the basis for a useful editor.  After getting a default editor,
 * you substitute in your own implementations for the editor functions
 * you care about.  The ones you don't care about, you don't have to
 * implement -- you can rely on the template's implementation to
 * safely do nothing of consequence.
 */
svn_delta_editor_t *svn_delta_default_editor (apr_pool_t *pool);

/** A text-delta window handler which does nothing.
 *
 * Editors can return this handler from apply_textdelta if they don't
 * care about text delta windows.
 */
svn_error_t *svn_delta_noop_window_handler (svn_txdelta_window_t *window,
                                            void *baton);

/** Return a cancellation editor that wraps @a wrapped_editor.
 *
 * The @a editor will call @a cancel_func with @a cancel_baton when each of 
 * its functions is called, continuing on to call the corresponding wrapped 
 * function if it returns @c SVN_NO_ERROR.
 *
 * If @a cancel_func is @c NULL, @a *editor is set to @a wrapped_editor and 
 * @a *edit_baton is set to @a wrapped_baton.
 */
svn_error_t *
svn_delta_get_cancellation_editor (svn_cancel_func_t cancel_func,
                                   void *cancel_baton,
                                   const svn_delta_editor_t *wrapped_editor,
                                   void *wrapped_baton,
                                   const svn_delta_editor_t **editor,
                                   void **edit_baton,
                                   apr_pool_t *pool);

/** @} */


/** Path-based editor drives.
 * 
 * @defgroup svn_delta_path_delta_drivers path-based delta drivers
 * @{
 */

/** Callback function type for svn_delta_path_driver().
 *
 * The handler of this callback is given the callback baton @a
 * callback_baton, @a path, and the @a parent_baton which represents
 * path's parent directory as created by the editor passed to
 * svn_delta_path_driver().
 *
 * If @a path represents a directory, the handler must return a @a
 * *dir_baton for @a path, generated from the same editor (so that the
 * driver can later close that directory).
 *
 * If, however, @a path represents a file, the handler should NOT
 * return any file batons.  It can close any opened or added files
 * immediately, or delay that close until the end of the edit when
 * svn_delta_path_driver() returns.
 *
 * Finally, if @a parent_baton is @c NULL, then the root of the edit
 * is also one of the paths passed to svn_delta_path_driver().  The
 * handler of this callback must call the editor's open_root()
 * function and return the top-level root dir baton in @a *dir_baton. 
 */
typedef svn_error_t *
(*svn_delta_path_driver_cb_func_t) (void **dir_baton,
                                    void *parent_baton,
                                    void *callback_baton,
                                    const char *path,
                                    apr_pool_t *pool);
  

/** Drive @a editor (with its @a edit_baton) in such a way that
 * each path in @a paths is traversed in a depth-first fashion.  As
 * each path is hit as part of the editor drive, use @a
 * callback_func and @a callback_baton to allow the caller to handle
 * the portion of the editor drive related to that path.  
 *
 * Use @a revision as the revision number passed to intermediate
 * directory openings.  
 *
 * Use @a pool for all necessary allocations. 
 */
svn_error_t *
svn_delta_path_driver (const svn_delta_editor_t *editor,
                       void *edit_baton,
                       svn_revnum_t revision,
                       apr_array_header_t *paths,
                       svn_delta_path_driver_cb_func_t callback_func,
                       void *callback_baton,
                       apr_pool_t *pool);

/** @} */


#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* SVN_DELTA_H */