aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2016-08-27 19:31:32 +0000
committerChristian Grothoff <christian@grothoff.org>2016-08-27 19:31:32 +0000
commit11171dc8c5741387a165bcf4f909c9c7af6e270e (patch)
tree59531bc20da3f660bcb28127184540025bb3cacd
parentcfbd80d1e127a98175c0276b7ffbcfb2475fea3b (diff)
downloadlibmicrohttpd-11171dc8c5741387a165bcf4f909c9c7af6e270e.tar.gz
libmicrohttpd-11171dc8c5741387a165bcf4f909c9c7af6e270e.zip
documenting upgrade API in manual
-rw-r--r--doc/libmicrohttpd.texi98
-rw-r--r--src/include/microhttpd.h2
-rw-r--r--src/microhttpd/response.c1
-rw-r--r--src/microhttpd/test_upgrade.c4
4 files changed, 103 insertions, 2 deletions
diff --git a/doc/libmicrohttpd.texi b/doc/libmicrohttpd.texi
index b95e27b8..deee825e 100644
--- a/doc/libmicrohttpd.texi
+++ b/doc/libmicrohttpd.texi
@@ -11,7 +11,7 @@ This manual is for GNU libmicrohttpd
11(version @value{VERSION}, @value{UPDATED}), a library for embedding 11(version @value{VERSION}, @value{UPDATED}), a library for embedding
12an HTTP(S) server into C applications. 12an HTTP(S) server into C applications.
13 13
14Copyright @copyright{} 2007--2015 Christian Grothoff 14Copyright @copyright{} 2007--2016 Christian Grothoff
15 15
16@quotation 16@quotation
17Permission is granted to copy, distribute and/or modify this document 17Permission is granted to copy, distribute and/or modify this document
@@ -1716,6 +1716,7 @@ response and we finally destroy it only when the daemon shuts down.
1716* microhttpd-response headers:: Adding headers to a response. 1716* microhttpd-response headers:: Adding headers to a response.
1717* microhttpd-response options:: Setting response options. 1717* microhttpd-response options:: Setting response options.
1718* microhttpd-response inspect:: Inspecting a response object. 1718* microhttpd-response inspect:: Inspecting a response object.
1719* microhttpd-response upgrade:: Creating a response for protocol upgrades.
1719@end menu 1720@end menu
1720 1721
1721@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1722@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -2066,6 +2067,101 @@ We should not modify the value, unless we know what we are doing.
2066@end deftypefun 2067@end deftypefun
2067 2068
2068 2069
2070@c ------------------------------------------------------------
2071@node microhttpd-response upgrade
2072@section Creating a response for protocol upgrades
2073@cindex WebSockets
2074@cindex Upgrade
2075@cindex HTTP2
2076@cindex RFC2817
2077
2078With RFC 2817 a mechanism to switch protocols within HTTP was
2079introduced. Here, a client sends a request with a ``Connection:
2080Upgrade'' header. The server responds with a ``101 Switching
2081Protocols'' response header, after which the two parties begin to
2082speak a different (non-HTTP) protocol over the TCP connection.
2083
2084This mechanism is used for upgrading HTTP 1.1 connections to HTTP2 or
2085HTTPS, as well as for implementing WebSockets. Which protocol
2086upgrade is performed is negotiated between server and client in
2087additional headers, in particular the ``Upgrade'' header.
2088
2089MHD supports switching protocols using this mechanism only if the
2090@code{MHD_USE_SUSPEND_RESUME} flag has been set when starting
2091the daemon. If this flag has been set, applications can upgrade
2092a connection by queueing a response (using the
2093@code{MHD_HTTP_SWITCHING_PROTOCOLS} status code) which must
2094have been created with the following function:
2095
2096
2097@deftypefun int MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler, void *upgrade_handler_cls)
2098Create a response suitable for switching protocols. Returns @code{MHD_YES} on success. @code{upgrade_handler} must not be @code{NULL}.
2099
2100When creating this type of response, the ``Connection: Upgrade''
2101header will be set automatically for you. MHD requires that you
2102additionally set a ``Upgrade:'' header. The ``Upgrade'' header
2103must simply exist, which value is used is up to the application.
2104
2105@end deftypefun
2106
2107The @code{upgrade_handler} argument to the above has the following type:
2108
2109
2110@deftypefn {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)
2111This 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:
2112
2113@table @var
2114@item cls
2115matches the @code{upgrade_handler_cls} that was given to @code{MHD_create_response_for_upgrade}
2116@item connection
2117identifies the connection that is being upgraded;
2118
2119@item con_cls
2120last value left in `*con_cls` in the `MHD_AccessHandlerCallback`
2121
2122@item extra_in
2123buffer 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.
2124
2125@item extra_in_size
2126number of bytes in @code{extra_in}
2127
2128@item sock
2129the socket which the application can now use directly for some bi-directional communication with the client
2130
2131@item urh
2132argument for calls to @code{MHD_upgrade_action}. Applications must eventually use this function to perform the close() action on the socket.
2133@end table
2134
2135@end deftypefn
2136
2137@deftypefun int MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh, enum MHD_UpgradeAction action, ...)
2138Perform special operations related to upgraded connections.
2139
2140@table @var
2141@item urh
2142identifies the upgraded connection to perform an action on
2143
2144@item action
2145specifies the action to perform; further arguments to the function depend on the specifics of the action.
2146@end table
2147
2148@end deftypefun
2149
2150
2151@deftp {Enumeration} MHD_UpgradeAction
2152Set of actions to be performed on upgraded connections. Passed as an argument to
2153@code{MHD_upgrade_action()}.
2154
2155@table @code
2156@item MHD_UPGRADE_ACTION_CLOSE
2157Closes the connection. Must be called once the application is done with the client. Takes no additional arguments.
2158
2159@item MHD_UPGRADE_ACTION_CORK
2160Uncork the TCP write buffer. Not implemented. Takes no additional arguments.
2161@end table
2162@end deftp
2163
2164
2069@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2165@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2070 2166
2071@c ------------------------------------------------------------ 2167@c ------------------------------------------------------------
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
index 0a7e4711..46a82625 100644
--- a/src/include/microhttpd.h
+++ b/src/include/microhttpd.h
@@ -2310,6 +2310,7 @@ MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh,
2310 * @param connection original HTTP connection handle, 2310 * @param connection original HTTP connection handle,
2311 * giving the function a last chance 2311 * giving the function a last chance
2312 * to inspect the original HTTP request 2312 * to inspect the original HTTP request
2313 * @param con_cls last value left in `con_cls` of the `MHD_AccessHandlerCallback`
2313 * @param extra_in if we happened to have read bytes after the 2314 * @param extra_in if we happened to have read bytes after the
2314 * HTTP header already (because the client sent 2315 * HTTP header already (because the client sent
2315 * more than the HTTP header of the request before 2316 * more than the HTTP header of the request before
@@ -2331,6 +2332,7 @@ MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh,
2331typedef void 2332typedef void
2332(*MHD_UpgradeHandler)(void *cls, 2333(*MHD_UpgradeHandler)(void *cls,
2333 struct MHD_Connection *connection, 2334 struct MHD_Connection *connection,
2335 void *con_cls,
2334 const char *extra_in, 2336 const char *extra_in,
2335 size_t extra_in_size, 2337 size_t extra_in_size,
2336 MHD_socket sock, 2338 MHD_socket sock,
diff --git a/src/microhttpd/response.c b/src/microhttpd/response.c
index fa45f5f5..9336aa91 100644
--- a/src/microhttpd/response.c
+++ b/src/microhttpd/response.c
@@ -702,6 +702,7 @@ MHD_response_execute_upgrade_ (struct MHD_Response *response,
702 connection->read_buffer_offset = 0; 702 connection->read_buffer_offset = 0;
703 response->upgrade_handler (response->upgrade_handler_cls, 703 response->upgrade_handler (response->upgrade_handler_cls,
704 connection, 704 connection,
705 connection->con_cls,
705 connection->read_buffer, 706 connection->read_buffer,
706 rbo, 707 rbo,
707 urh->app_socket, 708 urh->app_socket,
diff --git a/src/microhttpd/test_upgrade.c b/src/microhttpd/test_upgrade.c
index 5251c6bc..2288d927 100644
--- a/src/microhttpd/test_upgrade.c
+++ b/src/microhttpd/test_upgrade.c
@@ -177,6 +177,7 @@ recv_all (MHD_socket sock,
177 * @param connection original HTTP connection handle, 177 * @param connection original HTTP connection handle,
178 * giving the function a last chance 178 * giving the function a last chance
179 * to inspect the original HTTP request 179 * to inspect the original HTTP request
180 * @param con_cls last value left in `*con_cls` in the `MHD_AccessHandlerCallback`
180 * @param extra_in if we happened to have read bytes after the 181 * @param extra_in if we happened to have read bytes after the
181 * HTTP header already (because the client sent 182 * HTTP header already (because the client sent
182 * more than the HTTP header of the request before 183 * more than the HTTP header of the request before
@@ -192,12 +193,13 @@ recv_all (MHD_socket sock,
192 * may not work as expected (as the socket could be from a 193 * may not work as expected (as the socket could be from a
193 * socketpair() or a TCP-loopback) 194 * socketpair() or a TCP-loopback)
194 * @param urh argument for #MHD_upgrade_action()s on this @a connection. 195 * @param urh argument for #MHD_upgrade_action()s on this @a connection.
195 * Applications must eventually use this callback to perform the 196 * Applications must eventually use this function to perform the
196 * close() action on the @a sock. 197 * close() action on the @a sock.
197 */ 198 */
198static void 199static void
199upgrade_cb (void *cls, 200upgrade_cb (void *cls,
200 struct MHD_Connection *connection, 201 struct MHD_Connection *connection,
202 void *con_cls,
201 const char *extra_in, 203 const char *extra_in,
202 size_t extra_in_size, 204 size_t extra_in_size,
203 MHD_socket sock, 205 MHD_socket sock,