aboutsummaryrefslogtreecommitdiffstats
path: root/subversion/include/svn_delta.h
diff options
context:
space:
mode:
Diffstat (limited to 'subversion/include/svn_delta.h')
-rw-r--r--subversion/include/svn_delta.h164
1 files changed, 146 insertions, 18 deletions
diff --git a/subversion/include/svn_delta.h b/subversion/include/svn_delta.h
index c15788ee4d00..ee9e11fed6b5 100644
--- a/subversion/include/svn_delta.h
+++ b/subversion/include/svn_delta.h
@@ -495,6 +495,10 @@ svn_txdelta_send_contents(const unsigned char *contents,
* since there's nothing else in the delta application's context to
* supply a path for error messages.)
*
+ * The @a source stream will NOT be closed. The @a target stream will be
+ * closed when the window handler is given a null window to signal the
+ * end of the delta.
+ *
* @note To avoid lifetime issues, @a error_info is copied into
* @a pool or a subpool thereof.
*/
@@ -859,7 +863,7 @@ svn_txdelta_skip_svndiff_window(apr_file_t *file,
* @c apply_textdelta / @c apply_textdelta_stream and @c close_file
* should not refer to a parent directory baton UNLESS the editor has
* taken precautions to allocate it in a pool of the appropriate
- * lifetime (the @a dir_pool passed to @c open_directory and
+ * lifetime (the @a result_pool passed to @c open_directory and
* @c add_directory definitely does not have the proper lifetime).
* In general, it is recommended to simply avoid keeping a parent
* directory baton in a file baton.
@@ -1285,24 +1289,47 @@ svn_delta_depth_filter_editor(const svn_delta_editor_t **editor,
/** Callback function type for svn_delta_path_driver().
*
* The handler of this callback is given the callback baton @a
- * callback_baton, @a path which is a relpath relative to the
+ * callback_baton, @a editor and @a edit_baton which represent the
+ * editor being driven, @a relpath which is a relpath relative to the
* root of the edit, and the @a parent_baton which represents
- * path's parent directory as created by the editor passed to
- * svn_delta_path_driver().
+ * @a relpath's parent directory as created by the editor.
+ *
+ * If the handler deletes the node at @a relpath (and does not replace it
+ * with an added directory) it must set @a *dir_baton to null or leave
+ * it unchanged.
*
- * 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 the handler opens (or adds) a directory at @a relpath, it must set
+ * @a *dir_baton to the directory baton for @a relpath, generated from
+ * the same editor. The driver will close the directory later.
*
- * 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.
+ * If the handler opens (or adds) a file at @a relpath, the handler must
+ * set @a *dir_baton to null or leave it unchanged. The handler must
+ * either close the file 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.
+ *
+ * @since New in 1.12.
+ */
+typedef svn_error_t *(*svn_delta_path_driver_cb_func2_t)(
+ void **dir_baton,
+ const svn_delta_editor_t *editor,
+ void *edit_baton,
+ void *parent_baton,
+ void *callback_baton,
+ const char *relpath,
+ apr_pool_t *pool);
+
+/** Like #svn_delta_path_driver_cb_func2_t but without the @a editor and
+ * @a edit_baton parameters. The user must arrange for the editor to be
+ * passed through @a callback_baton (if required, which it usually is).
+ * And @a path could possibly have a '/' prefix instead of being a relpath;
+ * see the note on svn_delta_path_driver2().
+ *
+ * @deprecated Provided for backward compatibility with the 1.11 API.
*/
typedef svn_error_t *(*svn_delta_path_driver_cb_func_t)(
void **dir_baton,
@@ -1312,24 +1339,51 @@ typedef svn_error_t *(*svn_delta_path_driver_cb_func_t)(
apr_pool_t *pool);
-/** Drive @a editor (with its @a edit_baton) to visit each path in @a paths.
+/** Drive @a editor (with its @a edit_baton) to visit each path in @a relpaths.
+ *
* 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.
*
- * Each path in @a paths is a (const char *) relpath, relative
- * to the root path of the @a edit. The editor drive will be
- * performed in the same order as @a paths. The paths should be sorted
- * using something like svn_sort_compare_paths to ensure that a depth-first
- * pattern is observed for directory/file baton creation. If @a sort_paths
+ * Each path in @a relpaths is a (const char *) relpath, relative
+ * to the root path of the edit. The editor drive will be
+ * performed in the same order as @a relpaths. The paths should be sorted
+ * using something like svn_sort_compare_paths() to ensure that each
+ * directory in the depth-first walk is visited only once. If @a sort_paths
* is set, the function will sort the paths for you. Some callers may need
* further customization of the order (ie. libsvn_delta/compat.c).
*
+ * If the first target path (after any requested sorting) is @c "" (the
+ * root of the edit), the callback function will be responsible for
+ * calling the editor's @c open_root method; otherwise, this function
+ * will call @c open_root.
+ *
* Use @a scratch_pool for all necessary allocations.
*
- * @since New in 1.8.
+ * @since New in 1.12.
*/
svn_error_t *
+svn_delta_path_driver3(const svn_delta_editor_t *editor,
+ void *edit_baton,
+ const apr_array_header_t *relpaths,
+ svn_boolean_t sort_paths,
+ svn_delta_path_driver_cb_func2_t callback_func,
+ void *callback_baton,
+ apr_pool_t *pool);
+
+/** Like svn_delta_path_driver3() but with a different callback function
+ * signature.
+ *
+ * Optionally, paths in @a paths could have a '/' prefix instead of being
+ * relpaths. If any of them do, then (since 1.12) ALL paths sent to the
+ * callback will have a '/' prefix.
+ *
+ * @deprecated Provided for backward compatibility with the 1.11 API.
+ * @since New in 1.8. Before 1.12, paths sent to the callback were the
+ * exact paths passed in @a paths.
+ */
+SVN_DEPRECATED
+svn_error_t *
svn_delta_path_driver2(const svn_delta_editor_t *editor,
void *edit_baton,
const apr_array_header_t *paths,
@@ -1358,6 +1412,80 @@ svn_delta_path_driver(const svn_delta_editor_t *editor,
void *callback_baton,
apr_pool_t *scratch_pool);
+
+/** A state object for the path driver that is obtained from
+ * svn_delta_path_driver_start() and driven by
+ * svn_delta_path_driver_step() and svn_delta_path_driver_finish().
+ *
+ * @since New in 1.12.
+ */
+typedef struct svn_delta_path_driver_state_t svn_delta_path_driver_state_t;
+
+/** Return a path driver object that can drive @a editor (with its
+ * @a edit_baton) to visit a series of paths.
+ *
+ * As each path is hit as part of the editor drive, the path driver will
+ * call @a callback_func and @a callback_baton to allow the caller to handle
+ * the portion of the editor drive related to that path.
+ *
+ * This will not call the editor's open_root method; for that, see
+ * svn_delta_path_driver_step().
+ *
+ * @since New in 1.12.
+ */
+svn_error_t *
+svn_delta_path_driver_start(svn_delta_path_driver_state_t **state_p,
+ const svn_delta_editor_t *editor,
+ void *edit_baton,
+ svn_delta_path_driver_cb_func2_t callback_func,
+ void *callback_baton,
+ apr_pool_t *result_pool);
+
+/** Visit @a relpath.
+ *
+ * @a state is the object returned by svn_delta_path_driver_start().
+ *
+ * @a relpath is a relpath relative to the root path of the edit.
+ *
+ * This function uses the editor and the callback that were originally
+ * supplied to svn_delta_path_driver_start().
+ *
+ * This drives the editor in a depth-first order, closing and then opening
+ * directories if necessary to move from the last visited path to the new
+ * path, as required by the editor driving rules.
+ *
+ * This then calls the callback to allow the caller to handle
+ * the portion of the editor drive related to that path.
+ *
+ * If the first path to visit is @c "" (the root of the edit), the
+ * callback function will be responsible for calling the editor's
+ * @c open_root method; otherwise, this function will call @c open_root.
+ *
+ * The order of paths to visit should in general be sorted using something
+ * like svn_sort_compare_paths() to ensure that each directory in the
+ * depth-first walk is visited only once. Some editors may rely on such a
+ * restriction.
+ *
+ * @since New in 1.12.
+ */
+svn_error_t *
+svn_delta_path_driver_step(svn_delta_path_driver_state_t *state,
+ const char *relpath,
+ apr_pool_t *scratch_pool);
+
+/** Finish driving the editor.
+ *
+ * @a state is the object returned by svn_delta_path_driver_start().
+ *
+ * This drives the editor to close any open directories and then calls
+ * the editor's @c close_edit method.
+ *
+ * @since New in 1.12.
+ */
+svn_error_t *
+svn_delta_path_driver_finish(svn_delta_path_driver_state_t *state,
+ apr_pool_t *scratch_pool);
+
/** @} */