GNU libmicrohttpd 0.9.77
Loading...
Searching...
No Matches
microhttpd_ws.h File Reference

interface for experimental web socket extension to libmicrohttpd More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef void *(* MHD_WebSocketMallocCallback) (size_t buf_len)
 
typedef void *(* MHD_WebSocketReallocCallback) (void *buf, size_t new_buf_len)
 
typedef void(* MHD_WebSocketFreeCallback) (void *buf)
 
typedef size_t(* MHD_WebSocketRandomNumberGenerator) (void *cls, void *buf, size_t buf_len)
 

Enumerations

enum  MHD_WEBSOCKET_FLAG {
  MHD_WEBSOCKET_FLAG_SERVER = 0 , MHD_WEBSOCKET_FLAG_CLIENT = 1 , MHD_WEBSOCKET_FLAG_NO_FRAGMENTS = 0 , MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS = 2 ,
  MHD_WEBSOCKET_FLAG_GENERATE_CLOSE_FRAMES_ON_ERROR = 4
}
 Flags for the initialization of a websocket stream struct MHD_WebSocketStream used by MHD_websocket_stream_init() or MHD_websocket_stream_init2(). More...
 
enum  MHD_WEBSOCKET_FRAGMENTATION { MHD_WEBSOCKET_FRAGMENTATION_NONE = 0 , MHD_WEBSOCKET_FRAGMENTATION_FIRST = 1 , MHD_WEBSOCKET_FRAGMENTATION_FOLLOWING = 2 , MHD_WEBSOCKET_FRAGMENTATION_LAST = 3 }
 Enum to specify the fragmenting behavior while encoding with MHD_websocket_encode_text() or MHD_websocket_encode_binary(). More...
 
enum  MHD_WEBSOCKET_STATUS {
  MHD_WEBSOCKET_STATUS_OK = 0 , MHD_WEBSOCKET_STATUS_TEXT_FRAME = 0x1 , MHD_WEBSOCKET_STATUS_BINARY_FRAME = 0x2 , MHD_WEBSOCKET_STATUS_CLOSE_FRAME = 0x8 ,
  MHD_WEBSOCKET_STATUS_PING_FRAME = 0x9 , MHD_WEBSOCKET_STATUS_PONG_FRAME = 0xA , MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT = 0x11 , MHD_WEBSOCKET_STATUS_BINARY_FIRST_FRAGMENT = 0x12 ,
  MHD_WEBSOCKET_STATUS_TEXT_NEXT_FRAGMENT = 0x21 , MHD_WEBSOCKET_STATUS_BINARY_NEXT_FRAGMENT = 0x22 , MHD_WEBSOCKET_STATUS_TEXT_LAST_FRAGMENT = 0x41 , MHD_WEBSOCKET_STATUS_BINARY_LAST_FRAGMENT = 0x42 ,
  MHD_WEBSOCKET_STATUS_PROTOCOL_ERROR = -1 , MHD_WEBSOCKET_STATUS_STREAM_BROKEN = -2 , MHD_WEBSOCKET_STATUS_MEMORY_ERROR = -3 , MHD_WEBSOCKET_STATUS_PARAMETER_ERROR = -4 ,
  MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED = -5 , MHD_WEBSOCKET_STATUS_UTF8_ENCODING_ERROR = -6 , MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER = -7
}
 Enum of the return value for almost every MHD_websocket function. Errors are negative and values equal to or above zero mean a success. Positive values are only used by MHD_websocket_decode(). More...
 
enum  MHD_WEBSOCKET_CLOSEREASON {
  MHD_WEBSOCKET_CLOSEREASON_NO_REASON = 0 , MHD_WEBSOCKET_CLOSEREASON_REGULAR = 1000 , MHD_WEBSOCKET_CLOSEREASON_GOING_AWAY = 1001 , MHD_WEBSOCKET_CLOSEREASON_PROTOCOL_ERROR = 1002 ,
  MHD_WEBSOCKET_CLOSEREASON_UNSUPPORTED_DATATYPE = 1003 , MHD_WEBSOCKET_CLOSEREASON_MALFORMED_UTF8 = 1007 , MHD_WEBSOCKET_CLOSEREASON_POLICY_VIOLATED = 1008 , MHD_WEBSOCKET_CLOSEREASON_MAXIMUM_ALLOWED_PAYLOAD_SIZE_EXCEEDED = 1009 ,
  MHD_WEBSOCKET_CLOSEREASON_MISSING_EXTENSION = 1010 , MHD_WEBSOCKET_CLOSEREASON_UNEXPECTED_CONDITION = 1011
}
 Enumeration of possible close reasons for close frames. More...
 
enum  MHD_WEBSOCKET_UTF8STEP {
  MHD_WEBSOCKET_UTF8STEP_NORMAL = 0 , MHD_WEBSOCKET_UTF8STEP_UTF2TAIL_1OF1 = 1 , MHD_WEBSOCKET_UTF8STEP_UTF3TAIL1_1OF2 = 2 , MHD_WEBSOCKET_UTF8STEP_UTF3TAIL2_1OF2 = 3 ,
  MHD_WEBSOCKET_UTF8STEP_UTF3TAIL_1OF2 = 4 , MHD_WEBSOCKET_UTF8STEP_UTF3TAIL_2OF2 = 5 , MHD_WEBSOCKET_UTF8STEP_UTF4TAIL1_1OF3 = 6 , MHD_WEBSOCKET_UTF8STEP_UTF4TAIL2_1OF3 = 7 ,
  MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_1OF3 = 8 , MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_2OF3 = 9 , MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_3OF3 = 10
}
 Enumeration of possible UTF-8 check steps. More...
 
enum  MHD_WEBSOCKET_VALIDITY { MHD_WEBSOCKET_VALIDITY_INVALID = 0 , MHD_WEBSOCKET_VALIDITY_VALID = 1 , MHD_WEBSOCKET_VALIDITY_ONLY_VALID_FOR_CONTROL_FRAMES = 2 }
 Enumeration of validity values. More...
 

Functions

_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_check_http_version (const char *http_version)
 
_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_check_connection_header (const char *connection_header)
 
_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_check_upgrade_header (const char *upgrade_header)
 
_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_check_version_header (const char *version_header)
 
_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_create_accept_header (const char *sec_websocket_key, char *sec_websocket_accept)
 
_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_stream_init (struct MHD_WebSocketStream **ws, int flags, size_t max_payload_size)
 
_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, void *cls_rng, MHD_WebSocketRandomNumberGenerator callback_rng)
 
_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_stream_free (struct MHD_WebSocketStream *ws)
 
_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_stream_invalidate (struct MHD_WebSocketStream *ws)
 
_MHD_EXTERN enum MHD_WEBSOCKET_VALIDITY MHD_websocket_stream_is_valid (struct MHD_WebSocketStream *ws)
 
_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)
 
_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)
 
_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)
 
_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)
 
_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)
 
_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)
 
_MHD_EXTERN 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)
 
_MHD_EXTERN void * MHD_websocket_malloc (struct MHD_WebSocketStream *ws, size_t buf_len)
 
_MHD_EXTERN void * MHD_websocket_realloc (struct MHD_WebSocketStream *ws, void *buf, size_t new_buf_len)
 
_MHD_EXTERN int MHD_websocket_free (struct MHD_WebSocketStream *ws, void *buf)
 

Detailed Description

interface for experimental web socket extension to libmicrohttpd

Author
David Gausmann

Definition in file microhttpd_ws.h.

Typedef Documentation

◆ MHD_WebSocketFreeCallback

typedef void(* MHD_WebSocketFreeCallback) (void *buf)

This callback function is used internally by many websocket functions for freeing data. 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().

Parameters
bufbuffer

Definition at line 591 of file microhttpd_ws.h.

◆ MHD_WebSocketMallocCallback

typedef void *(* MHD_WebSocketMallocCallback) (size_t buf_len)

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().

Parameters
buf_lenbuffer size in bytes
Returns
allocated memory

Definition at line 557 of file microhttpd_ws.h.

◆ MHD_WebSocketRandomNumberGenerator

typedef size_t(* MHD_WebSocketRandomNumberGenerator) (void *cls, void *buf, size_t buf_len)

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().

Parameters
clsclosure specified in MHD_websocket_stream_init2()
bufbuffer to fill with random values
buf_lensize of buffer in bytes
Returns
The number of generated random bytes. Should usually equal to buf_len.

Definition at line 609 of file microhttpd_ws.h.

◆ MHD_WebSocketReallocCallback

typedef void *(* MHD_WebSocketReallocCallback) (void *buf, size_t new_buf_len)

This callback function is used internally by many websocket functions for reallocating data. 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().

Parameters
bufbuffer
new_buf_lennew buffer size in bytes
Returns
reallocated memory

Definition at line 575 of file microhttpd_ws.h.

Enumeration Type Documentation

◆ MHD_WEBSOCKET_CLOSEREASON

Enumeration of possible close reasons for 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: 0-999 are never used (if you pass 0 in MHD_websocket_encode_close() then no close reason is used). 1000-2999 are specified by RFC 6455. 3000-3999 are specified by libraries, etc. but must be registered by IANA. 4000-4999 are reserved for private use.

Enumerator
MHD_WEBSOCKET_CLOSEREASON_NO_REASON 

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 be a result of decoding, because this value is not a valid close reason for the websocket protocol.

MHD_WEBSOCKET_CLOSEREASON_REGULAR 

You close the websocket because it fulfilled its purpose and shall now be closed in a normal, planned way.

MHD_WEBSOCKET_CLOSEREASON_GOING_AWAY 

You close the websocket because you are shutting down the server or something similar.

MHD_WEBSOCKET_CLOSEREASON_PROTOCOL_ERROR 

You close the websocket because a protocol error occurred during decoding (i. e. invalid byte data).

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.

MHD_WEBSOCKET_CLOSEREASON_MALFORMED_UTF8 

You close the websocket because it contains malformed UTF-8. The UTF-8 validity is automatically checked by MHD_websocket_decode(), so you don't need to check it on your own. UTF-8 is specified in RFC 3629.

MHD_WEBSOCKET_CLOSEREASON_POLICY_VIOLATED 

You close the websocket because of any reason. Usually this close reason is used if no other close reason is more specific or if you don't want to use any other close reason.

MHD_WEBSOCKET_CLOSEREASON_MAXIMUM_ALLOWED_PAYLOAD_SIZE_EXCEEDED 

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().

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.

MHD_WEBSOCKET_CLOSEREASON_UNEXPECTED_CONDITION 

The server closes the websocket because it encountered an unexpected condition that prevented it from fulfilling the request.

Definition at line 371 of file microhttpd_ws.h.

◆ MHD_WEBSOCKET_FLAG

Flags for the initialization of a websocket stream struct MHD_WebSocketStream used by MHD_websocket_stream_init() or MHD_websocket_stream_init2().

Enumerator
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 MHD_WEBSOCKET_FLAG_CLIENT

MHD_WEBSOCKET_FLAG_CLIENT 

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. 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_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 MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS

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 MHD_WEBSOCKET_FLAG_NO_FRAGMENTS

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 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 with MHD_websocket_free().

Definition at line 58 of file microhttpd_ws.h.

◆ MHD_WEBSOCKET_FRAGMENTATION

Enum to specify the fragmenting behavior while encoding with MHD_websocket_encode_text() or MHD_websocket_encode_binary().

Enumerator
MHD_WEBSOCKET_FRAGMENTATION_NONE 

You don't want to use fragmentation. The encoded frame consists of only one frame.

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.

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.

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.

Definition at line 120 of file microhttpd_ws.h.

◆ MHD_WEBSOCKET_STATUS

Enum of the return value for almost every MHD_websocket function. Errors are negative and values equal to or above zero mean a success. Positive values are only used by MHD_websocket_decode().

Enumerator
MHD_WEBSOCKET_STATUS_OK 

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_TEXT_FRAME 

MHD_websocket_decode() has decoded a text frame. The parameters payload and payload_len are filled with the decoded text (if any).

MHD_WEBSOCKET_STATUS_BINARY_FRAME 

MHD_websocket_decode() has decoded a binary frame. The parameters payload and payload_len are filled with the decoded binary data (if any).

MHD_WEBSOCKET_STATUS_CLOSE_FRAME 

MHD_websocket_decode() has decoded a close frame. 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 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. You can call MHD_websocket_split_close_reason() to split that close reason.

MHD_WEBSOCKET_STATUS_PING_FRAME 

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 payload and payload_len are filled with the binary ping data (if any).

MHD_WEBSOCKET_STATUS_PONG_FRAME 

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 payload and payload_len are filled with the binary pong data (if any).

MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT 

MHD_websocket_decode() has decoded a text frame fragment. 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_BINARY_FIRST_FRAGMENT 

MHD_websocket_decode() has decoded a 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_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_NEXT_FRAGMENT 

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_BINARY_NEXT_FRAGMENT 

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_TEXT_LAST_FRAGMENT 

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_BINARY_LAST_FRAGMENT 

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_PROTOCOL_ERROR 

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 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).

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 MHD_upgrade_action() with MHD_UPGRADE_ACTION_CLOSE. 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 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_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 MHD_websocket_stream_init() or MHD_websocket_stream_init2() to avoid this and close the websocket instead.

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.

MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED 

The maximum payload size has been exceeded. 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 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 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_UTF8_ENCODING_ERROR 

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 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_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:

Definition at line 159 of file microhttpd_ws.h.

◆ MHD_WEBSOCKET_UTF8STEP

Enumeration of possible UTF-8 check steps.

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.

Enumerator
MHD_WEBSOCKET_UTF8STEP_NORMAL 

There is no open UTF-8 sequence. The next byte must be 0x00-0x7F or 0xC2-0xF4.

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.

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.

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.

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.

MHD_WEBSOCKET_UTF8STEP_UTF3TAIL_2OF2 

The third byte of a three byte UTF-8 sequence. The next byte must be 0x80-0xBF.

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.

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.

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.

MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_2OF3 

The third byte of a four byte UTF-8 sequence. The next byte must be 0x80-0xBF.

MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_3OF3 

The fourth byte of a four byte UTF-8 sequence. The next byte must be 0x80-0xBF.

Definition at line 446 of file microhttpd_ws.h.

◆ MHD_WEBSOCKET_VALIDITY

Enumeration of validity values.

These values are used for MHD_websocket_stream_is_valid() and specify the validity status.

Enumerator
MHD_WEBSOCKET_VALIDITY_INVALID 

The stream is invalid. It cannot be used for decoding anymore.

MHD_WEBSOCKET_VALIDITY_VALID 

The stream is valid. Decoding works as expected.

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.

Definition at line 520 of file microhttpd_ws.h.

Function Documentation

◆ MHD_websocket_check_connection_header()

_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_check_connection_header ( const char *  connection_header)

Checks the value of the 'Connection' HTTP request header. Websocket requests require the token 'Upgrade' in the 'Connection' HTTP request header.

Parameters
connection_headerThe value of the 'Connection' request header. You can get this request header value by passing MHD_HTTP_HEADER_CONNECTION to MHD_lookup_connection_value().
Returns
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.

Checks whether the "Connection" request header has the 'Upgrade' token.

Definition at line 282 of file mhd_websocket.c.

References MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER, MHD_WEBSOCKET_STATUS_OK, and NULL.

◆ MHD_websocket_check_http_version()

_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_check_http_version ( const char *  http_version)

Checks the HTTP version of the incoming request. Websocket requests are only allowed for HTTP/1.1 or above.

Parameters
http_versionThe value of the 'version' parameter of your access_handler callback
Returns
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.

Checks whether the HTTP version is 1.1 or above.

Definition at line 189 of file mhd_websocket.c.

References MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER, MHD_WEBSOCKET_STATUS_OK, and NULL.

◆ MHD_websocket_check_upgrade_header()

_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_check_upgrade_header ( const char *  upgrade_header)

Checks the value of the 'Upgrade' HTTP request header. Websocket requests require the value 'websocket' in the 'Upgrade' HTTP request header.

Parameters
upgrade_headerThe value of the 'Upgrade' request header. You can get this request header value by passing MHD_HTTP_HEADER_UPGRADE to MHD_lookup_connection_value().
Returns
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.

Checks whether the "Upgrade" request header has the "websocket" keyword.

Definition at line 365 of file mhd_websocket.c.

References MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER, MHD_WEBSOCKET_STATUS_OK, and NULL.

◆ MHD_websocket_check_version_header()

_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_check_version_header ( const char *  version_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.

Parameters
version_headerThe 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().
Returns
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.

Checks whether the "Sec-WebSocket-Version" request header equals to "13"

Definition at line 453 of file mhd_websocket.c.

References MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER, MHD_WEBSOCKET_STATUS_OK, and NULL.

◆ MHD_websocket_create_accept_header()

_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_create_accept_header ( const char *  sec_websocket_key,
char *  sec_websocket_accept 
)

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.

Parameters
sec_websocket_keyThe 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().
[out]sec_websocket_acceptThe response buffer, which will receive the generated 'Sec-WebSocket-Accept' header. This buffer must be at least 29 bytes long and will contain the response value plus a terminating NUL on success.
Returns
A value of enum MHD_WEBSOCKET_STATUS. Typically 0 on success or less than 0 on errors.

Creates the response for the Sec-WebSocket-Accept header

Definition at line 479 of file mhd_websocket.c.

References MHD_SHA1_finish(), MHD_SHA1_init(), MHD_SHA1_update(), MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER, MHD_WEBSOCKET_STATUS_OK, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, and NULL.

Here is the call graph for this function:

◆ MHD_websocket_decode()

_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 
)

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.

Parameters
wsThe websocket stream.
streambufThe byte sequence for decoding. Typically that what you received via recv().
streambuf_lenThe length of the byte sequence streambuf
[out]streambuf_read_lenThe number of bytes which has been processed by this call. This value may be less than streambuf_len when a frame is decoded before the end of the buffer is reached. The remaining bytes of buf must be passed to the next call of this function.
[out]payloadPointer to a variable, which receives a buffer with the decoded payload data. If no decoded data is available this is NULL. When the returned value is not NULL then the buffer contains always payload_len bytes plus one terminating NUL character. The caller must free this buffer using MHD_websocket_free(). If you passed the flag MHD_WEBSOCKET_FLAG_GENERATE_CLOSE_FRAMES_ON_ERROR upon creation of this 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 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.
[out]payload_lenThe length of the result payload buffer in bytes.
Returns
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.

Decodes incoming data to a websocket frame

Definition at line 666 of file mhd_websocket.c.

References MHD_htonll(), MHD_htons(), MHD_websocket_check_utf8(), MHD_WEBSOCKET_CLOSEREASON_MALFORMED_UTF8, MHD_WEBSOCKET_CLOSEREASON_MAXIMUM_ALLOWED_PAYLOAD_SIZE_EXCEEDED, MHD_WEBSOCKET_CLOSEREASON_PROTOCOL_ERROR, MHD_websocket_copy_payload(), MHD_websocket_decode_header_complete(), MHD_websocket_decode_payload_complete(), MHD_WebSocket_DecodeStep_BrokenStream, MHD_WebSocket_DecodeStep_HeaderCompleted, MHD_WebSocket_DecodeStep_Length1of2, MHD_WebSocket_DecodeStep_Length1of8, MHD_WebSocket_DecodeStep_Length1ofX, MHD_WebSocket_DecodeStep_Length2of2, MHD_WebSocket_DecodeStep_Length2of8, MHD_WebSocket_DecodeStep_Length3of8, MHD_WebSocket_DecodeStep_Length4of8, MHD_WebSocket_DecodeStep_Length5of8, MHD_WebSocket_DecodeStep_Length6of8, MHD_WebSocket_DecodeStep_Length7of8, MHD_WebSocket_DecodeStep_Length8of8, MHD_WebSocket_DecodeStep_Mask1Of4, MHD_WebSocket_DecodeStep_Mask2Of4, MHD_WebSocket_DecodeStep_Mask3Of4, MHD_WebSocket_DecodeStep_Mask4Of4, MHD_WebSocket_DecodeStep_PayloadOfControlFrame, MHD_WebSocket_DecodeStep_PayloadOfDataFrame, MHD_WebSocket_DecodeStep_Start, MHD_websocket_encode_close(), MHD_WEBSOCKET_FLAG_CLIENT, MHD_WEBSOCKET_FLAG_GENERATE_CLOSE_FRAMES_ON_ERROR, MHD_WEBSOCKET_FLAG_SERVER, MHD_WebSocket_Opcode_Binary, MHD_WebSocket_Opcode_Close, MHD_WebSocket_Opcode_Continuation, MHD_WebSocket_Opcode_Ping, MHD_WebSocket_Opcode_Pong, MHD_WebSocket_Opcode_Text, MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED, MHD_WEBSOCKET_STATUS_OK, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, MHD_WEBSOCKET_STATUS_PROTOCOL_ERROR, MHD_WEBSOCKET_STATUS_STREAM_BROKEN, MHD_WEBSOCKET_STATUS_UTF8_ENCODING_ERROR, MHD_WebSocket_UTF8Result_Invalid, MHD_WEBSOCKET_VALIDITY_INVALID, MHD_WEBSOCKET_VALIDITY_ONLY_VALID_FOR_CONTROL_FRAMES, NULL, and SIZE_MAX.

Here is the call graph for this function:

◆ MHD_websocket_encode_binary()

_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 
)

Encodes binary data into websocket binary frame.

Parameters
wsThe websocket stream.
payloadThe binary data to send.
payload_lenThe length of the binary data in bytes.
fragmentationA value of enum MHD_WEBSOCKET_FRAGMENTATION to specify the fragmentation behavior. Specify MHD_WEBSOCKET_FRAGMENTATION_NONE if you don't want to use fragmentation.
[out]frameThis variable receives a buffer with the encoded binary frame. This is what you typically send via send() to the recipient. If no encoded frame is available this is NULL. When this variable is not NULL then the allocated buffer contains always frame_len bytes plus one terminating NUL character. The caller must free this buffer using MHD_websocket_free().
[out]frame_lenThe length of the result frame buffer in bytes.
Returns
A value of enum MHD_WEBSOCKET_STATUS. This is MHD_WEBSOCKET_STATUS_OK (= 0) on success or a value less than 0 on errors.

Encodes binary data into a websocket binary frame

Definition at line 1696 of file mhd_websocket.c.

References MHD_websocket_encode_data(), MHD_WEBSOCKET_FRAGMENTATION_LAST, MHD_WEBSOCKET_FRAGMENTATION_NONE, MHD_WebSocket_Opcode_Binary, MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, and NULL.

Here is the call graph for this function:

◆ MHD_websocket_encode_close()

_MHD_EXTERN 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 
)

Encodes a websocket close frame

Parameters
wsThe websocket stream.
reason_codeThe reason for close. You can use 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 MHD_WEBSOCKET_CLOSEREASON_NO_REASON then no reason is encoded.
reason_utf8An UTF-8 encoded text reason why the connection is closed. This may be NULL if reason_utf8_len is 0. This must be NULL if reason_code is MHD_WEBSOCKET_CLOSEREASON_NO_REASON (= 0).
reason_utf8_lenThe length of the UTF-8 encoded text reason in bytes. This may not exceed 123 bytes.
[out]frameThis variable receives a buffer with the encoded close frame. This is what you typically send via send() to the recipient. If no encoded frame is available this is NULL. When this variable is not NULL then the buffer contains always frame_len bytes plus one terminating NUL character. The caller must free this buffer using MHD_websocket_free().
[out]frame_lenThe length of the result frame buffer in bytes.
Returns
A value of enum MHD_WEBSOCKET_STATUS. This is MHD_WEBSOCKET_STATUS_OK (= 0) on success or a value less than 0 on errors.

Encodes a websocket close frame

Definition at line 1938 of file mhd_websocket.c.

References MHD_htons(), MHD_websocket_check_utf8(), MHD_WEBSOCKET_CLOSEREASON_NO_REASON, MHD_websocket_copy_payload(), MHD_websocket_encode_is_masked(), MHD_websocket_encode_overhead_size(), MHD_websocket_generate_mask(), MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED, MHD_WEBSOCKET_STATUS_MEMORY_ERROR, MHD_WEBSOCKET_STATUS_OK, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, MHD_WEBSOCKET_STATUS_UTF8_ENCODING_ERROR, MHD_WebSocket_UTF8Result_Valid, and NULL.

Referenced by MHD_websocket_decode(), and MHD_websocket_decode_header_complete().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ MHD_websocket_encode_ping()

_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 
)

Encodes a websocket ping frame

Parameters
wsThe websocket stream.
payloadThe binary ping payload data to send. This may be NULL if payload_len is 0.
payload_lenThe length of the payload data in bytes. This may not exceed 125 bytes.
[out]frameThis variable receives a buffer with the encoded ping frame data. This is what you typically send via send() to the recipient. If no encoded frame is available this is NULL. When this variable is not NULL then the buffer contains always frame_len bytes plus one terminating NUL character. The caller must free this buffer using MHD_websocket_free().
[out]frame_lenThe length of the result frame buffer in bytes.
Returns
A value of enum MHD_WEBSOCKET_STATUS. This is MHD_WEBSOCKET_STATUS_OK (= 0) on success or a value less than 0 on errors.

Encodes a websocket ping frame

Definition at line 1825 of file mhd_websocket.c.

References MHD_websocket_encode_ping_pong(), and MHD_WebSocket_Opcode_Ping.

Here is the call graph for this function:

◆ MHD_websocket_encode_pong()

_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 pong frame

Parameters
wsThe websocket stream.
payloadThe binary pong payload data, which should be the decoded payload from the received ping frame. This may be NULL if payload_len is 0.
payload_lenThe length of the payload data in bytes. This may not exceed 125 bytes.
[out]frameThis variable receives a buffer with the encoded pong frame data. This is what you typically send via send() to the recipient. If no encoded frame is available this is NULL. When this variable is not NULL then the buffer contains always frame_len bytes plus one terminating NUL character. The caller must free this buffer using MHD_websocket_free().
[out]frame_lenThe length of the result frame buffer in bytes.
Returns
A value of enum MHD_WEBSOCKET_STATUS. This is MHD_WEBSOCKET_STATUS_OK (= 0) on success or a value less than 0 on errors.

Encodes a websocket pong frame

Definition at line 1845 of file mhd_websocket.c.

References MHD_websocket_encode_ping_pong(), and MHD_WebSocket_Opcode_Pong.

Here is the call graph for this function:

◆ MHD_websocket_encode_text()

_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 
)

Encodes an UTF-8 encoded text into websocket text frame.

Parameters
wsThe websocket stream.
payload_utf8The UTF-8 encoded text to send. This may be NULL if payload_utf8_len is 0.
payload_utf8_lenThe length of the UTF-8 encoded text in bytes.
fragmentationA value of enum MHD_WEBSOCKET_FRAGMENTATION to specify the fragmentation behavior. Specify MHD_WEBSOCKET_FRAGMENTATION_NONE if you don't want to use fragmentation.
[out]frameThis variable receives a buffer with the encoded frame. This is what you typically send via send() to the recipient. If no encoded data is available this is NULL. When this variable is not NULL then the buffer contains always frame_len bytes plus one terminating NUL character. The caller must free this buffer using MHD_websocket_free().
[out]frame_lenThe length of the encoded frame in bytes.
[out]utf8_stepThis parameter is required for fragmentation and 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. 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 of this variable will be initialized to MHD_WEBSOCKET_UTF8STEP_NORMAL.
Returns
A value of enum MHD_WEBSOCKET_STATUS. This is MHD_WEBSOCKET_STATUS_OK (= 0) on success or a value less than 0 on errors.

Encodes a text into a websocket text frame

Definition at line 1629 of file mhd_websocket.c.

References MHD_websocket_check_utf8(), MHD_websocket_encode_data(), MHD_WEBSOCKET_FRAGMENTATION_FIRST, MHD_WEBSOCKET_FRAGMENTATION_LAST, MHD_WEBSOCKET_FRAGMENTATION_NONE, MHD_WebSocket_Opcode_Text, MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, MHD_WEBSOCKET_STATUS_UTF8_ENCODING_ERROR, MHD_WebSocket_UTF8Result_Incomplete, MHD_WebSocket_UTF8Result_Invalid, MHD_WEBSOCKET_UTF8STEP_NORMAL, and NULL.

Here is the call graph for this function:

◆ MHD_websocket_free()

_MHD_EXTERN int MHD_websocket_free ( struct MHD_WebSocketStream *  ws,
void *  buf 
)

Frees memory with the associated 'free' function of the websocket stream

Parameters
wsThe websocket stream.
bufThe previously allocated memory or NULL
Returns
A value of enum MHD_WEBSOCKET_STATUS. This is MHD_WEBSOCKET_STATUS_OK (= 0) on success or a value less than 0 on errors.

Calls the free function associated with the websocket steam

Definition at line 2378 of file mhd_websocket.c.

References MHD_WEBSOCKET_STATUS_OK, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, and NULL.

◆ MHD_websocket_malloc()

_MHD_EXTERN void * MHD_websocket_malloc ( struct MHD_WebSocketStream *  ws,
size_t  buf_len 
)

Allocates memory with the associated 'malloc' function of the websocket stream

Parameters
wsThe websocket stream.
buf_lenThe length of the memory to allocate in bytes
Returns
The allocated memory on success or NULL on failure.

Calls the malloc function associated with the websocket steam

Definition at line 2345 of file mhd_websocket.c.

References NULL.

◆ MHD_websocket_realloc()

_MHD_EXTERN void * MHD_websocket_realloc ( struct MHD_WebSocketStream *  ws,
void *  buf,
size_t  new_buf_len 
)

Reallocates memory with the associated 'realloc' function of the websocket stream

Parameters
wsThe websocket stream.
bufThe previously allocated memory or NULL
new_buf_lenThe new length of the memory in bytes
Returns
The allocated memory on success or NULL on failure. If NULL is returned the previously allocated buffer remains valid.

Calls the realloc function associated with the websocket steam

Definition at line 2361 of file mhd_websocket.c.

References NULL.

◆ MHD_websocket_split_close_reason()

_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 
)

Splits the payload of a decoded close frame.

Parameters
payloadThe payload of the close frame. This parameter may only be NULL if payload_len is 0.
payload_lenThe length of payload.
[out]reason_codeThe 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 may be NULL.
[out]reason_utf8The literal close reason. If there was no literal close reason, this is 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 payload.
[out]reason_utf8_lenThe length of the literal close reason. If there was no literal close reason, this is 0. This parameter is optional and may be NULL.
Returns
A value of enum MHD_WEBSOCKET_STATUS. This is MHD_WEBSOCKET_STATUS_OK (= 0) on success or a value less than 0 on errors.

Splits the received close reason

Definition at line 1571 of file mhd_websocket.c.

References MHD_htons(), MHD_WEBSOCKET_CLOSEREASON_NO_REASON, MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED, MHD_WEBSOCKET_STATUS_OK, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, MHD_WEBSOCKET_STATUS_PROTOCOL_ERROR, and NULL.

Here is the call graph for this function:

◆ MHD_websocket_stream_free()

_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_stream_free ( struct MHD_WebSocketStream *  ws)

Frees a websocket stream

Parameters
wsThe websocket stream. This value may be NULL.
Returns
A value of enum MHD_WEBSOCKET_STATUS. Typically 0 on success or less than 0 on errors.

Frees a previously allocated websocket stream

Definition at line 612 of file mhd_websocket.c.

References MHD_WEBSOCKET_STATUS_OK, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, and NULL.

◆ MHD_websocket_stream_init()

_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_stream_init ( struct MHD_WebSocketStream **  ws,
int  flags,
size_t  max_payload_size 
)

Creates a new websocket stream, used for decoding/encoding.

Parameters
[out]wsThe websocket stream
flagsCombination of enum MHD_WEBSOCKET_FLAG values to modify the behavior of the websocket stream.
max_payload_sizeThe maximum size for incoming payload data in bytes. Use 0 to allow each size.
Returns
A value of enum MHD_WEBSOCKET_STATUS. Typically 0 on success or less than 0 on errors.

Initializes a new websocket stream

Definition at line 538 of file mhd_websocket.c.

References MHD_websocket_stream_init2(), and NULL.

Here is the call graph for this function:

◆ MHD_websocket_stream_init2()

_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,
void *  cls_rng,
MHD_WebSocketRandomNumberGenerator  callback_rng 
)

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.

Parameters
[out]wsThe websocket stream
flagsCombination of enum MHD_WEBSOCKET_FLAG values to modify the behavior of the websocket stream.
max_payload_sizeThe maximum size for incoming payload data in bytes. Use 0 to allow each size.
callback_mallocThe callback function for malloc().
callback_reallocThe callback function for realloc().
callback_freeThe callback function for free().
cls_rngA 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.
callback_rngA 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.
Returns
A value of enum MHD_WEBSOCKET_STATUS. Typically 0 on success or less than 0 on errors.

Initializes a new websocket stream with additional parameters for allocation functions

Definition at line 558 of file mhd_websocket.c.

References MHD_WEBSOCKET_FLAG_CLIENT, MHD_WEBSOCKET_FLAG_MASK_ALL, MHD_WEBSOCKET_STATUS_MEMORY_ERROR, MHD_WEBSOCKET_STATUS_OK, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, MHD_WEBSOCKET_VALIDITY_VALID, and NULL.

Referenced by MHD_websocket_stream_init().

Here is the caller graph for this function:

◆ MHD_websocket_stream_invalidate()

_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_stream_invalidate ( struct MHD_WebSocketStream *  ws)

Invalidates a websocket stream. After invalidation a websocket stream cannot be used for decoding anymore. Encoding is still possible.

Parameters
wsThe websocket stream.
Returns
A value of enum MHD_WEBSOCKET_STATUS. Typically 0 on success or less than 0 on errors.

Invalidates a websocket stream (no more decoding possible)

Definition at line 635 of file mhd_websocket.c.

References MHD_WEBSOCKET_STATUS_OK, MHD_WEBSOCKET_STATUS_PARAMETER_ERROR, MHD_WEBSOCKET_VALIDITY_INVALID, and NULL.

◆ MHD_websocket_stream_is_valid()

_MHD_EXTERN enum MHD_WEBSOCKET_VALIDITY MHD_websocket_stream_is_valid ( struct MHD_WebSocketStream *  ws)

Queries whether a websocket stream is valid. Invalidated websocket streams cannot be used for decoding anymore. Encoding is still possible.

Parameters
wsThe websocket stream.
Returns
A value of enum MHD_WEBSOCKET_VALIDITY.

Returns whether a websocket stream is valid

Definition at line 652 of file mhd_websocket.c.

References MHD_WEBSOCKET_VALIDITY_INVALID, and NULL.