5 files changed, 2628 insertions, 0 deletions

diff --git a/doc/chapters/bibliography.inc b/doc/chapters/bibliography.inc
index cc288bc0..bdaa6187 100644
--- a/doc/chapters/bibliography.inc
+++ b/doc/chapters/bibliography.inc
@@ -16,6 +16,9 @@ All referenced RFCs can be found on the website of @emph{The Internet Engineerin
 @emph{RFC 2617}: Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P.,
 Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999.
 
+@item
+@emph{RFC 6455}: Fette, I., Melnikov, A., "The WebSocket Protocol", RFC 6455, December 2011.
+
 
 @item 
 A well--structured @emph{HTML} reference can be found on
diff --git a/doc/chapters/websocket.inc b/doc/chapters/websocket.inc
new file mode 100644
index 00000000..a480fd13
--- /dev/null
+++ b/doc/chapters/websocket.inc
@@ -0,0 +1,886 @@
+Websockets are a genuine way to implement push notifications,
+where the server initiates the communication while the client can be idle.
+Usually a HTTP communication is half-duplex and always requested by the client,
+but websockets are full-duplex and only initialized by the client.
+In the further communication both sites can use the websocket at any time
+to send data to the other site.
+
+To initialize a websocket connection the client sends a special HTTP request
+to the server and initializes
+a handshake between client and server which switches from the HTTP protocol
+to the websocket protocol.
+Thus both the server as well as the client must support websockets.
+If proxys are used, they must support websockets too.
+In this chapter we take a look on server and client, but with a focus on
+the server with @emph{libmicrohttpd}.
+
+Since version 0.9.52 @emph{libmicrohttpd} supports upgrading requests,
+which is required for switching from the HTTP protocol.
+Since version 0.9.74 the library @emph{libmicrohttpd_ws} has been added
+to support the websocket protocol.
+
+@heading Upgrading connections with libmicrohttpd
+
+To support websockets we need to enable upgrading of HTTP connections first.
+This is done by passing the flag @code{MHD_ALLOW_UPGRADE} to
+@code{MHD_start_daemon()}.
+
+
+@verbatim
+daemon = MHD_start_daemon (MHD_USE_INTERNAL_POLLING_THREAD |
+                           MHD_USE_THREAD_PER_CONNECTION |
+                           MHD_ALLOW_UPGRADE |
+                           MHD_USE_ERROR_LOG,
+                           PORT, NULL, NULL,
+                           &access_handler, NULL,
+                           MHD_OPTION_END);
+@end verbatim
+@noindent
+
+
+The next step is to turn a specific request into an upgraded connection.
+This done in our @code{access_handler} by calling
+@code{MHD_create_response_for_upgrade()}.
+An @code{upgrade_handler} will be passed to perform the low-level actions
+on the socket.
+
+@emph{Please note that the socket here is just a regular socket as provided
+by the operating system.
+To use it as a websocket, some more steps from the following
+chapters are required.}
+
+
+@verbatim
+static enum MHD_Result
+access_handler (void *cls,
+                struct MHD_Connection *connection,
+                const char *url,
+                const char *method,
+                const char *version,
+                const char *upload_data,
+                size_t *upload_data_size,
+                void **ptr)
+{
+  /* ... */
+  /* some code to decide whether to upgrade or not */
+  /* ... */
+
+  /* create the response for upgrade */
+  response = MHD_create_response_for_upgrade (&upgrade_handler,
+                                              NULL);
+
+  /* ... */
+  /* additional headers, etc. */
+  /* ... */
+
+  ret = MHD_queue_response (connection,
+                            MHD_HTTP_SWITCHING_PROTOCOLS,
+                            response);
+  MHD_destroy_response (response);
+
+  return ret;
+}
+@end verbatim
+@noindent
+
+
+In the @code{upgrade_handler} we receive the low-level socket,
+which is used for the communication with the specific client.
+In addition to the low-level socket we get:
+@itemize @bullet
+@item
+Some data, which has been read too much while @emph{libmicrohttpd} was
+switching the protocols.
+This value is usually empty, because it would mean that the client
+has sent data before the handshake was complete.
+
+@item
+A @code{struct MHD_UpgradeResponseHandle} which is used to perform
+special actions like closing, corking or uncorking the socket.
+These commands are executed by passing the handle
+to @code{MHD_upgrade_action()}.
+
+
+@end itemize
+
+Depending of the flags specified while calling @code{MHD_start_deamon()}
+our @code{upgrade_handler} is either executed in the same thread
+as our deamon or in a thread specific for each connection.
+If it is executed in the same thread then @code{upgrade_handler} is
+a blocking call for our webserver and
+we should finish it as fast as possible (i. e. by creating a thread and
+passing the information there).
+If @code{MHD_USE_THREAD_PER_CONNECTION} was passed to
+@code{MHD_start_daemon()} then a separate thread is used and
+thus our @code{upgrade_handler} needs not to start a separate thread.
+
+An @code{upgrade_handler}, which is called with a separate thread
+per connection, could look like this:
+
+
+@verbatim
+static void
+upgrade_handler (void *cls,
+                 struct MHD_Connection *connection,
+                 void *con_cls,
+                 const char *extra_in,
+                 size_t extra_in_size,
+                 MHD_socket fd,
+                 struct MHD_UpgradeResponseHandle *urh)
+{
+  /* ... */
+  /* do something with the socket `fd` like `recv()` or `send()` */
+  /* ... */
+
+  /* close the socket when it is not needed anymore */
+  MHD_upgrade_action (urh,
+                      MHD_UPGRADE_ACTION_CLOSE);
+}
+@end verbatim
+@noindent
+
+
+This is all you need to know for upgrading connections
+with @emph{libmicrohttpd}.
+The next chapters focus on using the websocket protocol
+with @emph{libmicrohttpd_ws}.
+
+
+@heading Websocket handshake with libmicrohttpd_ws
+
+To request a websocket connection the client must send
+the following information with the HTTP request:
+
+@itemize @bullet
+@item
+A @code{GET} request must be sent.
+
+@item
+The version of the HTTP protocol must be 1.1 or higher.
+
+@item
+A @code{Host} header field must be sent
+
+@item
+A @code{Upgrade} header field containing the keyword "websocket"
+(case-insensitive).
+Please note that the client could pass multiple protocols separated by comma.
+
+@item
+A @code{Connection} header field that includes the token "Upgrade"
+(case-insensitive).
+Please note that the client could pass multiple tokens separated by comma.
+
+@item
+A @code{Sec-WebSocket-Key} header field with a base64-encoded value.
+The decoded the value is 16 bytes long
+and has been generated randomly by the client.
+
+@item
+A @code{Sec-WebSocket-Version} header field with the value "13".
+
+@end itemize
+
+
+Optionally the client can also send the following information:
+
+
+@itemize @bullet
+@item
+A @code{Origin} header field can be used to determine the source
+of the client (i. e. the website).
+
+@item
+A @code{Sec-WebSocket-Protocol} header field can contain a list
+of supported protocols by the client, which can be sent over the websocket.
+
+@item
+A @code{Sec-WebSocket-Extensions} header field which may contain extensions
+to the websocket protocol. The extensions must be registered by IANA.
+
+@end itemize
+
+
+A valid example request from the client could look like this:
+
+
+@verbatim
+GET /chat HTTP/1.1
+Host: server.example.com
+Upgrade: websocket
+Connection: Upgrade
+Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
+Sec-WebSocket-Version: 13
+@end verbatim
+@noindent
+
+
+To complete the handshake the server must respond with
+some specific response headers:
+
+@itemize @bullet
+@item
+The HTTP response code @code{101 Switching Protocols} must be answered.
+
+@item
+An @code{Upgrade} header field containing the value "websocket" must be sent.
+
+@item
+A @code{Connection} header field containing the value "Upgrade" must be sent.
+
+@item
+A @code{Sec-WebSocket-Accept} header field containing a value, which
+has been calculated from the @code{Sec-WebSocket-Key} request header field,
+must be sent.
+
+@end itemize
+
+
+Optionally the server may send following headers:
+
+
+@itemize @bullet
+@item
+A @code{Sec-WebSocket-Protocol} header field containing a protocol
+of the list specified in the corresponding request header field.
+
+@item
+A @code{Sec-WebSocket-Extension} header field containing all used extensions
+of the list specified in the corresponding request header field.
+
+@end itemize
+
+
+A valid websocket HTTP response could look like this:
+
+@verbatim
+HTTP/1.1 101 Switching Protocols
+Upgrade: websocket
+Connection: Upgrade
+Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
+@end verbatim
+@noindent
+
+
+To upgrade a connection to a websocket the @emph{libmicrohttpd_ws} provides
+some helper functions for the @code{access_handler} callback function:
+
+@itemize @bullet
+@item
+@code{MHD_websocket_check_http_version()} checks whether the HTTP version
+is 1.1 or above.
+
+@item
+@code{MHD_websocket_check_connection_header()} checks whether the value
+of the @code{Connection} request header field contains
+an "Upgrade" token (case-insensitive).
+
+@item
+@code{MHD_websocket_check_upgrade_header()} checks whether the value
+of the @code{Upgrade} request header field contains
+the "websocket" keyword (case-insensitive).
+
+@item
+@code{MHD_websocket_check_version_header()} checks whether the value
+of the @code{Sec-WebSocket-Version} request header field is "13".
+
+@item
+@code{MHD_websocket_create_accept_header()} takes the value from
+the @code{Sec-WebSocket-Key} request header and calculates the value
+for the @code{Sec-WebSocket-Accept} response header field.
+
+@end itemize
+
+
+The @code{access_handler} example of the previous chapter can now be
+extended with these helper functions to perform the websocket handshake:
+
+@verbatim
+static enum MHD_Result
+access_handler (void *cls,
+                struct MHD_Connection *connection,
+                const char *url,
+                const char *method,
+                const char *version,
+                const char *upload_data,
+                size_t *upload_data_size,
+                void **ptr)
+{
+  static int aptr;
+  struct MHD_Response *response;
+  int ret;
+
+  (void) cls;               /* Unused. Silent compiler warning. */
+  (void) upload_data;       /* Unused. Silent compiler warning. */
+  (void) upload_data_size;  /* Unused. Silent compiler warning. */
+
+  if (0 != strcmp (method, "GET"))
+    return MHD_NO;              /* unexpected method */
+  if (&aptr != *ptr)
+  {
+    /* do never respond on first call */
+    *ptr = &aptr;
+    return MHD_YES;
+  }
+  *ptr = NULL;                  /* reset when done */
+
+  if (0 == strcmp (url, "/"))
+  {
+    /* Default page for visiting the server */
+    struct MHD_Response *response = MHD_create_response_from_buffer (
+                                      strlen (PAGE),
+                                      PAGE,
+                                      MHD_RESPMEM_PERSISTENT);
+    ret = MHD_queue_response (connection,
+                              MHD_HTTP_OK,
+                              response);
+    MHD_destroy_response (response);
+  }
+  else if (0 == strcmp (url, "/chat"))
+  {
+    char is_valid = 1;
+    const char* value = NULL;
+    char sec_websocket_accept[29];
+
+    if (0 != MHD_websocket_check_http_version (version))
+    {
+      is_valid = 0;
+    }
+    value = MHD_lookup_connection_value (connection,
+                                         MHD_HEADER_KIND,
+                                         MHD_HTTP_HEADER_CONNECTION);
+    if (0 != MHD_websocket_check_connection_header (value))
+    {
+      is_valid = 0;
+    }
+    value = MHD_lookup_connection_value (connection,
+                                         MHD_HEADER_KIND,
+                                         MHD_HTTP_HEADER_UPGRADE);
+    if (0 != MHD_websocket_check_upgrade_header (value))
+    {
+      is_valid = 0;
+    }
+    value = MHD_lookup_connection_value (connection,
+                                         MHD_HEADER_KIND,
+                                         MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION);
+    if (0 != MHD_websocket_check_version_header (value))
+    {
+      is_valid = 0;
+    }
+    value = MHD_lookup_connection_value (connection,
+                                         MHD_HEADER_KIND,
+                                         MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY);
+    if (0 != MHD_websocket_create_accept_header (value, sec_websocket_accept))
+    {
+      is_valid = 0;
+    }
+
+    if (1 == is_valid)
+    {
+      /* upgrade the connection */
+      response = MHD_create_response_for_upgrade (&upgrade_handler,
+                                                  NULL);
+      MHD_add_response_header (response,
+                               MHD_HTTP_HEADER_CONNECTION,
+                               "Upgrade");
+      MHD_add_response_header (response,
+                               MHD_HTTP_HEADER_UPGRADE,
+                               "websocket");
+      MHD_add_response_header (response,
+                               MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT,
+                               sec_websocket_accept);
+      ret = MHD_queue_response (connection,
+                                MHD_HTTP_SWITCHING_PROTOCOLS,
+                                response);
+      MHD_destroy_response (response);
+    }
+    else
+    {
+      /* return error page */
+      struct MHD_Response*response = MHD_create_response_from_buffer (
+                                       strlen (PAGE_INVALID_WEBSOCKET_REQUEST),
+                                       PAGE_INVALID_WEBSOCKET_REQUEST,
+                                       MHD_RESPMEM_PERSISTENT);
+      ret = MHD_queue_response (connection,
+                                MHD_HTTP_BAD_REQUEST,
+                                response);
+      MHD_destroy_response (response);
+    }
+  }
+  else
+  {
+    struct MHD_Response*response = MHD_create_response_from_buffer (
+                                     strlen (PAGE_NOT_FOUND),
+                                     PAGE_NOT_FOUND,
+                                     MHD_RESPMEM_PERSISTENT);
+    ret = MHD_queue_response (connection,
+                              MHD_HTTP_NOT_FOUND,
+                              response);
+    MHD_destroy_response (response);
+  }
+
+  return ret;
+}
+@end verbatim
+@noindent
+
+Please note that we skipped the check of the Host header field here,
+because we don't know the host for this example.
+
+@heading Decoding/encoding the websocket protocol with libmicrohttpd_ws
+
+Once the websocket connection is established you can receive/send frame data
+with the low-level socket functions @code{recv()} and @code{send()}.
+The frame data which goes over the low-level socket is encoded according
+to the websocket protocol.
+To use received payload data, you need to decode the frame data first.
+To send payload data, you need to encode it into frame data first.
+
+@emph{libmicrohttpd_ws} provides serveral functions for encoding of
+payload data and decoding of frame data:
+
+@itemize @bullet
+@item
+@code{MHD_websocket_decode()} decodes received frame data.
+The payload data may be of any kind, depending upon what the client has sent.
+So this decode function is used for all kind of frames and returns
+the frame type along with the payload data.
+
+@item
+@code{MHD_websocket_encode_text()} encodes text.
+The text must be encoded with UTF-8.
+
+@item
+@code{MHD_websocket_encode_binary()} encodes binary data.
+
+@item
+@code{MHD_websocket_encode_ping()} encodes a ping request to
+check whether the websocket is still valid and to test latency.
+
+@item
+@code{MHD_websocket_encode_ping()} encodes a pong response to
+answer a received ping request.
+
+@item
+@code{MHD_websocket_encode_close()} encodes a close request.
+
+@item
+@code{MHD_websocket_free()} frees data returned by the encode/decode functions.
+
+@end itemize
+
+Since you could receive or send fragmented data (i. e. due to a too
+small buffer passed to @code{recv}) all of these encode/decode
+functions require a pointer to a @code{struct MHD_WebSocketStream} passed
+as argument.
+In this structure @emph{libmicrohttpd_ws} stores information
+about encoding/decoding of the particular websocket.
+For each websocket you need a unique @code{struct MHD_WebSocketStream}
+to encode/decode with this library.
+
+To create or destroy @code{struct MHD_WebSocketStream}
+we have additional functions:
+
+@itemize @bullet
+@item
+@code{MHD_websocket_stream_init()} allocates and initializes
+a new @code{struct MHD_WebSocketStream}.
+You can specify some options here to alter the behavior of the websocket stream.
+
+@item
+@code{MHD_websocket_stream_free()} frees a previously allocated
+@code{struct MHD_WebSocketStream}.
+
+@end itemize
+
+With these encode/decode functions we can improve our @code{upgrade_handler}
+callback function from an earlier example to a working websocket:
+
+
+@verbatim
+static void
+upgrade_handler (void *cls,
+                 struct MHD_Connection *connection,
+                 void *con_cls,
+                 const char *extra_in,
+                 size_t extra_in_size,
+                 MHD_socket fd,
+                 struct MHD_UpgradeResponseHandle *urh)
+{
+  /* make the socket blocking (operating-system-dependent code) */
+  make_blocking (fd);
+
+  /* create a websocket stream for this connection */
+  struct MHD_WebSocketStream* ws;
+  int result = MHD_websocket_stream_init (&ws,
+                                          0,
+                                          0);
+  if (0 != result)
+  {
+    /* Couldn't create the websocket stream.
+     * So we close the socket and leave
+     */
+    MHD_upgrade_action (urh,
+                        MHD_UPGRADE_ACTION_CLOSE);
+    return;
+  }
+
+  /* Let's wait for incoming data */
+  const size_t buf_len = 256;
+  char buf[buf_len];
+  ssize_t got;
+  while (MHD_WEBSOCKET_VALIDITY_VALID == MHD_websocket_stream_is_valid (ws))
+  {
+    got = recv (fd,
+                buf,
+                buf_len,
+                0);
+    if (0 >= got)
+    {
+      /* the TCP/IP socket has been closed */
+      break;
+    }
+
+    /* parse the entire received data */
+    size_t buf_offset = 0;
+    while (buf_offset < (size_t) got)
+    {
+      size_t new_offset = 0;
+      char *frame_data = NULL;
+      size_t frame_len  = 0;
+      int status = MHD_websocket_decode (ws,
+                                         buf + buf_offset,
+                                         ((size_t) got) - buf_offset,
+                                         &new_offset,
+                                         &frame_data,
+                                         &frame_len);
+      if (0 > status)
+      {
+        /* an error occurred and the connection must be closed */
+        if (NULL != frame_data)
+        {
+          MHD_websocket_free (ws, frame_data);
+        }
+        break;
+      }
+      else
+      {
+        buf_offset += new_offset;
+        if (0 < status)
+        {
+          /* the frame is complete */
+          switch (status)
+          {
+          case MHD_WEBSOCKET_STATUS_TEXT_FRAME:
+            /* The client has sent some text.
+             * We will display it and answer with a text frame.
+             */
+            if (NULL != frame_data)
+            {
+              printf ("Received message: %s\n", frame_data);
+              MHD_websocket_free (ws, frame_data);
+              frame_data = NULL;
+            }
+            result = MHD_websocket_encode_text (ws,
+                                                "Hello",
+                                                5,  /* length of "Hello" */
+                                                0,
+                                                &frame_data,
+                                                &frame_len,
+                                                NULL);
+            if (0 == result)
+            {
+              send_all (fd,
+                        frame_data,
+                        frame_len);
+            }
+            break;
+
+          case MHD_WEBSOCKET_STATUS_CLOSE_FRAME:
+            /* if we receive a close frame, we will respond with one */
+            MHD_websocket_free (ws,
+                                frame_data);
+            frame_data = NULL;
+
+            result = MHD_websocket_encode_close (ws,
+                                                 0,
+                                                 NULL,
+                                                 0,
+                                                 &frame_data,
+                                                 &frame_len);
+            if (0 == result)
+            {
+              send_all (fd,
+                        frame_data,
+                        frame_len);
+            }
+            break;
+
+          case MHD_WEBSOCKET_STATUS_PING_FRAME:
+            /* if we receive a ping frame, we will respond */
+            /* with the corresponding pong frame */
+            {
+              char *pong = NULL;
+              size_t pong_len = 0;
+              result = MHD_websocket_encode_pong (ws,
+                                                  frame_data,
+                                                  frame_len,
+                                                  &pong,
+                                                  &pong_len);
+              if (0 == result)
+              {
+                send_all (fd,
+                          pong,
+                          pong_len);
+              }
+              MHD_websocket_free (ws,
+                                  pong);
+            }
+            break;
+
+          default:
+            /* Other frame types are ignored
+             * in this minimal example.
+             * This is valid, because they become
+             * automatically skipped if we receive them unexpectedly
+             */
+            break;
+          }
+        }
+        if (NULL != frame_data)
+        {
+          MHD_websocket_free (ws, frame_data);
+        }
+      }
+    }
+  }
+
+  /* free the websocket stream */
+  MHD_websocket_stream_free (ws);
+
+  /* close the socket when it is not needed anymore */
+  MHD_upgrade_action (urh,
+                      MHD_UPGRADE_ACTION_CLOSE);
+}
+
+/* This helper function is used for the case that
+ * we need to resend some data
+ */
+static void
+send_all (MHD_socket fd,
+          const char *buf,
+          size_t len)
+{
+  ssize_t ret;
+  size_t off;
+
+  for (off = 0; off < len; off += ret)
+  {
+    ret = send (fd,
+                &buf[off],
+                (int) (len - off),
+                0);
+    if (0 > ret)
+    {
+      if (EAGAIN == errno)
+      {
+        ret = 0;
+        continue;
+      }
+      break;
+    }
+    if (0 == ret)
+      break;
+  }
+}
+
+/* This helper function contains operating-system-dependent code and
+ * is used to make a socket blocking.
+ */
+static void
+make_blocking (MHD_socket fd)
+{
+#if defined(MHD_POSIX_SOCKETS)
+  int flags;
+
+  flags = fcntl (fd, F_GETFL);
+  if (-1 == flags)
+    return;
+  if ((flags & ~O_NONBLOCK) != flags)
+    if (-1 == fcntl (fd, F_SETFL, flags & ~O_NONBLOCK))
+      abort ();
+#elif defined(MHD_WINSOCK_SOCKETS)
+  unsigned long flags = 0;
+
+  ioctlsocket (fd, FIONBIO, &flags);
+#endif /* MHD_WINSOCK_SOCKETS */
+}
+
+@end verbatim
+@noindent
+
+
+Please note that the websocket in this example is only half-duplex.
+It waits until the blocking @code{recv()} call returns and
+only does then something.
+In this example all frame types are decoded by @emph{libmicrohttpd_ws},
+but we only do something when a text, ping or close frame is received.
+Binary and pong frames are ignored in our code.
+This is legit, because the server is only required to implement at
+least support for ping frame or close frame (the other frame types
+could be skipped in theory, because they don't require an answer).
+The pong frame doesn't require an answer and whether text frames or
+binary frames get an answer simply belongs to your server application.
+So this is a valid minimal example.
+
+Until this point you've learned everything you need to basically
+use websockets with @emph{libmicrohttpd} and @emph{libmicrohttpd_ws}.
+These libraries offer much more functions for some specific cases.
+
+
+The further chapters of this tutorial focus on some specific problems
+and the client site programming.
+
+
+@heading Using full-duplex websockets
+
+To use full-duplex websockets you can simply create two threads
+per websocket connection.
+One of these threads is used for receiving data with
+a blocking @code{recv()} call and the other thread is triggered
+by the application internal codes and sends the data.
+
+A full-duplex websocket example is implemented in the example file
+@code{websocket_chatserver_example.c}.
+
+@heading Error handling
+
+The most functions of @emph{libmicrohttpd_ws} return a value
+of @code{enum MHD_WEBSOCKET_STATUS}.
+The values of this enumeration can be converted into an integer
+and have an easy interpretation:
+
+@itemize @bullet
+@item
+If the value is less than zero an error occurred and the call has failed.
+Check the enumeration values for more specific information.
+
+@item
+If the value is equal to zero, the call succeeded.
+
+@item
+If the value is greater than zero, the call succeeded and the value
+specifies the decoded frame type.
+Currently positive values are only returned by @code{MHD_websocket_decode()}
+(of the functions with this return enumeration type).
+
+@end itemize
+
+A websocket stream can also get broken when invalid frame data is received.
+Also the other site could send a close frame which puts the stream into
+a state where it may not be used for regular communication.
+Whether a stream has become broken, can be checked with
+@code{MHD_websocket_stream_is_valid()}.
+
+
+@heading Fragmentation
+
+In addition to the regular TCP/IP fragmentation the websocket protocol also
+supports fragmentation.
+Fragmentation could be used for continuous payload data such as video data
+from a webcam.
+Whether or not you want to receive fragmentation is specified upon
+initialization of the websocket stream.
+If you pass @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS} in the flags parameter
+of @code{MHD_websocket_stream_init()} then you can receive fragments.
+If you don't pass this flag (in the most cases you just pass zero as flags)
+then you don't want to handle fragments on your own.
+@emph{libmicrohttpd_ws} removes then the fragmentation for you
+in the background.
+You only get the completely assembled frames.
+
+Upon encoding you specify whether or not you want to create a fragmented frame
+by passing a flag to the corresponding encode function.
+Only @code{MHD_websocket_encode_text()} and @code{MHD_websocket_encode_binary()}
+can be used for fragmentation, because the other frame types may
+not be fragmented.
+Encoding fragmented frames is independent of
+the @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS} flag upon initialization.
+
+@heading Quick guide to websockets in JavaScript
+
+Websockets are supported in all modern web browsers.
+You initialize a websocket connection by creating an instance of
+the @code{WebSocket} class provided by the web browser.
+
+There are some simple rules for using websockets in the browser:
+
+@itemize @bullet
+@item
+When you initialize the instance of the websocket class you must pass an URL.
+The URL must either start with @code{ws://}
+(for not encrypted websocket protocol) or @code{wss://}
+(for TLS-encrypted websocket protocol).
+
+@strong{IMPORTANT:} If your website is accessed via @code{https://}
+then you are in a security context, which means that you are only allowed to
+access other secure protocols.
+So you can only use @code{wss://} for websocket connections then.
+If you try to @code{ws://} instead then your websocket connection will
+automatically fail.
+
+@item
+The WebSocket class uses events to handle the receiving of data.
+JavaScript is per definition a single-threaded language so
+the receiving events will never overlap.
+Sending is done directly by calling a method of the instance of
+the WebSocket class.
+
+@end itemize
+
+
+Here is a short example for receiving/sending data to the same host
+as the website is running on:
+
+@verbatim
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="UTF-8">
+<title>Websocket Demo</title>
+<script>
+
+let url = 'ws' + (window.location.protocol === 'https:' ? 's' : '') + '://' +
+          window.location.host + '/chat';
+let socket = null;
+
+window.onload = function(event) {
+  socket = new WebSocket(url);
+  socket.onopen = function(event) {
+    document.write('The websocket connection has been established.<br>');
+
+    // Send some text
+    socket.send('Hello from JavaScript!');
+  }
+
+  socket.onclose = function(event) {
+    document.write('The websocket connection has been closed.<br>');
+  }
+
+  socket.onerror = function(event) {
+    document.write('An error occurred during the websocket communication.<br>');
+  }
+
+  socket.onmessage = function(event) {
+    document.write('Websocket message received: ' + event.data + '<br>');
+  }
+}
+
+</script>
+</head>
+<body>
+</body>
+</html>
+
+@end verbatim
+@noindent
diff --git a/doc/examples/websocket.c b/doc/examples/websocket.c
new file mode 100644
index 00000000..39995479
--- /dev/null
+++ b/doc/examples/websocket.c
@@ -0,0 +1,446 @@
+/* Feel free to use this example code in any way
+   you see fit (Public Domain) */
+
+#include <sys/types.h>
+#ifndef _WIN32
+#include <sys/select.h>
+#include <sys/socket.h>
+#include <fcntl.h>
+#else
+#include <winsock2.h>
+#endif
+#include <microhttpd.h>
+#include <microhttpd_ws.h>
+#include <time.h>
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <errno.h>
+
+#define PORT 80
+
+#define PAGE \
+  "<!DOCTYPE html>\n" \
+  "<html>\n" \
+  "<head>\n" \
+  "<meta charset=\"UTF-8\">\n" \
+  "<title>Websocket Demo</title>\n" \
+  "<script>\n" \
+  "\n" \
+  "let url = 'ws' + (window.location.protocol === 'https:' ? 's' : '')" \
+    "  + '://' +\n" \
+  "          window.location.host + '/chat';\n" \
+  "let socket = null;\n" \
+  "\n" \
+  "window.onload = function(event) {\n" \
+  "  socket = new WebSocket(url);\n" \
+  "  socket.onopen = function(event) {\n" \
+  "    document.write('The websocket connection has been " \
+    "established.<br>');\n" \
+  "\n" \
+  "    // Send some text\n" \
+  "    socket.send('Hello from JavaScript!');\n" \
+  "  }\n" \
+  "\n" \
+  "  socket.onclose = function(event) {\n" \
+  "    document.write('The websocket connection has been closed.<br>');\n" \
+  "  }\n" \
+  "\n" \
+  "  socket.onerror = function(event) {\n" \
+  "    document.write('An error occurred during the websocket " \
+    "communication.<br>');\n" \
+  "  }\n" \
+  "\n" \
+  "  socket.onmessage = function(event) {\n" \
+  "    document.write('Websocket message received: ' + " \
+    "event.data + '<br>');\n" \
+  "  }\n" \
+  "}\n" \
+  "\n" \
+  "</script>\n" \
+  "</head>\n" \
+  "<body>\n" \
+  "</body>\n" \
+  "</html>"
+
+#define PAGE_NOT_FOUND \
+  "404 Not Found"
+
+#define PAGE_INVALID_WEBSOCKET_REQUEST \
+  "Invalid WebSocket request!"
+
+static void
+send_all (MHD_socket fd,
+          const char *buf,
+          size_t len);
+static void
+make_blocking (MHD_socket fd);
+
+static void
+upgrade_handler (void *cls,
+                 struct MHD_Connection *connection,
+                 void *con_cls,
+                 const char *extra_in,
+                 size_t extra_in_size,
+                 MHD_socket fd,
+                 struct MHD_UpgradeResponseHandle *urh)
+{
+  /* make the socket blocking (operating-system-dependent code) */
+  make_blocking (fd);
+
+  /* create a websocket stream for this connection */
+  struct MHD_WebSocketStream* ws;
+  int result = MHD_websocket_stream_init (&ws,
+                                          0,
+                                          0);
+  if (0 != result)
+  {
+    /* Couldn't create the websocket stream.
+     * So we close the socket and leave
+     */
+    MHD_upgrade_action (urh,
+                        MHD_UPGRADE_ACTION_CLOSE);
+    return;
+  }
+
+  /* Let's wait for incoming data */
+  const size_t buf_len = 256;
+  char buf[buf_len];
+  ssize_t got;
+  while (MHD_WEBSOCKET_VALIDITY_VALID == MHD_websocket_stream_is_valid (ws))
+  {
+    got = recv (fd,
+                buf,
+                buf_len,
+                0);
+    if (0 >= got)
+    {
+      /* the TCP/IP socket has been closed */
+      break;
+    }
+
+    /* parse the entire received data */
+    size_t buf_offset = 0;
+    while (buf_offset < (size_t) got)
+    {
+      size_t new_offset = 0;
+      char *frame_data = NULL;
+      size_t frame_len  = 0;
+      int status = MHD_websocket_decode (ws,
+                                         buf + buf_offset,
+                                         ((size_t) got) - buf_offset,
+                                         &new_offset,
+                                         &frame_data,
+                                         &frame_len);
+      if (0 > status)
+      {
+        /* an error occurred and the connection must be closed */
+        if (NULL != frame_data)
+        {
+          MHD_websocket_free (ws, frame_data);
+        }
+        break;
+      }
+      else
+      {
+        buf_offset += new_offset;
+        if (0 < status)
+        {
+          /* the frame is complete */
+          switch (status)
+          {
+          case MHD_WEBSOCKET_STATUS_TEXT_FRAME:
+            /* The client has sent some text.
+             * We will display it and answer with a text frame.
+             */
+            if (NULL != frame_data)
+            {
+              printf ("Received message: %s\n", frame_data);
+              MHD_websocket_free (ws, frame_data);
+              frame_data = NULL;
+            }
+            result = MHD_websocket_encode_text (ws,
+                                                "Hello",
+                                                5,  /* length of "Hello" */
+                                                0,
+                                                &frame_data,
+                                                &frame_len,
+                                                NULL);
+            if (0 == result)
+            {
+              send_all (fd,
+                        frame_data,
+                        frame_len);
+            }
+            break;
+
+          case MHD_WEBSOCKET_STATUS_CLOSE_FRAME:
+            /* if we receive a close frame, we will respond with one */
+            MHD_websocket_free (ws,
+                                frame_data);
+            frame_data = NULL;
+
+            result = MHD_websocket_encode_close (ws,
+                                                 0,
+                                                 NULL,
+                                                 0,
+                                                 &frame_data,
+                                                 &frame_len);
+            if (0 == result)
+            {
+              send_all (fd,
+                        frame_data,
+                        frame_len);
+            }
+            break;
+
+          case MHD_WEBSOCKET_STATUS_PING_FRAME:
+            /* if we receive a ping frame, we will respond */
+            /* with the corresponding pong frame */
+            {
+              char *pong = NULL;
+              size_t pong_len = 0;
+              result = MHD_websocket_encode_pong (ws,
+                                                  frame_data,
+                                                  frame_len,
+                                                  &pong,
+                                                  &pong_len);
+              if (0 == result)
+              {
+                send_all (fd,
+                          pong,
+                          pong_len);
+              }
+              MHD_websocket_free (ws,
+                                  pong);
+            }
+            break;
+
+          default:
+            /* Other frame types are ignored
+             * in this minimal example.
+             * This is valid, because they become
+             * automatically skipped if we receive them unexpectedly
+             */
+            break;
+          }
+        }
+        if (NULL != frame_data)
+        {
+          MHD_websocket_free (ws, frame_data);
+        }
+      }
+    }
+  }
+
+  /* free the websocket stream */
+  MHD_websocket_stream_free (ws);
+
+  /* close the socket when it is not needed anymore */
+  MHD_upgrade_action (urh,
+                      MHD_UPGRADE_ACTION_CLOSE);
+}
+
+/* This helper function is used for the case that
+ * we need to resend some data
+ */
+static void
+send_all (MHD_socket fd,
+          const char *buf,
+          size_t len)
+{
+  ssize_t ret;
+  size_t off;
+
+  for (off = 0; off < len; off += ret)
+  {
+    ret = send (fd,
+                &buf[off],
+                (int) (len - off),
+                0);
+    if (0 > ret)
+    {
+      if (EAGAIN == errno)
+      {
+        ret = 0;
+        continue;
+      }
+      break;
+    }
+    if (0 == ret)
+      break;
+  }
+}
+
+/* This helper function contains operating-system-dependent code and
+ * is used to make a socket blocking.
+ */
+static void
+make_blocking (MHD_socket fd)
+{
+#ifndef _WIN32
+  int flags;
+
+  flags = fcntl (fd, F_GETFL);
+  if (-1 == flags)
+    return;
+  if ((flags & ~O_NONBLOCK) != flags)
+    if (-1 == fcntl (fd, F_SETFL, flags & ~O_NONBLOCK))
+      abort ();
+#else
+  unsigned long flags = 0;
+
+  ioctlsocket (fd, FIONBIO, &flags);
+#endif
+}
+
+static enum MHD_Result
+access_handler (void *cls,
+                struct MHD_Connection *connection,
+                const char *url,
+                const char *method,
+                const char *version,
+                const char *upload_data,
+                size_t *upload_data_size,
+                void **ptr)
+{
+  static int aptr;
+  struct MHD_Response *response;
+  int ret;
+
+  (void) cls;               /* Unused. Silent compiler warning. */
+  (void) upload_data;       /* Unused. Silent compiler warning. */
+  (void) upload_data_size;  /* Unused. Silent compiler warning. */
+
+  if (0 != strcmp (method, "GET"))
+    return MHD_NO;              /* unexpected method */
+  if (&aptr != *ptr)
+  {
+    /* do never respond on first call */
+    *ptr = &aptr;
+    return MHD_YES;
+  }
+  *ptr = NULL;                  /* reset when done */
+
+  if (0 == strcmp (url, "/"))
+  {
+    /* Default page for visiting the server */
+    struct MHD_Response *response = MHD_create_response_from_buffer (
+                                      strlen (PAGE),
+                                      PAGE,
+                                      MHD_RESPMEM_PERSISTENT);
+    ret = MHD_queue_response (connection,
+                              MHD_HTTP_OK,
+                              response);
+    MHD_destroy_response (response);
+  }
+  else if (0 == strcmp (url, "/chat"))
+  {
+    char is_valid = 1;
+    const char* value = NULL;
+    char sec_websocket_accept[29];
+
+    if (0 != MHD_websocket_check_http_version (version))
+    {
+      is_valid = 0;
+    }
+    value = MHD_lookup_connection_value (connection,
+                                         MHD_HEADER_KIND,
+                                         MHD_HTTP_HEADER_CONNECTION);
+    if (0 != MHD_websocket_check_connection_header (value))
+    {
+      is_valid = 0;
+    }
+    value = MHD_lookup_connection_value (connection,
+                                         MHD_HEADER_KIND,
+                                         MHD_HTTP_HEADER_UPGRADE);
+    if (0 != MHD_websocket_check_upgrade_header (value))
+    {
+      is_valid = 0;
+    }
+    value = MHD_lookup_connection_value (connection,
+                                         MHD_HEADER_KIND,
+                                         MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION);
+    if (0 != MHD_websocket_check_version_header (value))
+    {
+      is_valid = 0;
+    }
+    value = MHD_lookup_connection_value (connection,
+                                         MHD_HEADER_KIND,
+                                         MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY);
+    if (0 != MHD_websocket_create_accept_header (value, sec_websocket_accept))
+    {
+      is_valid = 0;
+    }
+
+    if (1 == is_valid)
+    {
+      /* upgrade the connection */
+      response = MHD_create_response_for_upgrade (&upgrade_handler,
+                                                  NULL);
+      MHD_add_response_header (response,
+                               MHD_HTTP_HEADER_CONNECTION,
+                               "Upgrade");
+      MHD_add_response_header (response,
+                               MHD_HTTP_HEADER_UPGRADE,
+                               "websocket");
+      MHD_add_response_header (response,
+                               MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT,
+                               sec_websocket_accept);
+      ret = MHD_queue_response (connection,
+                                MHD_HTTP_SWITCHING_PROTOCOLS,
+                                response);
+      MHD_destroy_response (response);
+    }
+    else
+    {
+      /* return error page */
+      struct MHD_Response*response = MHD_create_response_from_buffer (
+                                       strlen (PAGE_INVALID_WEBSOCKET_REQUEST),
+                                       PAGE_INVALID_WEBSOCKET_REQUEST,
+                                       MHD_RESPMEM_PERSISTENT);
+      ret = MHD_queue_response (connection,
+                                MHD_HTTP_BAD_REQUEST,
+                                response);
+      MHD_destroy_response (response);
+    }
+  }
+  else
+  {
+    struct MHD_Response*response = MHD_create_response_from_buffer (
+                                     strlen (PAGE_NOT_FOUND),
+                                     PAGE_NOT_FOUND,
+                                     MHD_RESPMEM_PERSISTENT);
+    ret = MHD_queue_response (connection,
+                              MHD_HTTP_NOT_FOUND,
+                              response);
+    MHD_destroy_response (response);
+  }
+
+  return ret;
+}
+
+int
+main (int argc,
+      char *const *argv)
+{
+  (void) argc;               /* Unused. Silent compiler warning. */
+  (void) argv;               /* Unused. Silent compiler warning. */
+  struct MHD_Daemon *daemon;
+
+  daemon = MHD_start_daemon (MHD_USE_INTERNAL_POLLING_THREAD |
+                             MHD_USE_THREAD_PER_CONNECTION |
+                             MHD_ALLOW_UPGRADE |
+                             MHD_USE_ERROR_LOG,
+                             PORT, NULL, NULL,
+                             &access_handler, NULL,
+                             MHD_OPTION_END);
+
+  if (NULL == daemon)
+    return 1;
+  (void) getc (stdin);
+
+  MHD_stop_daemon (daemon);
+
+  return 0;
+}
diff --git a/doc/libmicrohttpd-tutorial.texi b/doc/libmicrohttpd-tutorial.texi
index de040fe8..7d3cd23a 100644
--- a/doc/libmicrohttpd-tutorial.texi
+++ b/doc/libmicrohttpd-tutorial.texi
@@ -68,6 +68,7 @@ Free Documentation License".
 * Improved processing of POST data::
 * Session management::
 * Adding a layer of security::
+* Websockets::
 * Bibliography::
 * License text::
 * Example programs::
@@ -109,6 +110,10 @@ Free Documentation License".
 @chapter Adding a layer of security
 @include chapters/tlsauthentication.inc
 
+@node Websockets
+@chapter Websockets
+@include chapters/websocket.inc
+
 @node Bibliography
 @appendix Bibliography
 @include chapters/bibliography.inc
@@ -128,6 +133,7 @@ Free Documentation License".
 * largepost.c::
 * sessions.c::
 * tlsauthentication.c::
+* websocket.c::
 @end menu
 
 @node hellobrowser.c
@@ -178,4 +184,10 @@ Free Documentation License".
 @verbatiminclude examples/tlsauthentication.c
 @end smalldisplay
 
+@node websocket.c
+@section websocket.c
+@smalldisplay
+@verbatiminclude examples/websocket.c
+@end smalldisplay
+
 @bye
diff --git a/doc/libmicrohttpd.texi b/doc/libmicrohttpd.texi
index 8e275a3b..a6bd12eb 100644
--- a/doc/libmicrohttpd.texi
+++ b/doc/libmicrohttpd.texi
@@ -67,6 +67,7 @@ Free Documentation License".
 * microhttpd-post::             Adding a @code{POST} processor.
 * microhttpd-info::             Obtaining and modifying status information.
 * microhttpd-util::             Utilities.
+* microhttpd-websocket::        Websockets.
 
 Appendices
 
@@ -1246,6 +1247,493 @@ list.
 @end deftp
 
 
+@deftp {Enumeration} MHD_WEBSOCKET_FLAG
+@cindex websocket
+Options for the MHD websocket stream.
+
+This is used for initialization of a websocket stream when calling
+@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2} and
+alters the behavior of the websocket stream.
+
+Note that websocket streams are only available if you include the header file
+@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
+
+@table @code
+@item MHD_WEBSOCKET_FLAG_SERVER
+The websocket stream is initialized in server mode (default).
+Thus all outgoing payload will not be masked.
+All incoming payload must be masked.
+
+This flag cannot be used together with @code{MHD_WEBSOCKET_FLAG_CLIENT}.
+
+@item MHD_WEBSOCKET_FLAG_CLIENT
+The websocket stream is initialized in client mode.
+You will usually never use that mode in combination with @emph{libmicrohttpd},
+because @emph{libmicrohttpd} provides a server and not a client.
+In client mode all outgoing payload will be masked
+(XOR-ed with random values).
+All incoming payload must be unmasked.
+If you use this mode, you must always call @code{MHD_websocket_stream_init2}
+instead of @code{MHD_websocket_stream_init}, because you need
+to pass a random number generator callback function for masking.
+
+This flag cannot be used together with @code{MHD_WEBSOCKET_FLAG_SERVER}.
+
+@item MHD_WEBSOCKET_FLAG_NO_FRAGMENTS
+You don't want to get fragmented data while decoding (default).
+Fragmented frames will be internally put together until
+they are complete.
+Whether or not data is fragmented is decided
+by the sender of the data during encoding.
+
+This cannot be used together with @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}.
+
+@item MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
+You want fragmented data, if it appears while decoding.
+You will receive the content of the fragmented frame,
+but if you are decoding text, you will never get an unfinished
+UTF-8 sequence (if the sequence appears between two fragments).
+Instead the text will end before the unfinished UTF-8 sequence.
+With the next fragment, which finishes the UTF-8 sequence,
+you will get the complete UTF-8 sequence.
+
+This cannot be used together with @code{MHD_WEBSOCKET_FLAG_NO_FRAGMENTS}.
+
+@item MHD_WEBSOCKET_FLAG_GENERATE_CLOSE_FRAMES_ON_ERROR
+If the websocket stream becomes invalid during decoding due to
+protocol errors, a matching close frame will automatically
+be generated.
+The close frame will be returned via the parameters
+@code{payload} and @code{payload_len} of @code{MHD_websocket_decode} and
+the return value is negative (a value of @code{enum MHD_WEBSOCKET_STATUS}).
+
+The generated close frame must be freed by the caller
+with @code{MHD_websocket_free}.
+
+@end table
+@end deftp
+
+
+@deftp {Enumeration} MHD_WEBSOCKET_FRAGMENTATION
+@cindex websocket
+This enumeration is used to specify the fragmentation behavior
+when encoding of data (text/binary) for a websocket stream.
+This is used with @code{MHD_websocket_encode_text} or
+@code{MHD_websocket_encode_binary}.
+
+Note that websocket streams are only available if you include the header file
+@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
+
+@table @code
+@item MHD_WEBSOCKET_FRAGMENTATION_NONE
+You don't want to use fragmentation.
+The encoded frame consists of only one frame.
+
+@item MHD_WEBSOCKET_FRAGMENTATION_FIRST
+You want to use fragmentation.
+The encoded frame is the first frame of
+a series of data frames of the same type
+(text or binary).
+You may send control frames (ping, pong or close)
+between these data frames.
+
+@item MHD_WEBSOCKET_FRAGMENTATION_FOLLOWING
+You want to use fragmentation.
+The encoded frame is not the first frame of
+the series of data frames, but also not the last one.
+You may send control frames (ping, pong or close)
+between these data frames.
+
+@item MHD_WEBSOCKET_FRAGMENTATION_LAST
+You want to use fragmentation.
+The encoded frame is the last frame of
+the series of data frames, but also not the first one.
+After this frame, you may send all types of frames again.
+
+@end table
+@end deftp
+
+
+@deftp {Enumeration} MHD_WEBSOCKET_STATUS
+@cindex websocket
+This enumeration is used for the return value of almost
+every websocket stream function.
+Errors are negative and values equal to or above zero mean a success.
+Positive values are only used by @code{MHD_websocket_decode}.
+
+Note that websocket streams are only available if you include the header file
+@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
+
+@table @code
+@item MHD_WEBSOCKET_STATUS_OK
+The call succeeded.
+Especially for @code{MHD_websocket_decode} this means that no error occurred,
+but also no frame has been completed yet.
+For other functions this means simply a success.
+
+@item MHD_WEBSOCKET_STATUS_TEXT_FRAME
+@code{MHD_websocket_decode} has decoded a text frame.
+The parameters @code{payload} and @code{payload_len} are filled with
+the decoded text (if any).
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_BINARY_FRAME
+@code{MHD_websocket_decode} has decoded a binary frame.
+The parameters @code{payload} and @code{payload_len} are filled with
+the decoded binary data (if any).
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_CLOSE_FRAME
+@code{MHD_websocket_decode} has decoded a close frame.
+This means you must close the socket using @code{MHD_upgrade_action}
+with @code{MHD_UPGRADE_ACTION_CLOSE}.
+You may respond with a close frame before closing.
+The parameters @code{payload} and @code{payload_len} are filled with
+the close reason (if any).
+The close reason starts with a two byte sequence of close code
+in network byte order (see @code{enum MHD_WEBSOCKET_CLOSEREASON}).
+After these two bytes a UTF-8 encoded close reason may follow.
+You can call @code{MHD_websocket_split_close_reason} to split that
+close reason.
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_PING_FRAME
+@code{MHD_websocket_decode} has decoded a ping frame.
+You should respond to this with a pong frame.
+The pong frame must contain the same binary data as
+the corresponding ping frame (if it had any).
+The parameters @code{payload} and @code{payload_len} are filled with
+the binary ping data (if any).
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_PONG_FRAME
+@code{MHD_websocket_decode} has decoded a pong frame.
+You should usually only receive pong frames if you sent
+a ping frame before.
+The binary data should be equal to your ping frame and can be
+used to distinguish the response if you sent multiple ping frames.
+The parameters @code{payload} and @code{payload_len} are filled with
+the binary pong data (if any).
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT
+@code{MHD_websocket_decode} has decoded a text frame fragment.
+The parameters @code{payload} and @code{payload_len} are filled with
+the decoded text (if any).
+This is like @code{MHD_WEBSOCKET_STATUS_TEXT_FRAME}, but it can only
+appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS} during
+the call of @code{MHD_websocket_stream_init} or
+@code{MHD_websocket_stream_init2}.
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT
+@code{MHD_websocket_decode} has decoded a binary frame fragment.
+The parameters @code{payload} and @code{payload_len} are filled with
+the decoded binary data (if any).
+This is like @code{MHD_WEBSOCKET_STATUS_BINARY_FRAME}, but it can only
+appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS} during
+the call of @code{MHD_websocket_stream_init} or
+@code{MHD_websocket_stream_init2}.
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_TEXT_NEXT_FRAGMENT
+@code{MHD_websocket_decode} has decoded the next text frame fragment.
+The parameters @code{payload} and @code{payload_len} are filled with
+the decoded text (if any).
+This is like @code{MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT}, but it appears
+only after the first and before the last fragment of a series of fragments.
+It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
+during the call of @code{MHD_websocket_stream_init} or
+@code{MHD_websocket_stream_init2}.
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_BINARY_NEXT_FRAGMENT
+@code{MHD_websocket_decode} has decoded the next binary frame fragment.
+The parameters @code{payload} and @code{payload_len} are filled with
+the decoded binary data (if any).
+This is like @code{MHD_WEBSOCKET_STATUS_BINARY_FIRST_FRAGMENT}, but it appears
+only after the first and before the last fragment of a series of fragments.
+It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
+during the call of @code{MHD_websocket_stream_init} or
+@code{MHD_websocket_stream_init2}.
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_TEXT_LAST_FRAGMENT
+@code{MHD_websocket_decode} has decoded the last text frame fragment.
+The parameters @code{payload} and @code{payload_len} are filled with
+the decoded text (if any).
+This is like @code{MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT}, but it appears
+only for the last fragment of a series of fragments.
+It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
+during the call of @code{MHD_websocket_stream_init} or
+@code{MHD_websocket_stream_init2}.
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_BINARY_LAST_FRAGMENT
+@code{MHD_websocket_decode} has decoded the last binary frame fragment.
+The parameters @code{payload} and @code{payload_len} are filled with
+the decoded binary data (if any).
+This is like @code{MHD_WEBSOCKET_STATUS_BINARY_FIRST_FRAGMENT}, but it appears
+only for the last fragment of a series of fragments.
+It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
+during the call of @code{MHD_websocket_stream_init} or
+@code{MHD_websocket_stream_init2}.
+You must free the returned @code{payload} after use with
+@code{MHD_websocket_free}.
+
+@item MHD_WEBSOCKET_STATUS_PROTOCOL_ERROR
+The call failed and the stream is invalid now for decoding.
+You must close the websocket now using @code{MHD_upgrade_action}
+with @code{MHD_UPGRADE_ACTION_CLOSE}.
+You may send a close frame before closing.
+This is only used by @code{MHD_websocket_decode} and happens
+if the stream contains errors (i. e. invalid byte data).
+
+@item MHD_WEBSOCKET_STATUS_STREAM_BROKEN
+You tried to decode something, but the stream has already
+been marked invalid.
+You must close the websocket now using @code{MHD_upgrade_action}
+with @code{MHD_UPGRADE_ACTION_CLOSE}.
+You may send a close frame before closing.
+This is only used by @code{MHD_websocket_decode} and happens
+if you call @code{MDM_websocket_decode} again after
+has been invalidated.
+You can call @code{MHD_websocket_stream_is_valid} at any time
+to check whether a stream is invalid or not.
+
+@item MHD_WEBSOCKET_STATUS_MEMORY_ERROR
+A memory allocation failed. The stream remains valid.
+If this occurred while decoding, the decoding could be
+possible later if enough memory is available.
+This could happen while decoding if you received a too big data frame.
+You could try to specify max_payload_size during the call of
+@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2} to
+avoid this and close the websocket instead.
+
+@item MHD_WEBSOCKET_STATUS_PARAMETER_ERROR
+You passed invalid parameters during the function call
+(i. e. a NULL pointer for a required parameter).
+The stream remains valid.
+
+@item MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED
+The maximum payload size has been exceeded.
+If you got this return code from @code{MHD_websocket_decode} then
+the stream becomes invalid and the websocket must be closed
+using @code{MHD_upgrade_action} with @code{MHD_UPGRADE_ACTION_CLOSE}.
+You may send a close frame before closing.
+The maximum payload size is specified during the call of
+@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2}.
+This can also appear if you specified 0 as maximum payload size
+when the message is greater than the maximum allocatable memory size
+(i. e. more than 4 GiB on 32 bit systems).
+If you got this return code from @code{MHD_websocket_encode_close},
+@code{MHD_websocket_encode_ping} or @code{MHD_websocket_encode_pong} then
+you passed to much payload data. The stream remains valid then.
+
+@item MHD_WEBSOCKET_STATUS_UTF8_ENCODING_ERROR
+An UTF-8 sequence is invalid.
+If you got this return code from @code{MHD_websocket_decode} then
+the stream becomes invalid and you must close the websocket
+using @code{MHD_upgrade_action} with @code{MHD_UPGRADE_ACTION_CLOSE}.
+You may send a close frame before closing.
+If you got this from @code{MHD_websocket_encode_text} or
+@code{MHD_websocket_encode_close} then you passed invalid UTF-8 text.
+The stream remains valid then.
+
+@item MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER
+A check routine for the HTTP headers came to the conclusion that
+the header value isn't valid for a websocket handshake request.
+This value can only be returned from the following functions:
+@code{MHD_websocket_check_http_version},
+@code{MHD_websocket_check_connection_header},
+@code{MHD_websocket_check_upgrade_header},
+@code{MHD_websocket_check_version_header},
+@code{MHD_websocket_create_accept_header}
+
+@end table
+@end deftp
+
+
+@deftp {Enumeration} MHD_WEBSOCKET_CLOSEREASON
+@cindex websocket
+Enumeration of possible close reasons for websocket close frames.
+
+The possible values are specified in RFC 6455 7.4.1
+These close reasons here are the default set specified by RFC 6455,
+but also other close reasons could be used.
+
+The definition is for short:
+@itemize @bullet
+@item 0-999 are never used (if you pass 0 in
+@code{MHD_websocket_encode_close} then no close reason is used).
+@item 1000-2999 are specified by RFC 6455.
+@item 3000-3999 are specified by libraries, etc. but must be registered by IANA.
+@item 4000-4999 are reserved for private use.
+@end itemize
+
+Note that websocket streams are only available if you include the header file
+@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
+
+@table @code
+@item MHD_WEBSOCKET_CLOSEREASON_NO_REASON
+This value is used as placeholder for @code{MHD_websocket_encode_close}
+to tell that you don't want to specify any reason.
+If you use this value then no reason text may be used.
+This value cannot be a result of decoding, because this value
+is not a valid close reason for the websocket protocol.
+
+@item MHD_WEBSOCKET_CLOSEREASON_REGULAR
+You close the websocket because it fulfilled its purpose and shall
+now be closed in a normal, planned way.
+
+@item MHD_WEBSOCKET_CLOSEREASON_GOING_AWAY
+You close the websocket because you are shutting down the server or
+something similar.
+
+@item MHD_WEBSOCKET_CLOSEREASON_PROTOCOL_ERROR
+You close the websocket because a protocol error occurred
+during decoding (i. e. invalid byte data).
+
+@item MHD_WEBSOCKET_CLOSEREASON_UNSUPPORTED_DATATYPE
+You close the websocket because you received data which you don't accept.
+For example if you received a binary frame,
+but your application only expects text frames.
+
+@item MHD_WEBSOCKET_CLOSEREASON_MALFORMED_UTF8
+You close the websocket because it contains malformed UTF-8.
+The UTF-8 validity is automatically checked by @code{MHD_websocket_decode},
+so you don't need to check it on your own.
+UTF-8 is specified in RFC 3629.
+
+@item MHD_WEBSOCKET_CLOSEREASON_POLICY_VIOLATED
+You close the websocket because you received a frame which is too big
+to process.
+You can specify the maximum allowed payload size during the call of
+@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2}.
+
+@item MHD_WEBSOCKET_CLOSEREASON_MISSING_EXTENSION
+This status code can be sent by the client if it
+expected a specific extension, but this extension hasn't been negotiated.
+
+@item MHD_WEBSOCKET_CLOSEREASON_UNEXPECTED_CONDITION
+The server closes the websocket because it encountered
+an unexpected condition that prevented it from fulfilling the request.
+
+@end table
+@end deftp
+
+
+@deftp {Enumeration} MHD_WEBSOCKET_UTF8STEP
+@cindex websocket
+Enumeration of possible UTF-8 check steps for websocket functions
+
+These values are used during the encoding of fragmented text frames
+or for error analysis while encoding text frames.
+Its values specify the next step of the UTF-8 check.
+UTF-8 sequences consist of one to four bytes.
+This enumeration just says how long the current UTF-8 sequence is
+and what is the next expected byte.
+
+Note that websocket streams are only available if you include the header file
+@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
+
+@table @code
+@item MHD_WEBSOCKET_UTF8STEP_NORMAL
+There is no open UTF-8 sequence.
+The next byte must be 0x00-0x7F or 0xC2-0xF4.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF2TAIL_1OF1
+The second byte of a two byte UTF-8 sequence.
+The first byte was 0xC2-0xDF.
+The next byte must be 0x80-0xBF.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL1_1OF2
+The second byte of a three byte UTF-8 sequence.
+The first byte was 0xE0.
+The next byte must be 0xA0-0xBF.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL2_1OF2
+The second byte of a three byte UTF-8 sequence.
+The first byte was 0xED.
+The next byte must by 0x80-0x9F.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL_1OF2
+The second byte of a three byte UTF-8 sequence.
+The first byte was 0xE1-0xEC or 0xEE-0xEF.
+The next byte must be 0x80-0xBF.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL_2OF2
+The third byte of a three byte UTF-8 sequence.
+The next byte must be 0x80-0xBF.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL1_1OF3
+The second byte of a four byte UTF-8 sequence.
+The first byte was 0xF0.
+The next byte must be 0x90-0xBF.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL2_1OF3
+The second byte of a four byte UTF-8 sequence.
+The first byte was 0xF4.
+The next byte must be 0x80-0x8F.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_1OF3
+The second byte of a four byte UTF-8 sequence.
+The first byte was 0xF1-0xF3.
+The next byte must be 0x80-0xBF.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_2OF3
+The third byte of a four byte UTF-8 sequence.
+The next byte must be 0x80-0xBF.
+
+@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_3OF3
+The fourth byte of a four byte UTF-8 sequence.
+The next byte must be 0x80-0xBF.
+
+@end table
+@end deftp
+
+
+@deftp {Enumeration} MHD_WEBSOCKET_VALIDITY
+@cindex websocket
+Enumeration of validity values of a websocket stream
+
+These values are used for @code{MHD_websocket_stream_is_valid}
+and specify the validity status.
+
+Note that websocket streams are only available if you include the header file
+@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
+
+@table @code
+@item MHD_WEBSOCKET_VALIDITY_INVALID
+The stream is invalid.
+It cannot be used for decoding anymore.
+
+@item MHD_WEBSOCKET_VALIDITY_VALID
+The stream is valid.
+Decoding works as expected.
+
+@item MHD_WEBSOCKET_VALIDITY_ONLY_VALID_FOR_CONTROL_FRAMES
+The stream has received a close frame and
+is partly invalid.
+You can still use the stream for decoding,
+but if a data frame is received an error will be reported.
+After a close frame has been sent, no data frames
+may follow from the sender of the close frame.
+
+@end table
+@end deftp
+
+
 @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 @c ------------------------------------------------------------
@@ -1291,6 +1779,12 @@ Information about an MHD daemon.
 @end deftp
 
 
+@deftp {C Struct} MHD_WebSocketStream
+@cindex websocket
+Information about a MHD websocket stream.
+@end deftp
+
+
 @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 @c ------------------------------------------------------------
@@ -1549,6 +2043,95 @@ iteration.
 @end deftypefn
 
 
+@deftypefn {Function Pointer} void* {*MHD_WebSocketMallocCallback} (size_t buf_len)
+@cindex websocket
+This callback function is used internally by many websocket functions
+for allocating data.
+By default @code{malloc} is used.
+You can use your own allocation function with @code{MHD_websocket_stream_init2}
+if you wish to.
+This can be useful for operating systems like Windows
+where @code{malloc}, @code{realloc} and @code{free} are compiler-dependent.
+You can call the associated @code{malloc} callback of
+a websocket stream with @code{MHD_websocket_malloc}.
+
+@table @var
+@item buf_len
+size of the buffer to allocate in bytes.
+@end table
+
+Return the pointer of the allocated buffer or @code{NULL} on failure.
+@end deftypefn
+
+
+@deftypefn {Function Pointer} void* {*MHD_WebSocketReallocCallback} (void *buf, size_t new_buf_len)
+@cindex websocket
+This callback function is used internally by many websocket
+functions for reallocating data.
+By default @code{realloc} is used.
+You can use your own reallocation function with
+@code{MHD_websocket_stream_init2} if you wish to.
+This can be useful for operating systems like Windows
+where @code{malloc}, @code{realloc} and @code{free} are compiler-dependent.
+You can call the associated @code{realloc} callback of
+a websocket stream with @code{MHD_websocket_realloc}.
+
+@table @var
+@item buf
+current buffer, may be @code{NULL};
+
+@item new_buf_len
+new size of the buffer in bytes.
+@end table
+
+Return the pointer of the reallocated buffer or @code{NULL} on failure.
+On failure the old pointer must remain valid.
+@end deftypefn
+
+
+@deftypefn {Function Pointer} void {*MHD_WebSocketFreeCallback} (void *buf)
+@cindex websocket
+This callback function is used internally by many websocket
+functions for freeing data.
+By default @code{free} is used.
+You can use your own free function with
+@code{MHD_websocket_stream_init2} if you wish to.
+This can be useful for operating systems like Windows
+where @code{malloc}, @code{realloc} and @code{free} are compiler-dependent.
+You can call the associated @code{free} callback of
+a websocket stream with @code{MHD_websocket_free}.
+
+@table @var
+@item cls
+current buffer to free, this may be @code{NULL} then nothing happens.
+@end table
+@end deftypefn
+
+
+@deftypefn {Function Pointer} size_t {*MHD_WebSocketRandomNumberGenerator} (void *cls, void* buf, size_t buf_len)
+@cindex websocket
+This callback function is used for generating random numbers
+for masking payload data in client mode.
+If you use websockets in server mode with @emph{libmicrohttpd} then
+you don't need a random number generator, because
+the server doesn't mask its outgoing messages.
+However if you wish to use a websocket stream in client mode,
+you must pass this callback function to @code{MHD_websocket_stream_init2}.
+
+@table @var
+@item cls
+closure specified in @code{MHD_websocket_stream_init2};
+@item buf
+buffer to fill with random values;
+@item buf_len
+size of buffer in bytes.
+@end table
+
+Return the number of generated random bytes.
+The return value should usually equal to buf_len.
+@end deftypefn
+
+
 @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 @c ------------------------------------------------------------
@@ -3346,6 +3929,704 @@ shorter afterwards due to elimination of escape sequences).
 
 
 
+
+@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+@c ------------------------------------------------------------
+@node microhttpd-websocket
+@chapter Websocket functions.
+
+@noindent
+Websocket functions provide what you need to use an upgraded connection
+as a websocket.
+These functions are only available if you include the header file
+@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
+
+@menu
+* microhttpd-websocket handshake::    Websocket handshake functions
+* microhttpd-websocket stream::       Websocket stream functions
+* microhttpd-websocket decode::       Websocket decode functions
+* microhttpd-websocket encode::       Websocket encode functions
+* microhttpd-websocket memory::       Websocket memory functions
+@end menu
+
+@c ------------------------------------------------------------
+@node microhttpd-websocket handshake
+@section Websocket handshake functions
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_check_http_version (const char* http_version)
+@cindex websocket
+Checks the HTTP version of the incoming request.
+Websocket requests are only allowed for HTTP/1.1 or above.
+
+@table @var
+@item http_version
+The value of the @code{version} parameter of your
+@code{access_handler} callback.
+If you pass @code{NULL} then this is handled like a not
+matching HTTP version.
+@end table
+
+Returns 0 when the HTTP version is
+valid for a websocket request and
+a value less than zero when the HTTP version isn't
+valid for a websocket request.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_check_connection_header (const char* connection_header)
+@cindex websocket
+Checks the value of the @code{Connection} HTTP request header.
+Websocket requests require the token @code{Upgrade} in
+the @code{Connection} HTTP request header.
+
+@table @var
+@item connection_header
+Value of the @code{Connection} request header.
+You can get this request header value by passing
+@code{MHD_HTTP_HEADER_CONNECTION} to
+@code{MHD_lookup_connection_value()}.
+If you pass @code{NULL} then this is handled like a not
+matching @code{Connection} header value.
+@end table
+
+Returns 0 when the @code{Connection} header is
+valid for a websocket request and
+a value less than zero when the @code{Connection} header isn't
+valid for a websocket request.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_check_upgrade_header (const char* upgrade_header)
+@cindex websocket
+Checks the value of the @code{Upgrade} HTTP request header.
+Websocket requests require the value @code{websocket} in
+the @code{Upgrade} HTTP request header.
+
+@table @var
+@item upgrade_header
+Value of the @code{Upgrade} request header.
+You can get this request header value by passing
+@code{MHD_HTTP_HEADER_UPGRADE} to
+@code{MHD_lookup_connection_value()}.
+If you pass @code{NULL} then this is handled like a not
+matching @code{Upgrade} header value.
+@end table
+
+Returns 0 when the @code{Upgrade} header is
+valid for a websocket request and
+a value less than zero when the @code{Upgrade} header isn't
+valid for a websocket request.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_check_version_header (const char* version_header)
+@cindex websocket
+Checks the value of the @code{Sec-WebSocket-Version} HTTP request header.
+Websocket requests require the value @code{13} in
+the @code{Sec-WebSocket-Version} HTTP request header.
+
+@table @var
+@item version_header
+Value of the @code{Sec-WebSocket-Version} request header.
+You can get this request header value by passing
+@code{MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION} to
+@code{MHD_lookup_connection_value()}.
+If you pass @code{NULL} then this is handled like a not
+matching @code{Sec-WebSocket-Version} header value.
+@end table
+
+Returns 0 when the @code{Sec-WebSocket-Version} header is
+valid for a websocket request and
+a value less than zero when the @code{Sec-WebSocket-Version} header isn't
+valid for a websocket request.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_create_accept_header (const char* sec_websocket_key, char* sec_websocket_accept)
+@cindex websocket
+Checks the value of the @code{Sec-WebSocket-Key}
+HTTP request header and generates the value for
+the @code{Sec-WebSocket-Accept} HTTP response header.
+The generated value must be sent to the client.
+
+@table @var
+@item sec_websocket_key
+Value of the @code{Sec-WebSocket-Key} request header.
+You can get this request header value by passing
+@code{MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY} to
+@code{MHD_lookup_connection_value()}.
+If you pass @code{NULL} then this is handled like a not
+matching @code{Sec-WebSocket-Key} header value.
+
+@item sec_websocket_accept
+Response buffer, which will receive
+the generated value for the @code{Sec-WebSocket-Accept}
+HTTP response header.
+This buffer must be at least 29 bytes long and
+will contain the response value plus a terminating @code{NUL}
+character on success.
+Must not be @code{NULL}.
+You can add this HTTP header to your response by passing
+@code{MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT} to
+@code{MHD_add_response_header()}.
+@end table
+
+Returns 0 when the @code{Sec-WebSocket-Key} header was
+not empty and a result value for the @code{Sec-WebSocket-Accept}
+was calculated.
+A value less than zero is returned when the @code{Sec-WebSocket-Key}
+header isn't valid for a websocket request or when any
+error occurred.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@c ------------------------------------------------------------
+@node microhttpd-websocket stream
+@section Websocket stream functions
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_stream_init (struct MHD_WebSocketStream **ws, int flags, size_t max_payload_size)
+@cindex websocket
+Creates a new websocket stream, used for decoding/encoding.
+
+@table @var
+@item ws
+pointer a variable to fill with the newly created
+@code{struct MHD_WebSocketStream},
+receives @code{NULL} on error. May not be @code{NULL}.
+
+If not required anymore, free the created websocket stream with
+@code{MHD_websocket_stream_free()}.
+
+@item flags
+combination of @code{enum MHD_WEBSOCKET_FLAG} values to
+modify the behavior of the websocket stream.
+
+@item max_payload_size
+maximum size for incoming payload data in bytes. Use 0 to allow each size.
+@end table
+
+Returns 0 on success, negative values on error.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_stream_init2 (struct MHD_WebSocketStream **ws, int flags, size_t max_payload_size, MHD_WebSocketMallocCallback callback_malloc, MHD_WebSocketReallocCallback callback_realloc, MHD_WebSocketFreeCallback callback_free, void* cls_rng, MHD_WebSocketRandomNumberGenerator callback_rng)
+@cindex websocket
+Creates a new websocket stream, used for decoding/encoding,
+but with custom memory functions for malloc, realloc and free.
+Also a random number generator can be specified for client mode.
+
+@table @var
+@item ws
+pointer a variable to fill with the newly created
+@code{struct MHD_WebSocketStream},
+receives @code{NULL} on error. Must not be @code{NULL}.
+
+If not required anymore, free the created websocket stream with
+@code{MHD_websocket_stream_free}.
+
+@item flags
+combination of @code{enum MHD_WEBSOCKET_FLAG} values to
+modify the behavior of the websocket stream.
+
+@item max_payload_size
+maximum size for incoming payload data in bytes. Use 0 to allow each size.
+
+@item callback_malloc
+callback function for allocating memory. Must not be @code{NULL}.
+The shorter @code{MHD_websocket_stream_init()} passes a reference to @code{malloc} here.
+
+@item callback_realloc
+callback function for reallocating memory. Must not be @code{NULL}.
+The shorter @code{MHD_websocket_stream_init()} passes a reference to @code{realloc} here.
+
+@item callback_free
+callback function for freeing memory. Must not be @code{NULL}.
+The shorter @code{MHD_websocket_stream_init()} passes a reference to @code{free} here.
+
+@item cls_rng
+closure for the random number generator.
+This is only required when
+@code{MHD_WEBSOCKET_FLAG_CLIENT} is passed in @code{flags}.
+The given value is passed to the random number generator callback.
+May be @code{NULL} if not needed.
+Should be @code{NULL} when you are not using @code{MHD_WEBSOCKET_FLAG_CLIENT}.
+The shorter @code{MHD_websocket_stream_init} passes @code{NULL} here.
+
+@item callback_rng
+callback function for a secure random number generator.
+This is only required when @code{MHD_WEBSOCKET_FLAG_CLIENT} is
+passed in @code{flags} and must not be @code{NULL} then.
+Should be @code{NULL} otherwise.
+The shorter @code{MHD_websocket_stream_init()} passes @code{NULL} here.
+@end table
+
+Returns 0 on success, negative values on error.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_stream_free (struct MHD_WebSocketStream *ws)
+@cindex websocket
+Frees a previously allocated websocket stream
+
+@table @var
+@item ws
+websocket stream to free, this value may be @code{NULL}.
+@end table
+
+Returns 0 on success, negative values on error.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_stream_invalidate (struct MHD_WebSocketStream *ws)
+@cindex websocket
+Invalidates a websocket stream.
+After invalidation a websocket stream cannot be used for decoding anymore.
+Encoding is still possible.
+
+@table @var
+@item ws
+websocket stream to invalidate.
+@end table
+
+Returns 0 on success, negative values on error.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_VALIDITY} MHD_websocket_stream_is_valid (struct MHD_WebSocketStream *ws)
+@cindex websocket
+Queries whether a websocket stream is valid.
+Invalidated websocket streams cannot be used for decoding anymore.
+Encoding is still possible.
+
+@table @var
+@item ws
+websocket stream to invalidate.
+@end table
+
+Returns 0 if invalid, 1 if valid for all types or
+2 if valid only for control frames.
+Can be compared with @code{enum MHD_WEBSOCKET_VALIDITY}.
+@end deftypefun
+
+
+@c ------------------------------------------------------------
+@node microhttpd-websocket decode
+@section Websocket decode functions
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_decode (struct MHD_WebSocketStream* ws, const char* streambuf, size_t streambuf_len, size_t* streambuf_read_len, char** payload, size_t* payload_len)
+@cindex websocket
+Decodes a byte sequence for a websocket stream.
+Decoding is done until either a frame is complete or
+the end of the byte sequence is reached.
+
+@table @var
+@item ws
+websocket stream for decoding.
+
+@item streambuf
+byte sequence for decoding.
+This is what you typically received via @code{recv()}.
+
+@item streambuf_len
+length of the byte sequence in parameter @code{streambuf}.
+
+@item streambuf_read_len
+pointer to a variable, which receives the number of bytes,
+that has been processed by this call.
+This value may be less than the value of @code{streambuf_len} when
+a frame is decoded before the end of the buffer is reached.
+The remaining bytes of @code{buf} must be passed to
+the next call of this function.
+
+@item payload
+pointer to a variable, which receives the allocated buffer with the payload
+data of the decoded frame. Must not be @code{NULL}.
+If no decoded data is available or an error occurred @code{NULL} is returned.
+When the returned value is not @code{NULL} then the buffer contains always
+@code{payload_len} bytes plus one terminating @code{NUL} character
+(regardless of the frame type).
+
+The caller must free this buffer using @code{MHD_websocket_free()}.
+
+If you passed the flag @code{MHD_WEBSOCKET_FLAG_GENERATE_CLOSE_FRAMES_ON_ERROR}
+upon creation of the websocket stream and a decoding error occurred
+(function return value less than 0), then this buffer contains
+a generated close frame, which must be sent via the socket to the recipient.
+
+If you passed the flag @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
+upon creation of the websocket stream then
+this payload may only be a part of the complete message.
+Only complete UTF-8 sequences are returned for fragmented text frames.
+If necessary the UTF-8 sequence will be completed with the next text fragment.
+
+@item payload_len
+pointer to a variable, which receives length of the result
+@code{payload} buffer in bytes.
+Must not be @code{NULL}.
+This receives 0 when no data is available, when the decoded payload
+has a length of zero or when an error occurred.
+@end table
+
+Returns a value greater than zero when a frame is complete.
+Compare with @code{enum MHD_WEBSOCKET_STATUS} to distinguish the frame type.
+Returns 0 when the call succeeded, but no frame is available.
+Returns a value less than zero on errors.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_split_close_reason (const char* payload, size_t payload_len, unsigned short* reason_code, const char** reason_utf8, size_t* reason_utf8_len)
+@cindex websocket
+Splits the payload of a decoded close frame.
+
+@table @var
+@item payload
+payload of the close frame.
+This parameter may only be @code{NULL} if @code{payload_len} is 0.
+
+@item payload_len
+length of @code{payload}.
+
+@item reason_code
+pointer to a variable, which receives the numeric close reason.
+If there was no close reason, this is 0.
+This value can be compared with @code{enum MHD_WEBSOCKET_CLOSEREASON}.
+May be @code{NULL}.
+
+@item reason_utf8
+pointer to a variable, which receives the literal close reason.
+If there was no literal close reason, this will be @code{NULL}.
+May be @code{NULL}.
+
+Please note that no memory is allocated in this function.
+If not @code{NULL} the returned value of this parameter
+points to a position in the specified @code{payload}.
+
+@item reason_utf8_len
+pointer to a variable, which receives the length of the literal close reason.
+If there was no literal close reason, this is 0.
+May be @code{NULL}.
+@end table
+
+Returns 0 on success or a value less than zero on errors.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@c ------------------------------------------------------------
+@node microhttpd-websocket encode
+@section Websocket encode functions
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_text (struct MHD_WebSocketStream* ws, const char* payload_utf8, size_t payload_utf8_len, int fragmentation, char** frame, size_t* frame_len, int* utf8_step)
+@cindex websocket
+Encodes an UTF-8 encoded text into websocket text frame
+
+@table @var
+@item ws
+websocket stream;
+
+@item payload_utf8
+text to send. This must be UTF-8 encoded.
+If you don't want UTF-8 then send a binary frame
+with @code{MHD_websocket_encode_binary()} instead.
+May be be @code{NULL} if @code{payload_utf8_len} is 0,
+must not be @code{NULL} otherwise.
+
+@item payload_utf8_len
+length of @code{payload_utf8} in bytes.
+
+@item fragmentation
+A value of @code{enum MHD_WEBSOCKET_FRAGMENTATION}
+to specify the fragmentation behavior.
+Specify @code{MHD_WEBSOCKET_FRAGMENTATION_NONE} or just 0
+if you don't want to use fragmentation (default).
+
+@item frame
+pointer to a variable, which receives a buffer with the encoded text frame.
+Must not be @code{NULL}.
+The buffer contains what you typically send via @code{send()} to the recipient.
+If no encoded data is available the variable receives @code{NULL}.
+
+If the variable is not @code{NULL} then the buffer contains always
+@code{frame_len} bytes plus one terminating @code{NUL} character.
+The caller must free this buffer using @code{MHD_websocket_free()}.
+
+@item frame_len
+pointer to a variable, which receives the length of the encoded frame in bytes.
+Must not be @code{NULL}.
+
+@item utf8_step
+If fragmentation is used (the parameter @code{fragmentation} is not 0)
+then is parameter is required and must not be @code{NULL}.
+If no fragmentation is used, this parameter is optional and
+should be @code{NULL}.
+
+This parameter is a pointer to a variable which contains the last check status
+of the UTF-8 sequence. It is required to continue a previous
+UTF-8 sequence check when fragmentation is used, because a UTF-8 sequence
+could be splitted upon fragments.
+
+@code{enum MHD_WEBSOCKET_UTF8STEP} is used for this value.
+If you start a new fragment using
+@code{MHD_WEBSOCKET_FRAGMENTATION_NONE} or
+@code{MHD_WEBSOCKET_FRAGMENTATION_FIRST} the old value of this variable
+will be discarded and the value of this variable will be initialized
+to @code{MHD_WEBSOCKET_UTF8STEP_NORMAL}.
+On all other fragmentation modes the previous value of the pointed variable
+will be used to continue the UTF-8 sequence check.
+@end table
+
+Returns 0 on success or a value less than zero on errors.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_binary (struct MHD_WebSocketStream* ws, const char* payload, size_t payload_len, int fragmentation, char** frame, size_t* frame_len)
+@cindex websocket
+Encodes binary data into websocket binary frame
+
+@table @var
+@item ws
+websocket stream;
+
+@item payload
+binary data to send.
+May be be @code{NULL} if @code{payload_len} is 0,
+must not be @code{NULL} otherwise.
+
+@item payload_len
+length of @code{payload} in bytes.
+
+@item fragmentation
+A value of @code{enum MHD_WEBSOCKET_FRAGMENTATION}
+to specify the fragmentation behavior.
+Specify @code{MHD_WEBSOCKET_FRAGMENTATION_NONE} or just 0
+if you don't want to use fragmentation (default).
+
+@item frame
+pointer to a variable, which receives a buffer with the encoded binary frame.
+Must not be @code{NULL}.
+The buffer contains what you typically send via @code{send()} to the recipient.
+If no encoded data is available the variable receives @code{NULL}.
+
+If the variable is not @code{NULL} then the buffer contains always
+@code{frame_len} bytes plus one terminating @code{NUL} character.
+The caller must free this buffer using @code{MHD_websocket_free()}.
+
+@item frame_len
+pointer to a variable, which receives the length of the encoded frame in bytes.
+Must not be @code{NULL}.
+@end table
+
+Returns 0 on success or a value less than zero on errors.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_ping (struct MHD_WebSocketStream* ws, const char* payload, size_t payload_len, char** frame, size_t* frame_len)
+@cindex websocket
+Encodes a websocket ping frame.
+Ping frames are used to check whether a recipient is still available
+and what latency the websocket connection has.
+
+@table @var
+@item ws
+websocket stream;
+
+@item payload
+binary ping data to send.
+May be @code{NULL} if @code{payload_len} is 0.
+
+@item payload_len
+length of @code{payload} in bytes.
+This may not exceed 125 bytes.
+
+@item frame
+pointer to a variable, which receives a buffer with the encoded ping frame.
+Must not be @code{NULL}.
+The buffer contains what you typically send via @code{send()} to the recipient.
+If no encoded data is available the variable receives @code{NULL}.
+
+If the variable is not @code{NULL} then the buffer contains always
+@code{frame_len} bytes plus one terminating @code{NUL} character.
+The caller must free this buffer using @code{MHD_websocket_free()}.
+
+@item frame_len
+pointer to a variable, which receives the length of the encoded frame in bytes.
+Must not be @code{NULL}.
+@end table
+
+Returns 0 on success or a value less than zero on errors.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_pong (struct MHD_WebSocketStream* ws, const char* payload, size_t payload_len, char** frame, size_t* frame_len)
+@cindex websocket
+Encodes a websocket pong frame.
+Pong frames are used to answer a previously received websocket ping frame.
+
+@table @var
+@item ws
+websocket stream;
+
+@item payload
+binary pong data to send, which should be
+the decoded payload from the received ping frame.
+May be @code{NULL} if @code{payload_len} is 0.
+
+@item payload_len
+length of @code{payload} in bytes.
+This may not exceed 125 bytes.
+
+@item frame
+pointer to a variable, which receives a buffer with the encoded pong frame.
+Must not be @code{NULL}.
+The buffer contains what you typically send via @code{send()} to the recipient.
+If no encoded data is available the variable receives @code{NULL}.
+
+If the variable is not @code{NULL} then the buffer contains always
+@code{frame_len} bytes plus one terminating @code{NUL} character.
+The caller must free this buffer using @code{MHD_websocket_free()}.
+
+@item frame_len
+pointer to a variable, which receives the length of the encoded frame in bytes.
+Must not be @code{NULL}.
+@end table
+
+Returns 0 on success or a value less than zero on errors.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_close (struct MHD_WebSocketStream* ws, unsigned short reason_code, const char* reason_utf8, size_t reason_utf8_len, char** frame, size_t* frame_len)
+@cindex websocket
+Encodes a websocket close frame.
+Close frames are used to close a websocket connection in a formal way.
+
+@table @var
+@item ws
+websocket stream;
+
+@item reason_code
+reason for close.
+You can use @code{enum MHD_WEBSOCKET_CLOSEREASON} for typical reasons,
+but you are not limited to these values.
+The allowed values are specified in RFC 6455 7.4.
+If you don't want to enter a reason, you can specify
+@code{MHD_WEBSOCKET_CLOSEREASON_NO_REASON} (or just 0) then
+no reason is encoded.
+
+@item reason_utf8
+An UTF-8 encoded text reason why the connection is closed.
+This may be @code{NULL} if @code{reason_utf8_len} is 0.
+This must be @code{NULL} if @code{reason_code} equals to zero
+(@code{MHD_WEBSOCKET_CLOSEREASON_NO_REASON}).
+
+@item reason_utf8_len
+length of the UTF-8 encoded text reason in bytes.
+This may not exceed 123 bytes.
+
+@item frame
+pointer to a variable, which receives a buffer with the encoded close frame.
+Must not be @code{NULL}.
+The buffer contains what you typically send via @code{send()} to the recipient.
+If no encoded data is available the variable receives @code{NULL}.
+
+If the variable is not @code{NULL} then the buffer contains always
+@code{frame_len} bytes plus one terminating @code{NUL} character.
+The caller must free this buffer using @code{MHD_websocket_free()}.
+
+@item frame_len
+pointer to a variable, which receives the length of the encoded frame in bytes.
+Must not be @code{NULL}.
+@end table
+
+Returns 0 on success or a value less than zero on errors.
+Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
+@end deftypefun
+
+
+@c ------------------------------------------------------------
+@node microhttpd-websocket memory
+@section Websocket memory functions
+
+
+@deftypefun {void*} MHD_websocket_malloc (struct MHD_WebSocketStream* ws, size_t buf_len)
+@cindex websocket
+Allocates memory with the associated @code{malloc()} function
+of the websocket stream.
+The memory allocation function could be different for a websocket stream if
+@code{MHD_websocket_stream_init2()} has been used for initialization.
+
+@table @var
+@item ws
+websocket stream;
+
+@item buf_len
+size of the buffer to allocate in bytes.
+@end table
+
+Returns the pointer of the allocated buffer or @code{NULL} on failure.
+@end deftypefun
+
+
+@deftypefun {void*} MHD_websocket_realloc (struct MHD_WebSocketStream* ws, void* buf, size_t new_buf_len)
+@cindex websocket
+Reallocates memory with the associated @code{realloc()} function
+of the websocket stream.
+The memory reallocation function could be different for a websocket stream if
+@code{MHD_websocket_stream_init2()} has been used for initialization.
+
+@table @var
+@item ws
+websocket stream;
+
+@item buf
+current buffer, may be @code{NULL};
+
+@item new_buf_len
+new size of the buffer in bytes.
+@end table
+
+Return the pointer of the reallocated buffer or @code{NULL} on failure.
+On failure the old pointer remains valid.
+@end deftypefun
+
+
+@deftypefun {void} MHD_websocket_free (struct MHD_WebSocketStream* ws, void* buf)
+@cindex websocket
+Frees memory with the associated @code{free()} function
+of the websocket stream.
+The memory free function could be different for a websocket stream if
+@code{MHD_websocket_stream_init2()} has been used for initialization.
+
+@table @var
+@item ws
+websocket stream;
+
+@item buf
+buffer to free, this may be @code{NULL} then nothing happens.
+@end table
+
+@end deftypefun
+
+
+
+
+
 @c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++