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