mod_dav: Note an API issue with the dav_hooks_repository.deliver(),

dav_hooks_vsn.deliver_report() and dav_hooks_vsn.merge() hook
definitions.

* modules/dav/main/mod_dav.h
  (dav_hooks_repository.deliver, dav_hooks_vsn.deliver_report,
   dav_hooks_vsn.merge): Add notes about the API issue.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1764043 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/modules/dav/main/mod_dav.h b/modules/dav/main/mod_dav.h
index 9e64e0589b5b3fdd1240deac25d3aab20c590279..d1f569fb1dbfdc4137a34825a68232081c3e832c 100644 (file)
--- a/modules/dav/main/mod_dav.h
+++ b/modules/dav/main/mod_dav.h
@@ -1934,8 +1934,8 @@ struct dav_hooks_repository
                                const dav_resource *resource);
 
     /*
-    ** The provider should deliver the resource into the specified filter.
-    ** Basically, this is the response to the GET method.
+    ** The provider should deliver the resource into the request's output
+    ** filter stack. Basically, this is the response to the GET method.
     **
     ** Note that this is called for all resources, including collections.
     ** The provider should determine what has content to deliver or not.
@@ -1945,6 +1945,15 @@ struct dav_hooks_repository
     **
     ** This may be NULL if handle_get is FALSE.
     ** ### maybe toss handle_get and just use this function as the marker
+    **
+    ** API ISSUE: don't use the passed-in 'output' filter.
+    **
+    ** Instead, generate the response into the output filter stack for the
+    ** request (r->output_filters). An implementation can use the request_rec
+    ** that was passed to get_resource() for this purpose. Using 'output'
+    ** filter for the response can cause unbounded memory usage.
+    **
+    ** See https://mail-archives.apache.org/mod_mbox/httpd-dev/201608.mbox/%3C20160822151917.GA22369%40redhat.com%3E
     */
     dav_error * (*deliver)(const dav_resource *resource,
                            ap_filter_t *output);
@@ -2296,6 +2305,15 @@ struct dav_hooks_vsn
     **
     ** ### maybe we need a way to signal an error anyways, and then
     ** ### apache can abort the connection?
+    **
+    ** API ISSUE: don't use the passed-in 'output' filter.
+    **
+    ** Instead, generate the response into the output filter stack for the
+    ** request (r->output_filters). An implementation can use the request_rec
+    ** that was passed to get_resource() for this purpose. Using 'output'
+    ** filter for the response can cause unbounded memory usage.
+    **
+    ** See https://mail-archives.apache.org/mod_mbox/httpd-dev/201608.mbox/%3C20160822151917.GA22369%40redhat.com%3E
     */
     dav_error * (*deliver_report)(request_rec *r,
                                   const dav_resource *resource,
@@ -2417,6 +2435,15 @@ struct dav_hooks_vsn
     **
     ** This hook is optional; if the provider does not support merging,
     ** then this should be set to NULL.
+    **
+    ** API ISSUE: don't use the passed-in 'output' filter.
+    **
+    ** Instead, generate the response into the output filter stack for the
+    ** request (r->output_filters). An implementation can use the request_rec
+    ** that was passed to get_resource() for this purpose. Using 'output'
+    ** filter for the response can cause unbounded memory usage.
+    **
+    ** See https://mail-archives.apache.org/mod_mbox/httpd-dev/201608.mbox/%3C20160822151917.GA22369%40redhat.com%3E
     */
     dav_error * (*merge)(dav_resource *target, dav_resource *source,
                          int no_auto_merge, int no_checkout,