[GNUnet-SVN] r37815 - in libmicrohttpd: doc src/include src/microhttpd

[gnunet]

Author: grothoff
Date: 2016-08-27 21:31:32 +0200 (Sat, 27 Aug 2016)
New Revision: 37815

Modified:
   libmicrohttpd/doc/libmicrohttpd.texi
   libmicrohttpd/src/include/microhttpd.h
   libmicrohttpd/src/microhttpd/response.c
   libmicrohttpd/src/microhttpd/test_upgrade.c
Log:
documenting upgrade API in manual

Modified: libmicrohttpd/doc/libmicrohttpd.texi
===================================================================
--- libmicrohttpd/doc/libmicrohttpd.texi        2016-08-27 19:01:52 UTC (rev 
37814)
+++ libmicrohttpd/doc/libmicrohttpd.texi        2016-08-27 19:31:32 UTC (rev 
37815)
@@ -11,7 +11,7 @@
 (version @value{VERSION}, @value{UPDATED}), a library for embedding
 an HTTP(S) server into C applications.
 
-Copyright @copyright{} 2007--2015 Christian Grothoff
+Copyright @copyright{} 2007--2016 Christian Grothoff
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -1716,6 +1716,7 @@
 * microhttpd-response headers:: Adding headers to a response.
 * microhttpd-response options:: Setting response options.
 * microhttpd-response inspect:: Inspecting a response object.
+* microhttpd-response upgrade:: Creating a response for protocol upgrades.
 @end menu
 
 @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -2066,6 +2067,101 @@
 @end deftypefun
 
 
address@hidden ------------------------------------------------------------
address@hidden microhttpd-response upgrade
address@hidden Creating a response for protocol upgrades
address@hidden WebSockets
address@hidden Upgrade
address@hidden HTTP2
address@hidden RFC2817
+
+With RFC 2817 a mechanism to switch protocols within HTTP was
+introduced.  Here, a client sends a request with a ``Connection:
+Upgrade'' header.  The server responds with a ``101 Switching
+Protocols'' response header, after which the two parties begin to
+speak a different (non-HTTP) protocol over the TCP connection.
+
+This mechanism is used for upgrading HTTP 1.1 connections to HTTP2 or
+HTTPS, as well as for implementing WebSockets.  Which protocol
+upgrade is performed is negotiated between server and client in
+additional headers, in particular the ``Upgrade'' header.
+
+MHD supports switching protocols using this mechanism only if the
address@hidden flag has been set when starting
+the daemon.  If this flag has been set, applications can upgrade
+a connection by queueing a response (using the
address@hidden status code) which must
+have been created with the following function:
+
+
address@hidden int MHD_create_response_for_upgrade (MHD_UpgradeHandler 
upgrade_handler, void *upgrade_handler_cls)
+Create a response suitable for switching protocols.  Returns @code{MHD_YES} on 
success.  @code{upgrade_handler} must not be @code{NULL}.
+
+When creating this type of response, the ``Connection: Upgrade''
+header will be set automatically for you.  MHD requires that you
+additionally set a ``Upgrade:'' header.  The ``Upgrade'' header
+must simply exist, which value is used is up to the application.
+
address@hidden deftypefun
+
+The @code{upgrade_handler} argument to the above has the following type:
+
+
address@hidden {Function Pointer} void {*MHD_UpgradeHandler} (void *cls, struct 
MHD_Connection *connection, const char *extra_in, size_t extra_in_size, 
MHD_socket sock, struct MHD_UpgradeResponseHandle *urh)
+This function will be called once MHD has transmitted the header of the 
response to the connection that is being upgraded.  At this point, the 
application is expected to take over the socket @code{sock} and speak the 
non-HTTP protocol to which the connection was upgraded.  MHD will no longer use 
the socket; this includes handling timeouts.  The application must call 
@code{MHD_upgrade_action} with an upgrade action of 
@code{MHD_UPGRADE_ACTION_CLOSE} when it is done processing the connection to 
close the socket.  The application must not call @code{MHD_stop_daemon} on the 
respective daemon as long as it is still handling the connection.  The 
arguments given to the @code{upgrade_handler} have the following meaning:
+
address@hidden @var
address@hidden cls
+matches the @code{upgrade_handler_cls} that was given to 
@code{MHD_create_response_for_upgrade}
address@hidden connection
+identifies the connection that is being upgraded;
+
address@hidden con_cls
+last value left in `*con_cls` in the `MHD_AccessHandlerCallback`
+
address@hidden extra_in
+buffer of bytes MHD read ``by accident'' from the socket already.  This can 
happen if the client eagerly transmits more than just the HTTP request.   The 
application should treat these as if it had read them from the socket.
+
address@hidden extra_in_size
+number of bytes in @code{extra_in}
+
address@hidden sock
+the socket which the application can now use directly for some bi-directional 
communication with the client
+
address@hidden urh
+argument for calls to @code{MHD_upgrade_action}.  Applications must eventually 
use this function to perform the close() action on the socket.
address@hidden table
+
address@hidden deftypefn
+
address@hidden int MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh, 
enum MHD_UpgradeAction action, ...)
+Perform special operations related to upgraded connections.
+
address@hidden @var
address@hidden urh
+identifies the upgraded connection to perform an action on
+
address@hidden action
+specifies the action to perform; further arguments to the function depend on 
the specifics of the action.
address@hidden table
+
address@hidden deftypefun
+
+
address@hidden {Enumeration} MHD_UpgradeAction
+Set of actions to be performed on upgraded connections.  Passed as an argument 
to
address@hidden()}.
+
address@hidden @code
address@hidden MHD_UPGRADE_ACTION_CLOSE
+Closes the connection.  Must be called once the application is done with the 
client.  Takes no additional arguments.
+
address@hidden MHD_UPGRADE_ACTION_CORK
+Uncork the TCP write buffer.  Not implemented.  Takes no additional arguments.
address@hidden table
address@hidden deftp
+
+
 @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 @c ------------------------------------------------------------

Modified: libmicrohttpd/src/include/microhttpd.h
===================================================================
--- libmicrohttpd/src/include/microhttpd.h      2016-08-27 19:01:52 UTC (rev 
37814)
+++ libmicrohttpd/src/include/microhttpd.h      2016-08-27 19:31:32 UTC (rev 
37815)
@@ -2310,6 +2310,7 @@
  * @param connection original HTTP connection handle,
  *                   giving the function a last chance
  *                   to inspect the original HTTP request
+ * @param con_cls last value left in `con_cls` of the 
`MHD_AccessHandlerCallback`
  * @param extra_in if we happened to have read bytes after the
  *                 HTTP header already (because the client sent
  *                 more than the HTTP header of the request before
@@ -2331,6 +2332,7 @@
 typedef void
 (*MHD_UpgradeHandler)(void *cls,
                       struct MHD_Connection *connection,
+                      void *con_cls,
                       const char *extra_in,
                       size_t extra_in_size,
                       MHD_socket sock,

Modified: libmicrohttpd/src/microhttpd/response.c
===================================================================
--- libmicrohttpd/src/microhttpd/response.c     2016-08-27 19:01:52 UTC (rev 
37814)
+++ libmicrohttpd/src/microhttpd/response.c     2016-08-27 19:31:32 UTC (rev 
37815)
@@ -702,6 +702,7 @@
     connection->read_buffer_offset = 0;
     response->upgrade_handler (response->upgrade_handler_cls,
                                connection,
+                               connection->con_cls,
                                connection->read_buffer,
                                rbo,
                                urh->app_socket,

Modified: libmicrohttpd/src/microhttpd/test_upgrade.c
===================================================================
--- libmicrohttpd/src/microhttpd/test_upgrade.c 2016-08-27 19:01:52 UTC (rev 
37814)
+++ libmicrohttpd/src/microhttpd/test_upgrade.c 2016-08-27 19:31:32 UTC (rev 
37815)
@@ -177,6 +177,7 @@
  * @param connection original HTTP connection handle,
  *                   giving the function a last chance
  *                   to inspect the original HTTP request
+ * @param con_cls last value left in `*con_cls` in the 
`MHD_AccessHandlerCallback`
  * @param extra_in if we happened to have read bytes after the
  *                 HTTP header already (because the client sent
  *                 more than the HTTP header of the request before
@@ -192,12 +193,13 @@
  *        may not work as expected (as the socket could be from a
  *        socketpair() or a TCP-loopback)
  * @param urh argument for #MHD_upgrade_action()s on this @a connection.
- *        Applications must eventually use this callback to perform the
+ *        Applications must eventually use this function to perform the
  *        close() action on the @a sock.
  */
 static void
 upgrade_cb (void *cls,
             struct MHD_Connection *connection,
+            void *con_cls,
             const char *extra_in,
             size_t extra_in_size,
             MHD_socket sock,