[GNUnet-SVN] r35147 - libmicrohttpd/doc

[gnunet]

Author: grothoff
Date: 2015-02-08 11:52:04 +0100 (Sun, 08 Feb 2015)
New Revision: 35147

Modified:
   libmicrohttpd/doc/libmicrohttpd.texi
Log:
document pointer validity

Modified: libmicrohttpd/doc/libmicrohttpd.texi
===================================================================
--- libmicrohttpd/doc/libmicrohttpd.texi        2015-02-08 00:37:10 UTC (rev 
35146)
+++ libmicrohttpd/doc/libmicrohttpd.texi        2015-02-08 10:52:04 UTC (rev 
35147)
@@ -269,7 +269,34 @@
 
 @end table
 
address@hidden Validity of pointers
 
+MHD will give applications access to its internal data structures
+via pointers via arguments and return values from its API.  This
+creates the question as to how long those pointers are assured to
+stay valid.
+
+Most MHD data structures are associated with the connection of an
+HTTP client.  Thus, pointers associated with a connection are
+typically valid until the connection is finished, at which point
+MHD will call the @code{MHD_RequestCompletedCallback} if one is
+registered.  Applications that have such a callback registered
+may assume that keys and values from the
address@hidden, return values from
address@hidden and the @code{url},
address@hidden and @code{version} arguments to the
address@hidden will remain valid until the
+respective @code{MHD_RequestCompletedCallback} is invoked.
+
+In contrast, the @code{upload_data} argument of
address@hidden as well as all pointers
+from the @code{MHD_PostDataIterator} are only valid for the
+duration of the callback.
+
+Pointers returned from @code{MHD_get_response_header} are
+valid as long as the response itself is valid.
+
+
 @section Including the microhttpd.h header
 @cindex portability
 @cindex microhttpd.h