microhttpd_ws.h

Go to the documentation of this file.

/*
     This file is part of libmicrohttpd
     Copyright (C) 2021 Christian Grothoff (and other contributing authors)

     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
     License as published by the Free Software Foundation; either
     version 2.1 of the License, or (at your option) any later version.

     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Lesser General Public License for more details.

     You should have received a copy of the GNU Lesser General Public
     License along with this library; if not, write to the Free Software
     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
*/
/*
 *                            *** WARNING! ***
 * *   The websockets interface is currently in "experimental" stage.   *
 * * It does not work on architectures with endianness different from  *
 * * big endian and little endian and may have some portability issues.*
 * * API and ABI are not yet stable.                                   *
 */
#ifndef MHD_MICROHTTPD_WS_H
#define MHD_MICROHTTPD_WS_H


#ifdef __cplusplus
extern "C"
{
#if 0                           /* keep Emacsens' auto-indent happy */
}
#endif
#endif


struct MHD_WebSocketStream;

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
};

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 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 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
};

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
};

enum MHD_WEBSOCKET_VALIDITY
{
  MHD_WEBSOCKET_VALIDITY_INVALID = 0,
  MHD_WEBSOCKET_VALIDITY_VALID   = 1,
  MHD_WEBSOCKET_VALIDITY_ONLY_VALID_FOR_CONTROL_FRAMES = 2
};
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);

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

#if 0                           /* keep Emacsens' auto-indent happy */
{
#endif
#ifdef __cplusplus
}
#endif

#endif