1 files changed, 336 insertions, 198 deletions

diff --git a/src/include/microhttpd_ws.h b/src/include/microhttpd_ws.h
index bfbd550a..f19c140d 100644
--- a/src/include/microhttpd_ws.h
+++ b/src/include/microhttpd_ws.h
@@ -51,29 +51,27 @@ struct MHD_WebSocketStream;
 enum MHD_WEBSOCKET_FLAG
 {
   /**
-   * The websocket is used by the server (default).
+   * The websocket stream is initialized in server mode (default).
    * Thus all outgoing payload will not be "masked".
    * All incoming payload must be masked.
-   * This cannot be used together with #MHD_WEBSOCKET_FLAG_CLIENT
+   * This flag cannot be used together with #MHD_WEBSOCKET_FLAG_CLIENT
    */
   MHD_WEBSOCKET_FLAG_SERVER = 0,
   /**
-   * The websocket is used by the client
-   * (not used if you provide the server).
-   * Thus all outgoing payload will be "masked" (XOR-ed with random values).
+   * The websocket stream is initialized in client mode.
+   * You will usually never use that mode in combination with libmicrohttpd,
+   * because 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.
-   * Please note that this implementation doesn't use a strong random
-   * number generator for the mask as suggested in RFC6455 10.3, because
-   * the main intention of this implementation is the use as server
-   * with MHD, which doesn't need masking.
-   * Instead a weak random number generator is used (`rand()`).
-   * You can set the seed for the random number generator
-   * by calling #MHD_websocket_srand().
-   * This cannot be used together with #MHD_WEBSOCKET_FLAG_SERVER
+   * If you use this mode, you must always call #MHD_websocket_stream_init2()
+   * instead of #MHD_websocket_stream_init(), because you need
+   * to pass a random number generator callback function for masking.
+   * This flag cannot be used together with #MHD_WEBSOCKET_FLAG_SERVER
    */
   MHD_WEBSOCKET_FLAG_CLIENT = 1,
   /**
-   * You don't want to get fragmented data while decoding.
+   * 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
@@ -85,11 +83,11 @@ enum MHD_WEBSOCKET_FLAG
    * 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 sequences (if the sequence appears between two fragments).
+   * 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 #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
+   * This cannot be used together with #MHD_WEBSOCKET_FLAG_NO_FRAGMENTS
    */
   MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS = 2,
   /**
@@ -97,7 +95,7 @@ enum MHD_WEBSOCKET_FLAG
    * protocol errors, a matching close frame will automatically
    * be generated.
    * The close frame will be returned via the parameters
-   * result and result_len of #MHD_websocket_decode() and
+   * `payload` and `payload_len` of #MHD_websocket_decode() and
    * the return value is negative
    * (a value of `enum MHD_WEBSOCKET_STATUS`).
    * The generated close frame must be freed by the caller
@@ -140,7 +138,7 @@ enum MHD_WEBSOCKET_FRAGMENTATION
    * 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 type of frames again.
+   * After this frame, you may send all types of frames again.
    */
   MHD_WEBSOCKET_FRAGMENTATION_LAST = 3
 };
@@ -157,18 +155,19 @@ enum MHD_WEBSOCKET_STATUS
    * The call succeeded.
    * For #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.
    */
   MHD_WEBSOCKET_STATUS_OK = 0,
   /**
    * #MHD_websocket_decode() has decoded a text frame.
-   * The parameters result and result_len are filled with the decoded text
-   * (if any).
+   * The parameters `payload` and `payload_len` are filled with
+   * the decoded text (if any).
    */
   MHD_WEBSOCKET_STATUS_TEXT_FRAME = 0x1,
   /**
    * #MHD_websocket_decode() has decoded a binary frame.
-   * The parameters result and result_len are filled with the decoded
-   * binary data (if any).
+   * The parameters `payload` and `payload_len` are filled with
+   * the decoded binary data (if any).
    */
   MHD_WEBSOCKET_STATUS_BINARY_FRAME = 0x2,
   /**
@@ -176,12 +175,13 @@ enum MHD_WEBSOCKET_STATUS
    * This means you must close the socket using #MHD_upgrade_action()
    * with #MHD_UPGRADE_ACTION_CLOSE.
    * You may respond with a close frame before closing.
-   * The parameters result and result_len are filled with
+   * The parameters `payload` and `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 `enum MHD_WEBSOCKET_CLOSEREASON`).
    * After these two bytes a UTF-8 encoded close reason may follow.
-   * Compare with result_len to decide whether there is any close reason.
+   * You can call #MHD_websocket_split_close_reason() to split that
+   * close reason.
    */
   MHD_WEBSOCKET_STATUS_CLOSE_FRAME = 0x8,
   /**
@@ -189,7 +189,7 @@ enum MHD_WEBSOCKET_STATUS
    * 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 result and result_len are filled with
+   * The parameters `payload` and `payload_len` are filled with
    * the binary ping data (if any).
    */
   MHD_WEBSOCKET_STATUS_PING_FRAME = 0x9,
@@ -199,57 +199,79 @@ enum MHD_WEBSOCKET_STATUS
    * 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 result and result_len are filled with
+   * The parameters `payload` and `payload_len` are filled with
    * the binary pong data (if any).
    */
   MHD_WEBSOCKET_STATUS_PONG_FRAME = 0xA,
   /**
    * #MHD_websocket_decode() has decoded a text frame fragment.
-   * The parameters result and result_len are filled with the decoded text
-   * (if any).
+   * The parameters `payload` and `payload_len` are filled with
+   * the decoded text (if any).
    * This is like #MHD_WEBSOCKET_STATUS_TEXT_FRAME, but it can only
    * appear if you specified #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS during
    * the call of #MHD_websocket_stream_init() or
    * #MHD_websocket_stream_init2().
    */
-  MHD_WEBSOCKET_STATUS_TEXT_FRAGMENT = 0x11,
+  MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT = 0x11,
   /**
    * #MHD_websocket_decode() has decoded a binary frame fragment.
-   * The parameters result and result_len are filled with the decoded
-   * binary data (if any).
+   * The parameters `payload` and `payload_len` are filled with
+   * the decoded binary data (if any).
    * This is like #MHD_WEBSOCKET_STATUS_BINARY_FRAME, but it can only
    * appear if you specified #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS during
    * the call of #MHD_websocket_stream_init() or
    * #MHD_websocket_stream_init2().
    */
-  MHD_WEBSOCKET_STATUS_BINARY_FRAGMENT = 0x12,
+  MHD_WEBSOCKET_STATUS_BINARY_FIRST_FRAGMENT = 0x12,
   /**
-  * #MHD_websocket_decode() has decoded the last text frame fragment.
-  * The parameters result and result_len are filled with the decoded text
-  * (if any).
-  * This is like #MHD_WEBSOCKET_STATUS_TEXT_FRAGMENT, but it appears
-  * only for the last fragment of a series of fragments.
-  * It can only appear if you specified #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
-  * during the call of #MHD_websocket_stream_init() or
-  * #MHD_websocket_stream_init2().
-  */
-  MHD_WEBSOCKET_STATUS_TEXT_LAST_FRAGMENT = 0x21,
-  /**
-  * #MHD_websocket_decode() has decoded the last binary frame fragment.
-  * The parameters result and result_len are filled with the decoded
-  * binary data (if any).
-  * This is like #MHD_WEBSOCKET_STATUS_BINARY_FRAGMENT, but it appears
-  * only for the last fragment of a series of fragments.
-  * It can only appear if you specified #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
-  * during the call of #MHD_websocket_stream_init() or
-  * #MHD_websocket_stream_init2().
-  */
-  MHD_WEBSOCKET_STATUS_BINARY_LAST_FRAGMENT = 0x22,
+   * #MHD_websocket_decode() has decoded the next text frame fragment.
+   * The parameters `payload` and `payload_len` are filled with
+   * the decoded text (if any).
+   * This is like #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 #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
+   * during the call of #MHD_websocket_stream_init() or
+   * #MHD_websocket_stream_init2().
+   */
+  MHD_WEBSOCKET_STATUS_TEXT_NEXT_FRAGMENT = 0x21,
+  /**
+   * #MHD_websocket_decode() has decoded the next binary frame fragment.
+   * The parameters `payload` and `payload_len` are filled with
+   * the decoded binary data (if any).
+   * This is like #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 #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
+   * during the call of #MHD_websocket_stream_init() or
+   * #MHD_websocket_stream_init2().
+   */
+  MHD_WEBSOCKET_STATUS_BINARY_NEXT_FRAGMENT = 0x22,
+  /**
+   * #MHD_websocket_decode() has decoded the last text frame fragment.
+   * The parameters `payload` and `payload_len` are filled with
+   * the decoded text (if any).
+   * This is like #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 #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
+   * during the call of #MHD_websocket_stream_init() or
+   * #MHD_websocket_stream_init2().
+   */
+  MHD_WEBSOCKET_STATUS_TEXT_LAST_FRAGMENT = 0x41,
+  /**
+   * #MHD_websocket_decode() has decoded the last binary frame fragment.
+   * The parameters `payload` and `payload_len` are filled with
+   * the decoded binary data (if any).
+   * This is like #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 #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
+   * during the call of #MHD_websocket_stream_init() or
+   * #MHD_websocket_stream_init2().
+   */
+  MHD_WEBSOCKET_STATUS_BINARY_LAST_FRAGMENT = 0x42,
   /**
    * The call failed and the stream is invalid now for decoding.
    * You must close the websocket now using #MHD_upgrade_action()
    * with #MHD_UPGRADE_ACTION_CLOSE.
-   * You can send a close frame before closing.
+   * You may send a close frame before closing.
    * This is only used by #MHD_websocket_decode() and happens
    * if the stream contains errors (i. e. invalid byte data).
    */
@@ -259,10 +281,12 @@ enum MHD_WEBSOCKET_STATUS
    * been marked invalid.
    * You must close the websocket now using #MHD_upgrade_action()
    * with #MHD_UPGRADE_ACTION_CLOSE.
-   * You can send a close frame before closing.
+   * You may send a close frame before closing.
    * This is only used by #MHD_websocket_decode() and happens
-   * if you call #MDM_websocket_decode() again after is
+   * if you call #MDM_websocket_decode() again after
    * has been invalidated.
+   * You can call #MHD_websocket_stream_is_valid() at any time
+   * to check whether a stream is invalid or not.
    */
   MHD_WEBSOCKET_STATUS_STREAM_BROKEN = -2,
   /**
@@ -271,8 +295,8 @@ enum MHD_WEBSOCKET_STATUS
    * 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
-   * #MHD_websocket_stream_init() or #MHD_websocket_stream_init2() then to
-   * avoid this and close the frame instead.
+   * #MHD_websocket_stream_init() or #MHD_websocket_stream_init2() to
+   * avoid this and close the websocket instead.
    */
   MHD_WEBSOCKET_STATUS_MEMORY_ERROR = -3,
   /**
@@ -286,28 +310,39 @@ enum MHD_WEBSOCKET_STATUS
    * If you got this return code from #MHD_websocket_decode() then
    * the stream becomes invalid and the websocket must be closed
    * using #MHD_upgrade_action() with #MHD_UPGRADE_ACTION_CLOSE.
-   * You can send a close frame before closing.
+   * You may send a close frame before closing.
    * The maximum payload size is specified during the call of
    * #MHD_websocket_stream_init() or #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 GB on 32 bit systems).
+   * (i. e. more than 4 GiB on 32 bit systems).
    * If you got this return code from #MHD_websocket_encode_close(),
    * #MHD_websocket_encode_ping() or #MHD_websocket_encode_pong() then
    * you passed to much payload data. The stream remains valid then.
    */
   MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED = -5,
   /**
-   * An UTF-8 text is invalid.
+   * An UTF-8 sequence is invalid.
    * If you got this return code from #MHD_websocket_decode() then
    * the stream becomes invalid and you must close the websocket
    * using #MHD_upgrade_action() with #MHD_UPGRADE_ACTION_CLOSE.
-   * You can send a close frame before closing.
+   * You may send a close frame before closing.
    * If you got this from #MHD_websocket_encode_text() or
    * #MHD_websocket_encode_close() then you passed invalid UTF-8 text.
    * The stream remains valid then.
    */
-  MHD_WEBSOCKET_STATUS_UTF8_ENCODING_ERROR = -6
+  MHD_WEBSOCKET_STATUS_UTF8_ENCODING_ERROR = -6,
+  /**
+   * 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:
+   * * #MHD_websocket_check_http_version()
+   * * #MHD_websocket_check_connection_header()
+   * * #MHD_websocket_check_upgrade_header()
+   * * #MHD_websocket_check_version_header()
+   * * #MHD_websocket_create_accept_header()
+   */
+  MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER = -7
 };
 
 /**
@@ -332,22 +367,22 @@ enum MHD_WEBSOCKET_CLOSEREASON
    * This value is used as placeholder for #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 a result of decoding, because this value
-   * is not a valid close reason for the WebSocket protocol.
+   * This value cannot be a result of decoding, because this value
+   * is not a valid close reason for the websocket protocol.
    */
   MHD_WEBSOCKET_CLOSEREASON_NO_REASON = 0,
   /**
-   * You close the websocket fulfilled its purpose and shall
+   * You close the websocket because it fulfilled its purpose and shall
    * now be closed in a normal, planned way.
    */
   MHD_WEBSOCKET_CLOSEREASON_REGULAR = 1000,
   /**
-   * You close the websocket because are shutting down the server or
+   * You close the websocket because you are shutting down the server or
    * something similar.
    */
   MHD_WEBSOCKET_CLOSEREASON_GOING_AWAY = 1001,
   /**
-   * You close the websocket because you a protocol error occurred
+   * You close the websocket because a protocol error occurred
    * during decoding (i. e. invalid byte data).
    */
   MHD_WEBSOCKET_CLOSEREASON_PROTOCOL_ERROR = 1002,
@@ -371,7 +406,8 @@ enum MHD_WEBSOCKET_CLOSEREASON
    */
   MHD_WEBSOCKET_CLOSEREASON_POLICY_VIOLATED = 1008,
   /**
-   * You close the websocket because you received a frame which is too big to process.
+   * 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
    * #MHD_websocket_stream_init() or #MHD_websocket_stream_init2().
    */
@@ -497,61 +533,170 @@ enum MHD_WEBSOCKET_VALIDITY
   MHD_WEBSOCKET_VALIDITY_ONLY_VALID_FOR_CONTROL_FRAMES = 2
 };
 /**
- * This method is called by many websocket
- * functions for allocating data.
- * By default 'malloc' is used.
- * This can be used for operating systems like Windows
- * where malloc, realloc and free are compiler dependent.
+ * This callback function is used internally by many websocket functions
+ * for allocating data.
+ * By default `malloc()` is used.
+ * You can use your own allocation function with
+ * #MHD_websocket_stream_init2() if you wish to.
+ * This can be useful for operating systems like Windows
+ * where `malloc()`, `realloc()` and `free()` are compiler-dependent.
+ * You can call the associated `malloc()` callback of
+ * a websocket stream with #MHD_websocket_malloc().
  *
- * @param len new size
+ * @param buf_len buffer size in bytes
  * @return allocated memory
  * @ingroup websocket
  */
 typedef void*
-(*MHD_WebSocketMallocCallback) (size_t len);
+(*MHD_WebSocketMallocCallback) (size_t buf_len);
 /**
- * This method is called by many websocket
+ * This callback function is used internally by many websocket
  * functions for reallocating data.
- * By default 'realloc' is used.
- * This can be used for operating systems like Windows
- * where malloc, realloc and free are compiler dependent.
+ * By default `realloc()` is used.
+ * You can use your own reallocation function with
+ * #MHD_websocket_stream_init2() if you wish to.
+ * This can be useful for operating systems like Windows
+ * where `malloc()`, `realloc()` and `free()` are compiler-dependent.
+ * You can call the associated `realloc()` callback of
+ * a websocket stream with #MHD_websocket_realloc().
  *
- * @param cls closure
- * @param len new size
+ * @param buf buffer
+ * @param new_buf_len new buffer size in bytes
  * @return reallocated memory
  * @ingroup websocket
  */
 typedef void*
-(*MHD_WebSocketReallocCallback) (void *cls, size_t len);
+(*MHD_WebSocketReallocCallback) (void *buf, size_t new_buf_len);
 /**
- * This method is called by many websocket
+ * This callback function is used internally by many websocket
  * functions for freeing data.
- * By default 'free' is used.
- * This can be used for operating systems like Windows
- * where malloc, realloc and free are compiler dependent.
+ * By default `free()` is used.
+ * You can use your own free function with
+ * #MHD_websocket_stream_init2() if you wish to.
+ * This can be useful for operating systems like Windows
+ * where `malloc()`, `realloc()` and `free()` are compiler-dependent.
+ * You can call the associated `free()` callback of
+ * a websocket stream with #MHD_websocket_free().
  *
- * @param cls closure
+ * @param buf buffer
  * @ingroup websocket
  */
 typedef void
-(*MHD_WebSocketFreeCallback) (void *cls);
+(*MHD_WebSocketFreeCallback) (void *buf);
+/**
+ * This callback function is used for generating random numbers
+ * for masking payload data in client mode.
+ * If you use websockets in server mode with libmicrohttpd then
+ * you don't need a random number generator, because
+ * the server doesn't mask its outgoing messageses.
+ * However if you wish to use a websocket stream in client mode,
+ * you must pass this callback function to #MHD_websocket_stream_init2().
+ *
+ * @param cls closure specified in #MHD_websocket_stream_init2()
+ * @param buf buffer to fill with random values
+ * @param buf_len size of buffer in bytes
+ * @return The number of generated random bytes.
+ *         Should usually equal to buf_len.
+ * @ingroup websocket
+ */
+typedef size_t
+(*MHD_WebSocketRandomNumberGenerator) (void *cls, void* buf, size_t buf_len);
+
+/**
+ * Checks the HTTP version of the incoming request.
+ * Websocket requests are only allowed for HTTP/1.1 or above.
+ *
+ * @param http_version The value of the 'version' parameter of your
+ *                     access_handler callback
+ * @return A value of `enum MHD_WEBSOCKET_STATUS`.
+ *         0 means the HTTP version is correct for a websocket request,
+ *         a value less than zero means that the HTTP version isn't
+ *         valid for a websocket request.
+ * @ingroup websocket
+ */
+_MHD_EXTERN enum MHD_WEBSOCKET_STATUS
+MHD_websocket_check_http_version (const char* http_version);
+
+/**
+ * Checks the value of the 'Connection' HTTP request header.
+ * Websocket requests require the token 'Upgrade' in
+ * the 'Connection' HTTP request header.
+ *
+ * @param connection_header The value of the 'Connection' request header.
+ *                          You can get this request header value by passing
+ *                          #MHD_HTTP_HEADER_CONNECTION to
+ *                          #MHD_lookup_connection_value().
+ * @return A value of `enum MHD_WEBSOCKET_STATUS`.
+ *         0 means the 'Connection' request header is correct
+ *         for a websocket request,
+ *         a value less than zero means that the 'Connection' header isn't
+ *         valid for a websocket request.
+ * @ingroup websocket
+ */
+_MHD_EXTERN enum MHD_WEBSOCKET_STATUS
+MHD_websocket_check_connection_header (const char* connection_header);
+
+/**
+ * Checks the value of the 'Upgrade' HTTP request header.
+ * Websocket requests require the value 'websocket' in
+ * the 'Upgrade' HTTP request header.
+ *
+ * @param upgrade_header The value of the 'Upgrade' request header.
+ *                       You can get this request header value by passing
+ *                       #MHD_HTTP_HEADER_UPGRADE to
+ *                       #MHD_lookup_connection_value().
+ * @return A value of `enum MHD_WEBSOCKET_STATUS`.
+ *         0 means the 'Upgrade' request header is correct
+ *         for a websocket request,
+ *         a value less than zero means that the 'Upgrade' header isn't
+ *         valid for a websocket request.
+ * @ingroup websocket
+ */
+_MHD_EXTERN enum MHD_WEBSOCKET_STATUS
+MHD_websocket_check_upgrade_header (const char* upgrade_header);
 
 /**
- * Creates the response value for the incoming 'Sec-WebSocket-Key' header.
- * The generated value must be sent to the client as 'Sec-WebSocket-Accept' response header.
+ * Checks the value of the 'Sec-WebSocket-Version' HTTP request header.
+ * Websocket requests require the value '13'
+ * in the 'Sec-WebSocket-Version' HTTP request header.
  *
- * @param sec_websocket_key The value of the 'Sec-WebSocket-Key' request header
+ * @param version_header The value of the 'Sec-WebSocket-Version'
+ *                       request header.
+ *                       You can get this request header value by passing
+ *                       #MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION to
+ *                       #MHD_lookup_connection_value().
+ * @return A value of `enum MHD_WEBSOCKET_STATUS`.
+ *         0 means the 'Sec-WebSocket-Version' request header is correct
+ *         for a websocket request,
+ *         a value less than zero means that the 'Sec-WebSocket-Version'
+ *         header isn't valid for a websocket request.
+ * @ingroup websocket
+ */
+_MHD_EXTERN enum MHD_WEBSOCKET_STATUS
+MHD_websocket_check_version_header (const char* version_header);
+
+/**
+ * Creates the response value for the 'Sec-WebSocket-Key' HTTP request header.
+ * The generated value must be sent to the client
+ * as 'Sec-WebSocket-Accept' HTTP response header.
+ *
+ * @param sec_websocket_key The value of the 'Sec-WebSocket-Key'
+ *                          request header.
+ *                          You can get this request header value by passing
+ *                          #MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY to
+ *                          #MHD_lookup_connection_value().
  * @param[out] sec_websocket_accept The response buffer, which will receive
  *                                  the generated 'Sec-WebSocket-Accept' header.
  *                                  This buffer must be at least 29 bytes long and
- *                                  will contain a terminating NUL character.
+ *                                  will contain the response value plus
+ *                                  a terminating NUL on success.
  * @return A value of `enum MHD_WEBSOCKET_STATUS`.
  *         Typically 0 on success or less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
-MHD_websocket_create_accept (const char*sec_websocket_key,
-                             char*sec_websocket_accept);
+_MHD_EXTERN enum MHD_WEBSOCKET_STATUS
+MHD_websocket_create_accept_header (const char* sec_websocket_key,
+                                    char* sec_websocket_accept);
 
 /**
  * Creates a new websocket stream, used for decoding/encoding.
@@ -559,13 +704,13 @@ MHD_websocket_create_accept (const char*sec_websocket_key,
  * @param[out] ws The websocket stream
  * @param flags Combination of `enum MHD_WEBSOCKET_FLAG` values
  *              to modify the behavior of the websocket stream.
- * @param max_message_size The maximum size for incoming payload
+ * @param max_payload_size The maximum size for incoming payload
  *                         data in bytes. Use 0 to allow each size.
  * @return A value of `enum MHD_WEBSOCKET_STATUS`.
  *         Typically 0 on success or less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
+_MHD_EXTERN enum MHD_WEBSOCKET_STATUS
 MHD_websocket_stream_init (struct MHD_WebSocketStream**ws,
                            int flags,
                            size_t max_payload_size);
@@ -573,26 +718,42 @@ MHD_websocket_stream_init (struct MHD_WebSocketStream**ws,
 /**
  * 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.
  *
  * @param[out] ws The websocket stream
  * @param flags Combination of `enum MHD_WEBSOCKET_FLAG` values
  *              to modify the behavior of the websocket stream.
- * @param max_message_size The maximum size for incoming payload
+ * @param max_payload_size The maximum size for incoming payload
  *                         data in bytes. Use 0 to allow each size.
- * @param callback_malloc  The callback function for 'malloc'.
- * @param callback_realloc The callback function for 'realloc'.
- * @param callback_free    The callback function for 'free'.
+ * @param callback_malloc  The callback function for `malloc()`.
+ * @param callback_realloc The callback function for `realloc()`.
+ * @param callback_free    The callback function for `free()`.
+ * @param cls_rng          A closure for the random number generator callback.
+ *                         This is only required when
+ *                         MHD_WEBSOCKET_FLAG_CLIENT is passed in `flags`.
+ *                         The given value is passed to
+ *                         the random number generator.
+ *                         May be NULL if not needed.
+ *                         Should be NULL when you are
+ *                         not using MHD_WEBSOCKET_FLAG_CLIENT.
+ * @param callback_rng     A callback function for a
+ *                         secure random number generator.
+ *                         This is only required when
+ *                         MHD_WEBSOCKET_FLAG_CLIENT is passed in `flags`.
+ *                         Should be NULL otherwise.
  * @return A value of `enum MHD_WEBSOCKET_STATUS`.
  *         Typically 0 on success or less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
+_MHD_EXTERN 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);
+                            MHD_WebSocketFreeCallback callback_free,
+                            void* cls_rng,
+                            MHD_WebSocketRandomNumberGenerator callback_rng);
 
 /**
  * Frees a websocket stream
@@ -602,7 +763,7 @@ MHD_websocket_stream_init2 (struct MHD_WebSocketStream**ws,
  *         Typically 0 on success or less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
+_MHD_EXTERN enum MHD_WEBSOCKET_STATUS
 MHD_websocket_stream_free (struct MHD_WebSocketStream*ws);
 
 /**
@@ -615,7 +776,7 @@ MHD_websocket_stream_free (struct MHD_WebSocketStream*ws);
  *         Typically 0 on success or less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
+_MHD_EXTERN enum MHD_WEBSOCKET_STATUS
 MHD_websocket_stream_invalidate (struct MHD_WebSocketStream*ws);
 
 /**
@@ -627,11 +788,11 @@ MHD_websocket_stream_invalidate (struct MHD_WebSocketStream*ws);
  * @return A value of `enum MHD_WEBSOCKET_VALIDITY`.
  * @ingroup websocket
  */
-_MHD_EXTERN int
+_MHD_EXTERN enum MHD_WEBSOCKET_VALIDITY
 MHD_websocket_stream_is_valid (struct MHD_WebSocketStream*ws);
 
 /**
- * Decodes a byte sequence via this websocket stream.
+ * 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.
  *
@@ -644,11 +805,11 @@ MHD_websocket_stream_is_valid (struct MHD_WebSocketStream*ws);
  *                                than @a streambuf_len when a frame is decoded
  *                                before the end of the buffer is reached.
  *                                The remaining bytes of @a buf must be passed
- *                                in the following decoding.
- * @param[out] payload This variable receives a buffer with the decoded
- *                     payload data.
+ *                                to the next call of this function.
+ * @param[out] payload Pointer to a variable, which receives a buffer
+ *                     with the decoded payload data.
  *                     If no decoded data is available this is NULL.
- *                     When this variable is not NULL then
+ *                     When the returned value is not NULL then
  *                     the buffer contains always @a payload_len bytes plus
  *                     one terminating NUL character.
  *                     The caller must free this buffer
@@ -657,11 +818,11 @@ MHD_websocket_stream_is_valid (struct MHD_WebSocketStream*ws);
  *                     #MHD_WEBSOCKET_FLAG_GENERATE_CLOSE_FRAMES_ON_ERROR
  *                     upon creation of this websocket stream and
  *                     a decoding error occurred
- *                     (return value less than 0), then this
+ *                     (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 #MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
- *                     upon creation of this websocket stream then
+ *                     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.
@@ -670,58 +831,58 @@ MHD_websocket_stream_is_valid (struct MHD_WebSocketStream*ws);
  * @param[out] payload_len The length of the result payload buffer in bytes.
  *
  * @return A value of `enum MHD_WEBSOCKET_STATUS`.
- *         This is greater than 0 if a frame has is complete, equal to 0 if more data
- *         is needed an less than 0 on errors.
+ *         This is greater than 0 if a frame has is complete,
+ *         equal to 0 if more data is needed an less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
-MHD_websocket_decode (struct MHD_WebSocketStream*ws,
-                      const char*streambuf,
+_MHD_EXTERN 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);
+                      size_t* streambuf_read_len,
+                      char** payload,
+                      size_t* payload_len);
 
 /**
- * Splits the payload of of a decoded close frame.
+ * Splits the payload of a decoded close frame.
  *
  * @param payload The payload of the close frame.
- *                This parameter may be NULL if @a payload_len is 0.
+ *                This parameter may only be NULL if @a payload_len is 0.
  * @param payload_len The length of @a payload.
  * @param[out] reason_code The numeric close reason.
  *                         If there was no close reason, this is
  *                         #MHD_WEBSOCKET_CLOSEREASON_NO_REASON.
  *                         Compare with `enum MHD_WEBSOCKET_CLOSEREASON`.
- *                         This parameter is optional and can be NULL.
+ *                         This parameter is optional and may be NULL.
  * @param[out] reason_utf8 The literal close reason.
  *                         If there was no literal close reason, this is NULL.
- *                         This parameter is optional and can be NULL.
+ *                         This parameter is optional and may be NULL.
  *                         Please note that no memory is allocated
  *                         in this function.
  *                         If not NULL the returned value of this parameter
  *                         points to a position in the specified @a payload.
  * @param[out] reason_utf8_len The length of the literal close reason.
  *                             If there was no literal close reason, this is 0.
- *                             This parameter is optional and can be NULL.
+ *                             This parameter is optional and may be NULL.
  *
  * @return A value of `enum MHD_WEBSOCKET_STATUS`.
  *         This is #MHD_WEBSOCKET_STATUS_OK (= 0) on success
  *         or a value less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
-MHD_websocket_split_close_reason (const char*payload,
+_MHD_EXTERN 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);
+                                  unsigned short* reason_code,
+                                  const char** reason_utf8,
+                                  size_t* reason_utf8_len);
 
 /**
  * Encodes an UTF-8 encoded text into websocket text frame.
  *
  * @param ws The websocket stream.
  * @param payload_utf8 The UTF-8 encoded text to send.
- *                     This can be NULL if payload_utf8_len is 0.
+ *                     This may be NULL if payload_utf8_len is 0.
  * @param payload_utf8_len The length of the UTF-8 encoded text in bytes.
  * @param fragmentation A value of `enum MHD_WEBSOCKET_FRAGMENTATION`
  *                      to specify the fragmentation behavior.
@@ -735,11 +896,11 @@ MHD_websocket_split_close_reason (const char*payload,
  *                   The caller must free this buffer using #MHD_websocket_free().
  * @param[out] frame_len The length of the encoded frame in bytes.
  * @param[out] utf8_step This parameter is required for fragmentation and
- *                       can be NULL if no fragmentation is used.
+ *                       should be NULL if no fragmentation is used.
  *                       It contains information about the last encoded
  *                       UTF-8 sequence and is required to continue a previous
  *                       UTF-8 sequence when fragmentation is used.
- *                       The `enum MHD_WEBSOCKET_UTF8STEP` is for this.
+ *                       `enum MHD_WEBSOCKET_UTF8STEP` is for this value.
  *                       If you start a new fragment using
  *                       MHD_WEBSOCKET_FRAGMENTATION_NONE or
  *                       MHD_WEBSOCKET_FRAGMENTATION_FIRST the value
@@ -751,17 +912,17 @@ MHD_websocket_split_close_reason (const char*payload,
  *         or a value less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
-MHD_websocket_encode_text (struct MHD_WebSocketStream*ws,
-                           const char*payload_utf8,
+_MHD_EXTERN 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);
+                           char** frame,
+                           size_t* frame_len,
+                           int* utf8_step);
 
 /**
- * Encodes a binary data into websocket binary frame.
+ * Encodes binary data into websocket binary frame.
  *
  * @param ws The websocket stream.
  * @param payload The binary data to send.
@@ -786,13 +947,13 @@ MHD_websocket_encode_text (struct MHD_WebSocketStream*ws,
  *         or a value less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
-MHD_websocket_encode_binary (struct MHD_WebSocketStream*ws,
-                             const char*payload,
+_MHD_EXTERN 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);
+                             char** frame,
+                             size_t* frame_len);
 
 /**
  * Encodes a websocket ping frame
@@ -815,18 +976,18 @@ MHD_websocket_encode_binary (struct MHD_WebSocketStream*ws,
  *         or a value less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
-MHD_websocket_encode_ping (struct MHD_WebSocketStream*ws,
-                           const char*payload,
+_MHD_EXTERN 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);
+                           char** frame,
+                           size_t* frame_len);
 
 /**
  * Encodes a websocket pong frame
  *
  * @param ws The websocket stream.
- * @param payload The binary pong payload data, which is typically
+ * @param payload The binary pong payload data, which should be
  *                the decoded payload from the received ping frame.
  *                This may be NULL if @a payload_len is 0.
  * @param payload_len The length of the payload data in bytes.
@@ -848,12 +1009,12 @@ MHD_websocket_encode_ping (struct MHD_WebSocketStream*ws,
  *         or a value less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
-MHD_websocket_encode_pong (struct MHD_WebSocketStream*ws,
-                           const char*payload,
-                           size_t payload_len,
-                           char**frame,
-                           size_t*frame_len);
+_MHD_EXTERN 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);
 
 /**
  * Encodes a websocket close frame
@@ -890,58 +1051,35 @@ MHD_websocket_encode_pong (struct MHD_WebSocketStream*ws,
  *         or a value less than 0 on errors.
  * @ingroup websocket
  */
-_MHD_EXTERN int
-MHD_websocket_encode_close (struct MHD_WebSocketStream*ws,
+_MHD_EXTERN enum MHD_WEBSOCKET_STATUS
+MHD_websocket_encode_close (struct MHD_WebSocketStream* ws,
                             unsigned short reason_code,
-                            const char*reason_utf8,
+                            const char* reason_utf8,
                             size_t reason_utf8_len,
-                            char**frame,
-                            size_t*frame_len);
-
-/**
- * Sets the seed for the random number generated used for
- * the generation of masked frames (this is only used for client websockets).
- * This seed is used for all websocket streams.
- * Internally `srand()` is called.
- * Please note that on some situations
- * (where `rand()` and `srand()` are shared between your program
- * and this library) this could cause unwanted results in your program if
- * your program relies on a specific seed.
- *
- * @param seed The seed used for the initialization of
- *             the pseudo random number generator.
- *             Typically `time(NULL)` is used here to
- *             generate a seed.
- *
- * @return A value of `enum MHD_WEBSOCKET_STATUS`.
- *         This is #MHD_WEBSOCKET_STATUS_OK (= 0) on success
- *         or a value less than 0 on errors.
- * @ingroup websocket
- */
-_MHD_EXTERN int
-MHD_websocket_srand (unsigned long seed);
+                            char** frame,
+                            size_t* frame_len);
 
 /**
  * Allocates memory with the associated 'malloc' function
  * of the websocket stream
  *
  * @param ws The websocket stream.
- * @param len The length of the memory to allocate in bytes
+ * @param buf_len The length of the memory to allocate in bytes
  *
  * @return The allocated memory on success or NULL on failure.
  * @ingroup websocket
  */
 _MHD_EXTERN void*
-MHD_websocket_malloc (struct MHD_WebSocketStream*ws,
-                      size_t len);
+MHD_websocket_malloc (struct MHD_WebSocketStream* ws,
+                      size_t buf_len);
 
 /**
  * Reallocates memory with the associated 'realloc' function
  * of the websocket stream
  *
  * @param ws The websocket stream.
- * @param cls The previously allocated memory or NULL
- * @param len The new length of the memory in bytes
+ * @param buf The previously allocated memory or NULL
+ * @param new_buf_len The new length of the memory in bytes
  *
  * @return The allocated memory on success or NULL on failure.
  *         If NULL is returned the previously allocated buffer
@@ -949,16 +1087,16 @@ MHD_websocket_malloc (struct MHD_WebSocketStream*ws,
  * @ingroup websocket
  */
 _MHD_EXTERN void*
-MHD_websocket_realloc (struct MHD_WebSocketStream*ws,
-                       void*cls,
-                       size_t len);
+MHD_websocket_realloc (struct MHD_WebSocketStream* ws,
+                       void* buf,
+                       size_t new_buf_len);
 
 /**
  * Frees memory with the associated 'free' function
  * of the websocket stream
  *
  * @param ws The websocket stream.
- * @param cls The previously allocated memory or NULL
+ * @param buf The previously allocated memory or NULL
  *
  * @return A value of `enum MHD_WEBSOCKET_STATUS`.
  *         This is #MHD_WEBSOCKET_STATUS_OK (= 0) on success
@@ -966,8 +1104,8 @@ MHD_websocket_realloc (struct MHD_WebSocketStream*ws,
  * @ingroup websocket
  */
 _MHD_EXTERN int
-MHD_websocket_free (struct MHD_WebSocketStream*ws,
-                    void*cls);
+MHD_websocket_free (struct MHD_WebSocketStream* ws,
+                    void* buf);
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {