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