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