GNU libmicrohttpd 0.9.77
|
interface for experimental web socket extension to libmicrohttpd More...
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) |
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) |
interface for experimental web socket extension to libmicrohttpd
Definition in file microhttpd_ws.h.
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().
buf | buffer |
Definition at line 591 of file microhttpd_ws.h.
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().
buf_len | buffer size in bytes |
Definition at line 557 of file microhttpd_ws.h.
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().
cls | closure specified in MHD_websocket_stream_init2() |
buf | buffer to fill with random values |
buf_len | size of buffer in bytes |
Definition at line 609 of file microhttpd_ws.h.
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().
buf | buffer |
new_buf_len | new buffer size in bytes |
Definition at line 575 of file microhttpd_ws.h.
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.
enum 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 |
Definition at line 58 of file microhttpd_ws.h.
Enum to specify the fragmenting behavior while encoding with MHD_websocket_encode_text() or MHD_websocket_encode_binary().
Definition at line 120 of file microhttpd_ws.h.
enum 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 |
MHD_WEBSOCKET_STATUS_BINARY_FRAME | MHD_websocket_decode() has decoded a binary frame. The parameters |
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 |
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 |
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 |
MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT | MHD_websocket_decode() has decoded a text frame fragment. The parameters |
MHD_WEBSOCKET_STATUS_BINARY_FIRST_FRAGMENT | MHD_websocket_decode() has decoded a binary frame fragment. The parameters |
MHD_WEBSOCKET_STATUS_TEXT_NEXT_FRAGMENT | MHD_websocket_decode() has decoded the next text frame fragment. The parameters |
MHD_WEBSOCKET_STATUS_BINARY_NEXT_FRAGMENT | MHD_websocket_decode() has decoded the next binary frame fragment. The parameters |
MHD_WEBSOCKET_STATUS_TEXT_LAST_FRAGMENT | MHD_websocket_decode() has decoded the last text frame fragment. The parameters |
MHD_WEBSOCKET_STATUS_BINARY_LAST_FRAGMENT | MHD_websocket_decode() has decoded the last binary frame fragment. The parameters |
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.
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.
Definition at line 446 of file microhttpd_ws.h.
Enumeration of validity values.
These values are used for MHD_websocket_stream_is_valid() and specify the validity status.
Definition at line 520 of file microhttpd_ws.h.
_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.
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(). |
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_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.
http_version | The value of the 'version' parameter of your access_handler callback |
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_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.
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(). |
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_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.
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(). |
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_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.
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(). | |
[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 the response value plus a terminating NUL on success. |
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.
_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.
ws | The websocket stream. | |
streambuf | The byte sequence for decoding. Typically that what you received via recv() . | |
streambuf_len | The length of the byte sequence streambuf | |
[out] | streambuf_read_len | The 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] | payload | Pointer 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_len | The length of the result payload buffer in bytes. |
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.
_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.
ws | The websocket stream. | |
payload | The binary data to send. | |
payload_len | The length of the binary data in bytes. | |
fragmentation | A 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] | frame | This 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_len | The length of the result frame buffer in bytes. |
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.
_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
ws | The websocket stream. | |
reason_code | The 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_utf8 | An 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_len | The length of the UTF-8 encoded text reason in bytes. This may not exceed 123 bytes. | |
[out] | frame | This 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_len | The length of the result frame buffer in bytes. |
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().
_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
ws | The websocket stream. | |
payload | The binary ping payload data to send. This may be NULL if payload_len is 0. | |
payload_len | The length of the payload data in bytes. This may not exceed 125 bytes. | |
[out] | frame | This 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_len | The length of the result frame buffer in bytes. |
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.
_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
ws | The websocket stream. | |
payload | The 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_len | The length of the payload data in bytes. This may not exceed 125 bytes. | |
[out] | frame | This 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_len | The length of the result frame buffer in bytes. |
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.
_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.
ws | The websocket stream. | |
payload_utf8 | The UTF-8 encoded text to send. This may be NULL if payload_utf8_len is 0. | |
payload_utf8_len | The length of the UTF-8 encoded text in bytes. | |
fragmentation | A 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] | frame | This 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_len | The length of the encoded frame in bytes. |
[out] | utf8_step | This 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. |
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.
_MHD_EXTERN int MHD_websocket_free | ( | struct MHD_WebSocketStream * | ws, |
void * | buf | ||
) |
Frees memory with the associated 'free' function of the websocket stream
ws | The websocket stream. |
buf | The previously allocated memory or NULL |
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_EXTERN void * MHD_websocket_malloc | ( | struct MHD_WebSocketStream * | ws, |
size_t | buf_len | ||
) |
Allocates memory with the associated 'malloc' function of the websocket stream
ws | The websocket stream. |
buf_len | The length of the memory to allocate in bytes |
Calls the malloc function associated with the websocket steam
Definition at line 2345 of file mhd_websocket.c.
References NULL.
_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
ws | The websocket stream. |
buf | The previously allocated memory or NULL |
new_buf_len | The new length of the memory in bytes |
Calls the realloc function associated with the websocket steam
Definition at line 2361 of file mhd_websocket.c.
References NULL.
_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.
payload | The payload of the close frame. This parameter may only be NULL if payload_len is 0. | |
payload_len | The length of payload. | |
[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 may be NULL. |
[out] | reason_utf8 | The 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_len | The length of the literal close reason. If there was no literal close reason, this is 0. This parameter is optional and may be NULL. |
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.
_MHD_EXTERN enum MHD_WEBSOCKET_STATUS MHD_websocket_stream_free | ( | struct MHD_WebSocketStream * | ws | ) |
Frees a websocket stream
ws | The websocket stream. This value may be NULL. |
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_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.
[out] | ws | The websocket stream |
flags | Combination of enum MHD_WEBSOCKET_FLAG values to modify the behavior of the websocket stream. | |
max_payload_size | The maximum size for incoming payload data in bytes. Use 0 to allow each size. |
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.
_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.
[out] | ws | The websocket stream |
flags | Combination of enum MHD_WEBSOCKET_FLAG values to modify the behavior of the websocket stream. | |
max_payload_size | The maximum size for incoming payload data in bytes. Use 0 to allow each size. | |
callback_malloc | The callback function for malloc() . | |
callback_realloc | The callback function for realloc() . | |
callback_free | The callback function for free() . | |
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. | |
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. |
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().
_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.
ws | The websocket stream. |
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_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.
ws | The websocket stream. |
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.