lib/libwebsockets.h

   1 /*
   2  * libwebsockets - small server side websockets and web server implementation
   3  *
   4  * Copyright (C) 2010 Andy Green <andy@warmcat.com>
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Lesser General Public
   8  *  License as published by the Free Software Foundation:
   9  *  version 2.1 of the License.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Lesser General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Lesser General Public
  17  *  License along with this library; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  19  *  MA  02110-1301  USA
  20  */
  21
  22 #ifndef __LIBWEBSOCKET_H__
  23 #define __LIBWEBSOCKET_H__
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #include <cstddef>
  28 #endif
  29
  30 #ifdef WIN32
  31
  32 #ifndef WIN32_LEAN_AND_MEAN
  33 #define WIN32_LEAN_AND_MEAN
  34 #endif
  35 #include <winsock2.h>
  36 #include <ws2tcpip.h>
  37 #include <stddef.h>
  38 #include "../win32port/win32helpers/websock-w32.h"
  39
  40 #include "../win32port/win32helpers/gettimeofday.h"
  41
  42 #define strcasecmp stricmp
  43
  44 typedef int ssize_t;
  45
  46 #ifdef LWS_DLL
  47 #ifdef LWS_INTERNAL
  48 #define LWS_EXTERN extern __declspec(dllexport)
  49 #else
  50 #define LWS_EXTERN extern __declspec(dllimport)
  51 #endif
  52 #endif
  53
  54 #else
  55 #include <poll.h>
  56 #endif
  57
  58 #ifndef LWS_EXTERN
  59 #define LWS_EXTERN extern
  60 #endif
  61
  62 #define CONTEXT_PORT_NO_LISTEN 0
  63 #define MAX_MUX_RECURSION 2
  64
  65 enum libwebsocket_context_options {
  66         LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK = 1,
  67         LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT = 2,
  68         LWS_SERVER_OPTION_SKIP_SERVER_CANONICAL_NAME = 4,
  69 };
  70
  71 enum libwebsocket_callback_reasons {
  72         LWS_CALLBACK_ESTABLISHED,
  73         LWS_CALLBACK_CLIENT_CONNECTION_ERROR,
  74         LWS_CALLBACK_CLIENT_ESTABLISHED,
  75         LWS_CALLBACK_CLOSED,
  76         LWS_CALLBACK_RECEIVE,
  77         LWS_CALLBACK_CLIENT_RECEIVE,
  78         LWS_CALLBACK_CLIENT_RECEIVE_PONG,
  79         LWS_CALLBACK_CLIENT_WRITEABLE,
  80         LWS_CALLBACK_SERVER_WRITEABLE,
  81         LWS_CALLBACK_HTTP,
  82         LWS_CALLBACK_BROADCAST,
  83         LWS_CALLBACK_FILTER_NETWORK_CONNECTION,
  84         LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION,
  85         LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS,
  86         LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS,
  87         LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION,
  88         LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER,
  89         LWS_CALLBACK_CONFIRM_EXTENSION_OKAY,
  90         LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED,
  91         /* external poll() management support */
  92         LWS_CALLBACK_ADD_POLL_FD,
  93         LWS_CALLBACK_DEL_POLL_FD,
  94         LWS_CALLBACK_SET_MODE_POLL_FD,
  95         LWS_CALLBACK_CLEAR_MODE_POLL_FD,
  96 };
  97
  98 enum libwebsocket_extension_callback_reasons {
  99         LWS_EXT_CALLBACK_SERVER_CONTEXT_CONSTRUCT,
 100         LWS_EXT_CALLBACK_CLIENT_CONTEXT_CONSTRUCT,
 101         LWS_EXT_CALLBACK_SERVER_CONTEXT_DESTRUCT,
 102         LWS_EXT_CALLBACK_CLIENT_CONTEXT_DESTRUCT,
 103         LWS_EXT_CALLBACK_CONSTRUCT,
 104         LWS_EXT_CALLBACK_CLIENT_CONSTRUCT,
 105         LWS_EXT_CALLBACK_CHECK_OK_TO_REALLY_CLOSE,
 106         LWS_EXT_CALLBACK_CHECK_OK_TO_PROPOSE_EXTENSION,
 107         LWS_EXT_CALLBACK_DESTROY,
 108         LWS_EXT_CALLBACK_DESTROY_ANY_WSI_CLOSING,
 109         LWS_EXT_CALLBACK_ANY_WSI_ESTABLISHED,
 110         LWS_EXT_CALLBACK_PACKET_RX_PREPARSE,
 111         LWS_EXT_CALLBACK_PACKET_TX_PRESEND,
 112         LWS_EXT_CALLBACK_PACKET_TX_DO_SEND,
 113         LWS_EXT_CALLBACK_HANDSHAKE_REPLY_TX,
 114         LWS_EXT_CALLBACK_FLUSH_PENDING_TX,
 115         LWS_EXT_CALLBACK_EXTENDED_PAYLOAD_RX,
 116         LWS_EXT_CALLBACK_CAN_PROXY_CLIENT_CONNECTION,
 117         LWS_EXT_CALLBACK_1HZ,
 118         LWS_EXT_CALLBACK_REQUEST_ON_WRITEABLE,
 119         LWS_EXT_CALLBACK_IS_WRITEABLE,
 120         LWS_EXT_CALLBACK_PAYLOAD_TX,
 121         LWS_EXT_CALLBACK_PAYLOAD_RX,
 122 };
 123
 124 enum libwebsocket_write_protocol {
 125         LWS_WRITE_TEXT,
 126         LWS_WRITE_BINARY,
 127         LWS_WRITE_CONTINUATION,
 128         LWS_WRITE_HTTP,
 129
 130         /* special 04+ opcodes */
 131
 132         LWS_WRITE_CLOSE,
 133         LWS_WRITE_PING,
 134         LWS_WRITE_PONG,
 135
 136         /* flags */
 137
 138         LWS_WRITE_NO_FIN = 0x40,
 139         /*
 140          * client packet payload goes out on wire unmunged
 141          * only useful for security tests since normal servers cannot
 142          * decode the content if used
 143          */
 144         LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
 145 };
 146
 147 /*
 148  * you need these to look at headers that have been parsed if using the
 149  * LWS_CALLBACK_FILTER_CONNECTION callback.  If a header from the enum
 150  * list below is absent, .token = NULL and token_len = 0.  Otherwise .token
 151  * points to .token_len chars containing that header content.
 152  */
 153
 154 struct lws_tokens {
 155         char *token;
 156         int token_len;
 157 };
 158
 159 enum lws_token_indexes {
 160         WSI_TOKEN_GET_URI,
 161         WSI_TOKEN_HOST,
 162         WSI_TOKEN_CONNECTION,
 163         WSI_TOKEN_KEY1,
 164         WSI_TOKEN_KEY2,
 165         WSI_TOKEN_PROTOCOL,
 166         WSI_TOKEN_UPGRADE,
 167         WSI_TOKEN_ORIGIN,
 168         WSI_TOKEN_DRAFT,
 169         WSI_TOKEN_CHALLENGE,
 170
 171         /* new for 04 */
 172         WSI_TOKEN_KEY,
 173         WSI_TOKEN_VERSION,
 174         WSI_TOKEN_SWORIGIN,
 175
 176         /* new for 05 */
 177         WSI_TOKEN_EXTENSIONS,
 178
 179         /* client receives these */
 180         WSI_TOKEN_ACCEPT,
 181         WSI_TOKEN_NONCE,
 182         WSI_TOKEN_HTTP,
 183         WSI_TOKEN_MUXURL,
 184
 185         /* always last real token index*/
 186         WSI_TOKEN_COUNT,
 187         /* parser state additions */
 188         WSI_TOKEN_NAME_PART,
 189         WSI_TOKEN_SKIPPING,
 190         WSI_TOKEN_SKIPPING_SAW_CR,
 191         WSI_PARSING_COMPLETE,
 192         WSI_INIT_TOKEN_MUXURL,
 193 };
 194
 195 /*
 196  * From RFC 6455
 197    1000
 198
 199       1000 indicates a normal closure, meaning that the purpose for
 200       which the connection was established has been fulfilled.
 201
 202    1001
 203
 204       1001 indicates that an endpoint is "going away", such as a server
 205       going down or a browser having navigated away from a page.
 206
 207    1002
 208
 209       1002 indicates that an endpoint is terminating the connection due
 210       to a protocol error.
 211
 212    1003
 213
 214       1003 indicates that an endpoint is terminating the connection
 215       because it has received a type of data it cannot accept (e.g., an
 216       endpoint that understands only text data MAY send this if it
 217       receives a binary message).
 218
 219    1004
 220
 221       Reserved.  The specific meaning might be defined in the future.
 222
 223    1005
 224
 225       1005 is a reserved value and MUST NOT be set as a status code in a
 226       Close control frame by an endpoint.  It is designated for use in
 227       applications expecting a status code to indicate that no status
 228       code was actually present.
 229
 230    1006
 231
 232       1006 is a reserved value and MUST NOT be set as a status code in a
 233       Close control frame by an endpoint.  It is designated for use in
 234       applications expecting a status code to indicate that the
 235       connection was closed abnormally, e.g., without sending or
 236       receiving a Close control frame.
 237
 238    1007
 239
 240       1007 indicates that an endpoint is terminating the connection
 241       because it has received data within a message that was not
 242       consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
 243       data within a text message).
 244
 245    1008
 246
 247       1008 indicates that an endpoint is terminating the connection
 248       because it has received a message that violates its policy.  This
 249       is a generic status code that can be returned when there is no
 250       other more suitable status code (e.g., 1003 or 1009) or if there
 251       is a need to hide specific details about the policy.
 252
 253    1009
 254
 255       1009 indicates that an endpoint is terminating the connection
 256       because it has received a message that is too big for it to
 257       process.
 258
 259    1010
 260
 261       1010 indicates that an endpoint (client) is terminating the
 262       connection because it has expected the server to negotiate one or
 263       more extension, but the server didn't return them in the response
 264       message of the WebSocket handshake.  The list of extensions that
 265       are needed SHOULD appear in the /reason/ part of the Close frame.
 266       Note that this status code is not used by the server, because it
 267       can fail the WebSocket handshake instead.
 268
 269    1011
 270
 271       1011 indicates that a server is terminating the connection because
 272       it encountered an unexpected condition that prevented it from
 273       fulfilling the request.
 274
 275    1015
 276
 277       1015 is a reserved value and MUST NOT be set as a status code in a
 278       Close control frame by an endpoint.  It is designated for use in
 279       applications expecting a status code to indicate that the
 280       connection was closed due to a failure to perform a TLS handshake
 281       (e.g., the server certificate can't be verified).
 282 */
 283
 284 enum lws_close_status {
 285         LWS_CLOSE_STATUS_NOSTATUS = 0,
 286         LWS_CLOSE_STATUS_NORMAL = 1000,
 287         LWS_CLOSE_STATUS_GOINGAWAY = 1001,
 288         LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002,
 289         LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003,
 290         LWS_CLOSE_STATUS_RESERVED = 1004,
 291         LWS_CLOSE_STATUS_NO_STATUS = 1005,
 292         LWS_CLOSE_STATUS_ABNORMAL_CLOSE = 1006,
 293         LWS_CLOSE_STATUS_INVALID_PAYLOAD = 1007,
 294         LWS_CLOSE_STATUS_POLICY_VIOLATION = 1008,
 295         LWS_CLOSE_STATUS_MESSAGE_TOO_LARGE = 1009,
 296         LWS_CLOSE_STATUS_EXTENSION_REQUIRED = 1010,
 297     LWS_CLOSE_STATUS_UNEXPECTED_CONDITION = 1011,
 298     LWS_CLOSE_STATUS_TLS_FAILURE = 1015,
 299 };
 300
 301 struct libwebsocket;
 302 struct libwebsocket_context;
 303 struct libwebsocket_extension;
 304
 305 /**
 306  * callback_function() - User server actions
 307  * @context:    Websockets context
 308  * @wsi:        Opaque websocket instance pointer
 309  * @reason:     The reason for the call
 310  * @user:       Pointer to per-session user data allocated by library
 311  * @in:         Pointer used for some callback reasons
 312  * @len:        Length set for some callback reasons
 313  *
 314  *      This callback is the way the user controls what is served.  All the
 315  *      protocol detail is hidden and handled by the library.
 316  *
 317  *      For each connection / session there is user data allocated that is
 318  *      pointed to by "user".  You set the size of this user data area when
 319  *      the library is initialized with libwebsocket_create_server.
 320  *
 321  *      You get an opportunity to initialize user data when called back with
 322  *      LWS_CALLBACK_ESTABLISHED reason.
 323  *
 324  *      LWS_CALLBACK_ESTABLISHED:  after the server completes a handshake with
 325  *                              an incoming client
 326  *
 327  *  LWS_CALLBACK_CLIENT_CONNECTION_ERROR: the request client connection has
 328  *        been unable to complete a handshake with the remote server
 329  *
 330  *  LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed
 331  *                              a handshake with the remote server
 332  *
 333  *      LWS_CALLBACK_CLOSED: when the websocket session ends
 334  *
 335  *      LWS_CALLBACK_BROADCAST: signal to send to client (you would use
 336  *                              libwebsocket_write() taking care about the
 337  *                              special buffer requirements
 338  *
 339  *      LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a
 340  *                              remote client, it can be found at *in and is
 341  *                              len bytes long
 342  *
 343  *      LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,
 344  *                              they appear with this callback reason.  PONG
 345  *                              packets only exist in 04+ protocol
 346  *
 347  *      LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the
 348  *                              client connection, it can be found at *in and
 349  *                              is len bytes long
 350  *
 351  *      LWS_CALLBACK_HTTP: an http request has come from a client that is not
 352  *                              asking to upgrade the connection to a websocket
 353  *                              one.  This is a chance to serve http content,
 354  *                              for example, to send a script to the client
 355  *                              which will then open the websockets connection.
 356  *                              @in points to the URI path requested and
 357  *                              libwebsockets_serve_http_file() makes it very
 358  *                              simple to send back a file to the client.
 359  *
 360  *      LWS_CALLBACK_CLIENT_WRITEABLE:
 361  *      LWS_CALLBACK_SERVER_WRITEABLE:   If you call
 362  *              libwebsocket_callback_on_writable() on a connection, you will
 363  *              get one of these callbacks coming when the connection socket
 364  *              is able to accept another write packet without blocking.
 365  *              If it already was able to take another packet without blocking,
 366  *              you'll get this callback at the next call to the service loop
 367  *              function.  Notice that CLIENTs get LWS_CALLBACK_CLIENT_WRITEABLE
 368  *              and servers get LWS_CALLBACK_SERVER_WRITEABLE.
 369  *
 370  *      LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to
 371  *              the server at network level; the connection is accepted but then
 372  *              passed to this callback to decide whether to hang up immediately
 373  *              or not, based on the client IP.  @user contains the connection
 374  *              socket's descriptor.  Return non-zero to terminate
 375  *              the connection before sending or receiving anything.
 376  *              Because this happens immediately after the network connection
 377  *              from the client, there's no websocket protocol selected yet so
 378  *              this callback is issued only to protocol 0.
 379  *
 380  *      LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has
 381  *              been received and parsed from the client, but the response is
 382  *              not sent yet.  Return non-zero to disallow the connection.
 383  *              @user is a pointer to an array of struct lws_tokens, you can
 384  *              use the header enums lws_token_indexes from libwebsockets.h
 385  *              to check for and read the supported header presence and
 386  *              content before deciding to allow the handshake to proceed or
 387  *              to kill the connection.
 388  *
 389  *      LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS: if configured for
 390  *              including OpenSSL support, this callback allows your user code
 391  *              to perform extra SSL_CTX_load_verify_locations() or similar
 392  *              calls to direct OpenSSL where to find certificates the client
 393  *              can use to confirm the remote server identity.  @user is the
 394  *              OpenSSL SSL_CTX*
 395  *
 396  *      LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS: if configured for
 397  *              including OpenSSL support, this callback allows your user code
 398  *              to load extra certifcates into the server which allow it to
 399  *              verify the validity of certificates returned by clients.  @user
 400  *              is the server's OpenSSL SSL_CTX*
 401  *
 402  *      LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION: if the
 403  *              libwebsockets context was created with the option
 404  *              LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
 405  *              callback is generated during OpenSSL verification of the cert
 406  *              sent from the client.  It is sent to protocol[0] callback as
 407  *              no protocol has been negotiated on the connection yet.
 408  *              Notice that the libwebsockets context and wsi are both NULL
 409  *              during this callback.  See
 410  *               http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
 411  *              to understand more detail about the OpenSSL callback that
 412  *              generates this libwebsockets callback and the meanings of the
 413  *              arguments passed.  In this callback, @user is the x509_ctx,
 414  *              @in is the ssl pointer and @len is preverify_ok
 415  *              Notice that this callback maintains libwebsocket return
 416  *              conventions, return 0 to mean the cert is OK or 1 to fail it.
 417  *              This also means that if you don't handle this callback then
 418  *              the default callback action of returning 0 allows the client
 419  *              certificates.
 420  *
 421  *      LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER: this callback happens
 422  *              when a client handshake is being compiled.  @user is NULL,
 423  *              @in is a char **, it's pointing to a char * which holds the
 424  *              next location in the header buffer where you can add
 425  *              headers, and @len is the remaining space in the header buffer,
 426  *              which is typically some hundreds of bytes.  So, to add a canned
 427  *              cookie, your handler code might look similar to:
 428  *
 429  *              char **p = (char **)in;
 430  *
 431  *              if (len < 100)
 432  *                      return 1;
 433  *
 434  *              *p += sprintf(*p, "Cookie: a=b\x0d\x0a");
 435  *
 436  *              return 0;
 437  *
 438  *              Notice if you add anything, you just have to take care about
 439  *              the CRLF on the line you added.  Obviously this callback is
 440  *              optional, if you don't handle it everything is fine.
 441  *
 442  *              Notice the callback is coming to protocols[0] all the time,
 443  *              because there is no specific protocol handshook yet.
 444  *
 445  *      LWS_CALLBACK_CONFIRM_EXTENSION_OKAY: When the server handshake code
 446  *              sees that it does support a requested extension, before
 447  *              accepting the extension by additing to the list sent back to
 448  *              the client it gives this callback just to check that it's okay
 449  *              to use that extension.  It calls back to the requested protocol
 450  *              and with @in being the extension name, @len is 0 and @user is
 451  *              valid.  Note though at this time the ESTABLISHED callback hasn't
 452  *              happened yet so if you initialize @user content there, @user
 453  *              content during this callback might not be useful for anything.
 454  *              Notice this callback comes to protocols[0].
 455  *
 456  *      LWS_CALLBACK_CLIENT_CONFIRM_EXTENSION_SUPPORTED:        When a client
 457  *              connection is being prepared to start a handshake to a server,
 458  *              each supported extension is checked with protocols[0] callback
 459  *              with this reason, giving the user code a chance to suppress the
 460  *              claim to support that extension by returning non-zero.  If
 461  *              unhandled, by default 0 will be returned and the extension
 462  *              support included in the header to the server.  Notice this
 463  *              callback comes to protocols[0].
 464  *
 465  *      The next four reasons are optional and only need taking care of if you
 466  *      will be integrating libwebsockets sockets into an external polling
 467  *      array.
 468  *
 469  *      LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
 470  *              internally, but in the case you are integrating with another
 471  *              server you will need to have libwebsocket sockets share a
 472  *              polling array with the other server.  This and the other
 473  *              POLL_FD related callbacks let you put your specialized
 474  *              poll array interface code in the callback for protocol 0, the
 475  *              first protocol you support, usually the HTTP protocol in the
 476  *              serving case.  This callback happens when a socket needs to be
 477  *              added to the polling loop: @user contains the fd, and
 478  *              @len is the events bitmap (like, POLLIN).  If you are using the
 479  *              internal polling loop (the "service" callback), you can just
 480  *              ignore these callbacks.
 481  *
 482  *      LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
 483  *              needs to be removed from an external polling array.  @user is
 484  *              the socket desricptor.  If you are using the internal polling
 485  *              loop, you can just ignore it.
 486  *
 487  *      LWS_CALLBACK_SET_MODE_POLL_FD: This callback happens when libwebsockets
 488  *              wants to modify the events for the socket descriptor in @user.
 489  *              The handler should OR @len on to the events member of the pollfd
 490  *              struct for this socket descriptor.  If you are using the
 491  *              internal polling loop, you can just ignore it.
 492  *
 493  *      LWS_CALLBACK_CLEAR_MODE_POLL_FD: This callback occurs when libwebsockets
 494  *              wants to modify the events for the socket descriptor in @user.
 495  *              The handler should AND ~@len on to the events member of the
 496  *              pollfd struct for this socket descriptor.  If you are using the
 497  *              internal polling loop, you can just ignore it.
 498  */
 499 LWS_EXTERN int callback(struct libwebsocket_context * context,
 500                         struct libwebsocket *wsi,
 501                          enum libwebsocket_callback_reasons reason, void *user,
 502                                                           void *in, size_t len);
 503
 504 typedef int (callback_function)(struct libwebsocket_context * context,
 505                         struct libwebsocket *wsi,
 506                          enum libwebsocket_callback_reasons reason, void *user,
 507                                                           void *in, size_t len);
 508
 509
 510 /**
 511  * extension_callback_function() - Hooks to allow extensions to operate
 512  * @context:    Websockets context
 513  * @ext:        This extension
 514  * @wsi:        Opaque websocket instance pointer
 515  * @reason:     The reason for the call
 516  * @user:       Pointer to per-session user data allocated by library
 517  * @in:         Pointer used for some callback reasons
 518  * @len:        Length set for some callback reasons
 519  *
 520  *      Each extension that is active on a particular connection receives
 521  *      callbacks during the connection lifetime to allow the extension to
 522  *      operate on websocket data and manage itself.
 523  *
 524  *      Libwebsockets takes care of allocating and freeing "user" memory for
 525  *      each active extension on each connection.  That is what is pointed to
 526  *      by the @user parameter.
 527  *
 528  *      LWS_EXT_CALLBACK_CONSTRUCT:  called when the server has decided to
 529  *              select this extension from the list provided by the client,
 530  *              just before the server will send back the handshake accepting
 531  *              the connection with this extension active.  This gives the
 532  *              extension a chance to initialize its connection context found
 533  *              in @user.
 534  *
 535  *      LWS_EXT_CALLBACK_CLIENT_CONSTRUCT: same as LWS_EXT_CALLBACK_CONSTRUCT
 536  *              but called when client is instantiating this extension.  Some
 537  *              extensions will work the same on client and server side and then
 538  *              you can just merge handlers for both CONSTRUCTS.
 539  *
 540  *      LWS_EXT_CALLBACK_DESTROY:  called when the connection the extension was
 541  *              being used on is about to be closed and deallocated.  It's the
 542  *              last chance for the extension to deallocate anything it has
 543  *              allocated in the user data (pointed to by @user) before the
 544  *              user data is deleted.  This same callback is used whether you
 545  *              are in client or server instantiation context.
 546  *
 547  *      LWS_EXT_CALLBACK_PACKET_RX_PREPARSE: when this extension was active on
 548  *              a connection, and a packet of data arrived at the connection,
 549  *              it is passed to this callback to give the extension a chance to
 550  *              change the data, eg, decompress it.  @user is pointing to the
 551  *              extension's private connection context data, @in is pointing
 552  *              to an lws_tokens struct, it consists of a char * pointer called
 553  *              token, and an int called token_len.  At entry, these are
 554  *              set to point to the received buffer and set to the content
 555  *              length.  If the extension will grow the content, it should use
 556  *              a new buffer allocated in its private user context data and
 557  *              set the pointed-to lws_tokens members to point to its buffer.
 558  *
 559  *      LWS_EXT_CALLBACK_PACKET_TX_PRESEND: this works the same way as
 560  *              LWS_EXT_CALLBACK_PACKET_RX_PREPARSE above, except it gives the
 561  *              extension a chance to change websocket data just before it will
 562  *              be sent out.  Using the same lws_token pointer scheme in @in,
 563  *              the extension can change the buffer and the length to be
 564  *              transmitted how it likes.  Again if it wants to grow the
 565  *              buffer safely, it should copy the data into its own buffer and
 566  *              set the lws_tokens token pointer to it.
 567  */
 568 LWS_EXTERN int extension_callback(struct libwebsocket_context * context,
 569                         struct libwebsocket_extension *ext,
 570                         struct libwebsocket *wsi,
 571                          enum libwebsocket_extension_callback_reasons reason, void *user,
 572                                                           void *in, size_t len);
 573
 574 typedef int (extension_callback_function)(struct libwebsocket_context * context,
 575                         struct libwebsocket_extension *ext,
 576                         struct libwebsocket *wsi,
 577                          enum libwebsocket_extension_callback_reasons reason, void *user,
 578                                                           void *in, size_t len);
 579
 580 /**
 581  * struct libwebsocket_protocols -      List of protocols and handlers server
 582  *                                      supports.
 583  * @name:       Protocol name that must match the one given in the client
 584  *              Javascript new WebSocket(url, 'protocol') name
 585  * @callback:   The service callback used for this protocol.  It allows the
 586  *              service action for an entire protocol to be encapsulated in
 587  *              the protocol-specific callback
 588  * @per_session_data_size:      Each new connection using this protocol gets
 589  *              this much memory allocated on connection establishment and
 590  *              freed on connection takedown.  A pointer to this per-connection
 591  *              allocation is passed into the callback in the 'user' parameter
 592  * @owning_server:      the server init call fills in this opaque pointer when
 593  *              registering this protocol with the server.
 594  * @broadcast_socket_port: the server init call fills this in with the
 595  *              localhost port number used to forward broadcasts for this
 596  *              protocol
 597  * @broadcast_socket_user_fd:  the server init call fills this in ... the main()
 598  *              process context can write to this socket to perform broadcasts
 599  *              (use the libwebsockets_broadcast() api to do this instead,
 600  *              it works from any process context)
 601  * @protocol_index: which protocol we are starting from zero
 602  *
 603  *      This structure represents one protocol supported by the server.  An
 604  *      array of these structures is passed to libwebsocket_create_server()
 605  *      allows as many protocols as you like to be handled by one server.
 606  */
 607
 608 struct libwebsocket_protocols {
 609         const char *name;
 610         callback_function *callback;
 611         size_t per_session_data_size;
 612
 613         /*
 614          * below are filled in on server init and can be left uninitialized,
 615          * no need for user to use them directly either
 616          */
 617
 618         struct libwebsocket_context *owning_server;
 619         int broadcast_socket_port;
 620         int broadcast_socket_user_fd;
 621         int protocol_index;
 622 };
 623
 624 /**
 625  * struct libwebsocket_extension -      An extension we know how to cope with
 626  *
 627  * @name:                       Formal extension name, eg, "deflate-stream"
 628  * @callback:                   Service callback
 629  * @per_session_data_size:      Libwebsockets will auto-malloc this much
 630  *                              memory for the use of the extension, a pointer
 631  *                              to it comes in the @user callback parameter
 632  * @per_context_private_data:   Optional storage for this externsion that
 633  *                              is per-context, so it can track stuff across
 634  *                              all sessions, etc, if it wants
 635  */
 636
 637 struct libwebsocket_extension {
 638         const char *name;
 639         extension_callback_function *callback;
 640         size_t per_session_data_size;
 641         void * per_context_private_data;
 642 };
 643
 644
 645
 646 LWS_EXTERN struct libwebsocket_context *
 647 libwebsocket_create_context(int port, const char * interf,
 648                   struct libwebsocket_protocols *protocols,
 649                   struct libwebsocket_extension *extensions,
 650                   const char *ssl_cert_filepath,
 651                   const char *ssl_private_key_filepath,
 652                   const char *ssl_ca_filepath,
 653                   int gid, int uid,
 654                   unsigned int options, void *user);
 655
 656 LWS_EXTERN void
 657 libwebsocket_context_destroy(struct libwebsocket_context *context);
 658
 659 LWS_EXTERN int
 660 libwebsockets_fork_service_loop(struct libwebsocket_context *context);
 661
 662 LWS_EXTERN int
 663 libwebsocket_service(struct libwebsocket_context *context, int timeout_ms);
 664
 665 LWS_EXTERN int
 666 libwebsocket_service_fd(struct libwebsocket_context *context,
 667                                                          struct pollfd *pollfd);
 668
 669 LWS_EXTERN void *
 670 libwebsocket_context_user(struct libwebsocket_context *context);
 671
 672 /*
 673  * IMPORTANT NOTICE!
 674  *
 675  * When sending with websocket protocol (LWS_WRITE_TEXT or LWS_WRITE_BINARY)
 676  * the send buffer has to have LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE
 677  * buf, and LWS_SEND_BUFFER_POST_PADDING bytes valid AFTER (buf + len).
 678  *
 679  * This allows us to add protocol info before and after the data, and send as
 680  * one packet on the network without payload copying, for maximum efficiency.
 681  *
 682  * So for example you need this kind of code to use libwebsocket_write with a
 683  * 128-byte payload
 684  *
 685  *   char buf[LWS_SEND_BUFFER_PRE_PADDING + 128 + LWS_SEND_BUFFER_POST_PADDING];
 686  *
 687  *   // fill your part of the buffer... for example here it's all zeros
 688  *   memset(&buf[LWS_SEND_BUFFER_PRE_PADDING], 0, 128);
 689  *
 690  *   libwebsocket_write(wsi, &buf[LWS_SEND_BUFFER_PRE_PADDING], 128);
 691  *
 692  * When sending LWS_WRITE_HTTP, there is no protocol addition and you can just
 693  * use the whole buffer without taking care of the above.
 694  */
 695
 696 /*
 697  * this is the frame nonce plus two header plus 8 length
 698  *   there's an additional two for mux extension per mux nesting level
 699  * 2 byte prepend on close will already fit because control frames cannot use
 700  * the big length style
 701  */
 702
 703 #define LWS_SEND_BUFFER_PRE_PADDING (4 + 10 + (2 * MAX_MUX_RECURSION))
 704 #define LWS_SEND_BUFFER_POST_PADDING 4
 705
 706 LWS_EXTERN int
 707 libwebsocket_write(struct libwebsocket *wsi, unsigned char *buf, size_t len,
 708                                      enum libwebsocket_write_protocol protocol);
 709
 710 LWS_EXTERN int
 711 libwebsockets_serve_http_file(struct libwebsocket *wsi, const char *file,
 712                                                      const char *content_type);
 713
 714 /* notice - you need the pre- and post- padding allocation for buf below */
 715
 716 LWS_EXTERN int
 717 libwebsockets_broadcast(const struct libwebsocket_protocols *protocol,
 718                                                 unsigned char *buf, size_t len);
 719
 720 LWS_EXTERN const struct libwebsocket_protocols *
 721 libwebsockets_get_protocol(struct libwebsocket *wsi);
 722
 723 LWS_EXTERN int
 724 libwebsocket_callback_on_writable(struct libwebsocket_context *context,
 725                                                       struct libwebsocket *wsi);
 726
 727 LWS_EXTERN int
 728 libwebsocket_callback_on_writable_all_protocol(
 729                                  const struct libwebsocket_protocols *protocol);
 730
 731 LWS_EXTERN int
 732 libwebsocket_get_socket_fd(struct libwebsocket *wsi);
 733
 734 LWS_EXTERN int
 735 libwebsocket_is_final_fragment(struct libwebsocket *wsi);
 736
 737 LWS_EXTERN unsigned char
 738 libwebsocket_get_reserved_bits(struct libwebsocket *wsi);
 739
 740 LWS_EXTERN void *
 741 libwebsocket_ensure_user_space(struct libwebsocket *wsi);
 742
 743 LWS_EXTERN int
 744 libwebsocket_rx_flow_control(struct libwebsocket *wsi, int enable);
 745
 746 LWS_EXTERN size_t
 747 libwebsockets_remaining_packet_payload(struct libwebsocket *wsi);
 748
 749 LWS_EXTERN struct libwebsocket *
 750 libwebsocket_client_connect(struct libwebsocket_context *clients,
 751                               const char *address,
 752                               int port,
 753                               int ssl_connection,
 754                               const char *path,
 755                               const char *host,
 756                               const char *origin,
 757                               const char *protocol,
 758                               int ietf_version_or_minus_one);
 759
 760 LWS_EXTERN struct libwebsocket *
 761 libwebsocket_client_connect_extended(struct libwebsocket_context *clients,
 762                               const char *address,
 763                               int port,
 764                               int ssl_connection,
 765                               const char *path,
 766                               const char *host,
 767                               const char *origin,
 768                               const char *protocol,
 769                               int ietf_version_or_minus_one,
 770                               void *userdata);
 771
 772 LWS_EXTERN const char *
 773 libwebsocket_canonical_hostname(struct libwebsocket_context *context);
 774
 775
 776 LWS_EXTERN void
 777 libwebsockets_get_peer_addresses(int fd, char *name, int name_len,
 778                                         char *rip, int rip_len);
 779
 780 LWS_EXTERN void
 781 libwebsockets_hangup_on_client(struct libwebsocket_context *context, int fd);
 782
 783 LWS_EXTERN void
 784 libwebsocket_close_and_free_session(struct libwebsocket_context *context,
 785                                struct libwebsocket *wsi, enum lws_close_status);
 786
 787 LWS_EXTERN int
 788 libwebsockets_get_random(struct libwebsocket_context *context,
 789                                                             void *buf, int len);
 790
 791 LWS_EXTERN int
 792 lws_send_pipe_choked(struct libwebsocket *wsi);
 793
 794 LWS_EXTERN unsigned char *
 795 libwebsockets_SHA1(const unsigned char *d, size_t n, unsigned char *md);
 796
 797 LWS_EXTERN int
 798 lws_b64_encode_string(const char *in, int in_len, char *out, int out_size);
 799
 800 LWS_EXTERN int
 801 lws_b64_decode_string(const char *in, char *out, int out_size);
 802
 803 LWS_EXTERN struct libwebsocket_extension libwebsocket_internal_extensions[];
 804
 805 #ifdef __cplusplus
 806 }
 807 #endif
 808
 809 #endif