[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r37815 - in libmicrohttpd: doc src/include src/microhttpd
From: |
gnunet |
Subject: |
[GNUnet-SVN] r37815 - in libmicrohttpd: doc src/include src/microhttpd |
Date: |
Sat, 27 Aug 2016 21:31:32 +0200 |
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,
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r37815 - in libmicrohttpd: doc src/include src/microhttpd,
gnunet <=