New upstream version 1.3.0+dfsg.1

[libgit2.git] / include / git2 / sys / filter.h

diff --git a/include/git2/sys/filter.h b/include/git2/sys/filter.h
index e43fde55c2fe54f14b76d93dedc561918b7fb64c..b3759416a1dd8ab5cfd6e43c2b2ae99f9e879d2d 100644 (file)
--- a/include/git2/sys/filter.h
+++ b/include/git2/sys/filter.h
@@ -167,17 +167,18 @@ typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self);
  *
  * The `payload` will be a pointer to a reference payload for the filter.
  * This will start as NULL, but `check` can assign to this pointer for
- * later use by the `apply` callback.  Note that the value should be heap
- * allocated (not stack), so that it doesn't go away before the `apply`
+ * later use by the `stream` callback.  Note that the value should be heap
+ * allocated (not stack), so that it doesn't go away before the `stream`
  * callback can use it.  If a filter allocates and assigns a value to the
  * `payload`, it will need a `cleanup` callback to free the payload.
  */
 typedef int GIT_CALLBACK(git_filter_check_fn)(
-       git_filter  *self,
-       void       **payload, /* points to NULL ptr on entry, may be set */
+       git_filter              *self,
+       void                   **payload, /* NULL on entry, may be set */
        const git_filter_source *src,
-       const char **attr_values);
+       const char             **attr_values);
 
+#ifndef GIT_DEPRECATE_HARD
 /**
  * Callback to actually perform the data filtering
  *
@@ -189,32 +190,45 @@ typedef int GIT_CALLBACK(git_filter_check_fn)(
  *
  * The `payload` value will refer to any payload that was set by the
  * `check` callback.  It may be read from or written to as needed.
+ *
+ * @deprecated use git_filter_stream_fn
  */
 typedef int GIT_CALLBACK(git_filter_apply_fn)(
-       git_filter    *self,
-       void         **payload, /* may be read and/or set */
-       git_buf       *to,
-       const git_buf *from,
+       git_filter              *self,
+       void                   **payload, /* may be read and/or set */
+       git_buf                 *to,
+       const git_buf           *from,
        const git_filter_source *src);
+#endif
 
+/**
+ * Callback to perform the data filtering.
+ *
+ * Specified as `filter.stream`, this is a callback that filters data
+ * in a streaming manner.  This function will provide a
+ * `git_writestream` that will the original data will be written to;
+ * with that data, the `git_writestream` will then perform the filter
+ * translation and stream the filtered data out to the `next` location.
+ */
 typedef int GIT_CALLBACK(git_filter_stream_fn)(
-       git_writestream **out,
-       git_filter *self,
-       void **payload,
+       git_writestream        **out,
+       git_filter              *self,
+       void                   **payload,
        const git_filter_source *src,
-       git_writestream *next);
+       git_writestream         *next);
 
 /**
  * Callback to clean up after filtering has been applied
  *
  * Specified as `filter.cleanup`, this is an optional callback invoked
- * after the filter has been applied.  If the `check` or `apply` callbacks
- * allocated a `payload` to keep per-source filter state, use this
- * callback to free that payload and release resources as required.
+ * after the filter has been applied.  If the `check`, `apply`, or
+ * `stream` callbacks allocated a `payload` to keep per-source filter
+ * state, use this callback to free that payload and release resources
+ * as required.
  */
 typedef void GIT_CALLBACK(git_filter_cleanup_fn)(
-       git_filter *self,
-       void       *payload);
+       git_filter              *self,
+       void                    *payload);
 
 /**
  * Filter structure used to register custom filters.
@@ -248,21 +262,28 @@ struct git_filter {
        /**
         * Called to determine whether the filter should be invoked for a
         * given file.  If this function returns `GIT_PASSTHROUGH` then the
-        * `apply` function will not be invoked and the contents will be passed
-        * through unmodified.
+        * `stream` or `apply` functions will not be invoked and the
+        * contents will be passed through unmodified.
         */
        git_filter_check_fn    check;
 
+#ifdef GIT_DEPRECATE_HARD
+       void *reserved;
+#else
        /**
-        * Called to actually apply the filter to file contents.  If this
-        * function returns `GIT_PASSTHROUGH` then the contents will be passed
-        * through unmodified.
+        * Provided for backward compatibility; this will apply the
+        * filter to the given contents in a `git_buf`.  Callers should
+        * provide a `stream` function instead.
         */
        git_filter_apply_fn    apply;
+#endif
 
        /**
-        * Called to apply the filter in a streaming manner.  If this is not
-        * specified then the system will call `apply` with the whole buffer.
+        * Called to apply the filter, this function will provide a
+        * `git_writestream` that will the original data will be
+        * written to; with that data, the `git_writestream` will then
+        * perform the filter translation and stream the filtered data
+        * out to the `next` location.
         */
        git_filter_stream_fn   stream;
 
@@ -289,9 +310,9 @@ GIT_EXTERN(int) git_filter_init(git_filter *filter, unsigned int version);
  * As mentioned elsewhere, the initialize callback will not be invoked
  * immediately.  It is deferred until the filter is used in some way.
  *
- * A filter's attribute checks and `check` and `apply` callbacks will be
- * issued in order of `priority` on smudge (to workdir), and in reverse
- * order of `priority` on clean (to odb).
+ * A filter's attribute checks and `check` and `stream` (or `apply`)
+ * callbacks will be issued in order of `priority` on smudge (to
+ * workdir), and in reverse order of `priority` on clean (to odb).
  *
  * Two filters are preregistered with libgit2:
  * - GIT_FILTER_CRLF with priority 0