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 #include <poll.h>
  26
  27 #define CONTEXT_PORT_NO_LISTEN 0
  28
  29
  30 enum libwebsocket_context_options {
  31         LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK = 1,
  32         LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT = 2,
  33 };
  34
  35 enum libwebsocket_callback_reasons {
  36         LWS_CALLBACK_ESTABLISHED,
  37         LWS_CALLBACK_CLIENT_ESTABLISHED,
  38         LWS_CALLBACK_CLOSED,
  39         LWS_CALLBACK_RECEIVE,
  40         LWS_CALLBACK_CLIENT_RECEIVE,
  41         LWS_CALLBACK_CLIENT_RECEIVE_PONG,
  42         LWS_CALLBACK_CLIENT_WRITEABLE,
  43         LWS_CALLBACK_HTTP,
  44         LWS_CALLBACK_BROADCAST,
  45         LWS_CALLBACK_FILTER_NETWORK_CONNECTION,
  46         LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION,
  47         LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS,
  48         LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS,
  49         LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION,
  50
  51         /* external poll() management support */
  52         LWS_CALLBACK_ADD_POLL_FD,
  53         LWS_CALLBACK_DEL_POLL_FD,
  54         LWS_CALLBACK_SET_MODE_POLL_FD,
  55         LWS_CALLBACK_CLEAR_MODE_POLL_FD,
  56 };
  57
  58 enum libwebsocket_write_protocol {
  59         LWS_WRITE_TEXT,
  60         LWS_WRITE_BINARY,
  61         LWS_WRITE_HTTP,
  62
  63         /* special 04+ opcodes */
  64
  65         LWS_WRITE_CLOSE,
  66         LWS_WRITE_PING,
  67         LWS_WRITE_PONG,
  68
  69         /* flags */
  70
  71         LWS_WRITE_NO_FIN = 0x40,
  72         /*
  73          * client packet payload goes out on wire unmunged
  74          * only useful for security tests since normal servers cannot
  75          * decode the content if used
  76          */
  77         LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
  78 };
  79
  80 /*
  81  * you need these to look at headers that have been parsed if using the
  82  * LWS_CALLBACK_FILTER_CONNECTION callback.  If a header from the enum
  83  * list below is absent, .token = NULL and token_len = 0.  Otherwise .token
  84  * points to .token_len chars containing that header content.
  85  */
  86
  87 struct lws_tokens {
  88         char *token;
  89         int token_len;
  90 };
  91
  92 enum lws_token_indexes {
  93         WSI_TOKEN_GET_URI,
  94         WSI_TOKEN_HOST,
  95         WSI_TOKEN_CONNECTION,
  96         WSI_TOKEN_KEY1,
  97         WSI_TOKEN_KEY2,
  98         WSI_TOKEN_PROTOCOL,
  99         WSI_TOKEN_UPGRADE,
 100         WSI_TOKEN_ORIGIN,
 101         WSI_TOKEN_DRAFT,
 102         WSI_TOKEN_CHALLENGE,
 103
 104         /* new for 04 */
 105         WSI_TOKEN_KEY,
 106         WSI_TOKEN_VERSION,
 107         WSI_TOKEN_SWORIGIN,
 108
 109         /* new for 05 */
 110         WSI_TOKEN_EXTENSIONS,
 111
 112         /* client receives these */
 113         WSI_TOKEN_ACCEPT,
 114         WSI_TOKEN_NONCE,
 115         WSI_TOKEN_HTTP,
 116
 117         /* always last real token index*/
 118         WSI_TOKEN_COUNT,
 119         /* parser state additions */
 120         WSI_TOKEN_NAME_PART,
 121         WSI_TOKEN_SKIPPING,
 122         WSI_TOKEN_SKIPPING_SAW_CR,
 123         WSI_PARSING_COMPLETE
 124 };
 125
 126 /*
 127  * From 06 spec
 128    1000
 129
 130       1000 indicates a normal closure, meaning whatever purpose the
 131       connection was established for has been fulfilled.
 132
 133    1001
 134
 135       1001 indicates that an endpoint is "going away", such as a server
 136       going down, or a browser having navigated away from a page.
 137
 138    1002
 139
 140       1002 indicates that an endpoint is terminating the connection due
 141       to a protocol error.
 142
 143    1003
 144
 145       1003 indicates that an endpoint is terminating the connection
 146       because it has received a type of data it cannot accept (e.g. an
 147       endpoint that understands only text data may send this if it
 148       receives a binary message.)
 149
 150    1004
 151
 152       1004 indicates that an endpoint is terminating the connection
 153       because it has received a message that is too large.
 154 */
 155
 156 enum lws_close_status {
 157         LWS_CLOSE_STATUS_NOSTATUS = 0,
 158         LWS_CLOSE_STATUS_NORMAL = 1000,
 159         LWS_CLOSE_STATUS_GOINGAWAY = 1001,
 160         LWS_CLOSE_STATUS_PROTOCOL_ERR = 1002,
 161         LWS_CLOSE_STATUS_UNACCEPTABLE_OPCODE = 1003,
 162         LWS_CLOSE_STATUS_PAYLOAD_TOO_LARGE = 1004,
 163 };
 164
 165 struct libwebsocket;
 166 struct libwebsocket_context;
 167
 168 /* document the generic callback (it's a fake prototype under this) */
 169 /**
 170  * callback() - User server actions
 171  * @context:    Websockets context
 172  * @wsi:        Opaque websocket instance pointer
 173  * @reason:     The reason for the call
 174  * @user:       Pointer to per-session user data allocated by library
 175  * @in:         Pointer used for some callback reasons
 176  * @len:        Length set for some callback reasons
 177  *
 178  *      This callback is the way the user controls what is served.  All the
 179  *      protocol detail is hidden and handled by the library.
 180  *
 181  *      For each connection / session there is user data allocated that is
 182  *      pointed to by "user".  You set the size of this user data area when
 183  *      the library is initialized with libwebsocket_create_server.
 184  *
 185  *      You get an opportunity to initialize user data when called back with
 186  *      LWS_CALLBACK_ESTABLISHED reason.
 187  *
 188  *      LWS_CALLBACK_ESTABLISHED:  after the server completes a handshake with
 189  *                              an incoming client
 190  *
 191  *      LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed
 192  *                              a handshake with the remote server
 193  *
 194  *      LWS_CALLBACK_CLOSED: when the websocket session ends
 195  *
 196  *      LWS_CALLBACK_BROADCAST: signal to send to client (you would use
 197  *                              libwebsocket_write() taking care about the
 198  *                              special buffer requirements
 199  *
 200  *      LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a
 201  *                              remote client, it can be found at *in and is
 202  *                              len bytes long
 203  *
 204  *      LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,
 205  *                              they appear with this callback reason.  PONG
 206  *                              packets only exist in 04+ protocol
 207  *
 208  *      LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the
 209  *                              client connection, it can be found at *in and
 210  *                              is len bytes long
 211  *
 212  *      LWS_CALLBACK_HTTP: an http request has come from a client that is not
 213  *                              asking to upgrade the connection to a websocket
 214  *                              one.  This is a chance to serve http content,
 215  *                              for example, to send a script to the client
 216  *                              which will then open the websockets connection.
 217  *                              @in points to the URI path requested and
 218  *                              libwebsockets_serve_http_file() makes it very
 219  *                              simple to send back a file to the client.
 220  *
 221  *      LWS_CALLBACK_CLIENT_WRITEABLE:  if you call
 222  *              libwebsocket_callback_on_writable() on a connection, you will
 223  *              get this callback coming when the connection socket is able to
 224  *              accept another write packet without blocking.  If it already
 225  *              was able to take another packet without blocking, you'll get
 226  *              this callback at the next call to the service loop function.
 227  *
 228  *      LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to
 229  *              the server at network level; the connection is accepted but then
 230  *              passed to this callback to decide whether to hang up immediately
 231  *              or not, based on the client IP.  @user contains the connection
 232  *              socket's descriptor.  Return non-zero to terminate
 233  *              the connection before sending or receiving anything.
 234  *              Because this happens immediately after the network connection
 235  *              from the client, there's no websocket protocol selected yet so
 236  *              this callback is issued only to protocol 0.
 237  *
 238  *      LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has
 239  *              been received and parsed from the client, but the response is
 240  *              not sent yet.  Return non-zero to disallow the connection.
 241  *              @user is a pointer to an array of struct lws_tokens, you can
 242  *              use the header enums lws_token_indexes from libwebsockets.h
 243  *              to check for and read the supported header presence and
 244  *              content before deciding to allow the handshake to proceed or
 245  *              to kill the connection.
 246  *
 247  *      LWS_CALLBACK_OPENSSL_LOAD_EXTRA_CLIENT_VERIFY_CERTS: if configured for
 248  *              including OpenSSL support, this callback allows your user code
 249  *              to perform extra SSL_CTX_load_verify_locations() or similar
 250  *              calls to direct OpenSSL where to find certificates the client
 251  *              can use to confirm the remote server identity.  @user is the
 252  *              OpenSSL SSL_CTX*
 253  *
 254  *      LWS_CALLBACK_OPENSSL_LOAD_EXTRA_SERVER_VERIFY_CERTS: if configured for
 255  *              including OpenSSL support, this callback allows your user code
 256  *              to load extra certifcates into the server which allow it to
 257  *              verify the validity of certificates returned by clients.  @user
 258  *              is the server's OpenSSL SSL_CTX*
 259  *
 260  *      LWS_CALLBACK_OPENSSL_PERFORM_CLIENT_CERT_VERIFICATION: if the
 261  *              libwebsockets context was created with the option
 262  *              LWS_SERVER_OPTION_REQUIRE_VALID_OPENSSL_CLIENT_CERT, then this
 263  *              callback is generated during OpenSSL verification of the cert
 264  *              sent from the client.  It is sent to protocol[0] callback as
 265  *              no protocol has been negotiated on the connection yet.
 266  *              Notice that the libwebsockets context and wsi are both NULL
 267  *              during this callback.  See
 268  *               http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html
 269  *              to understand more detail about the OpenSSL callback that
 270  *              generates this libwebsockets callback and the meanings of the
 271  *              arguments passed.  In this callback, @user is the x509_ctx,
 272  *              @in is the ssl pointer and @len is preverify_ok
 273  *              Notice that this callback maintains libwebsocket return
 274  *              conventions, return 0 to mean the cert is OK or 1 to fail it.
 275  *              This also means that if you don't handle this callback then
 276  *              the default callback action of returning 0 allows the client
 277  *              certificates.
 278  *
 279  *      The next four reasons are optional and only need taking care of if you
 280  *      will be integrating libwebsockets sockets into an external polling
 281  *      array.
 282  *
 283  *      LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
 284  *              internally, but in the case you are integrating with another
 285  *              server you will need to have libwebsocket sockets share a
 286  *              polling array with the other server.  This and the other
 287  *              POLL_FD related callbacks let you put your specialized
 288  *              poll array interface code in the callback for protocol 0, the
 289  *              first protocol you support, usually the HTTP protocol in the
 290  *              serving case.  This callback happens when a socket needs to be
 291  *              added to the polling loop: @user contains the fd, and
 292  *              @len is the events bitmap (like, POLLIN).  If you are using the
 293  *              internal polling loop (the "service" callback), you can just
 294  *              ignore these callbacks.
 295  *
 296  *      LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
 297  *              needs to be removed from an external polling array.  @user is
 298  *              the socket desricptor.  If you are using the internal polling
 299  *              loop, you can just ignore it.
 300  *
 301  *      LWS_CALLBACK_SET_MODE_POLL_FD: This callback happens when libwebsockets
 302  *              wants to modify the events for the socket descriptor in @user.
 303  *              The handler should OR @len on to the events member of the pollfd
 304  *              struct for this socket descriptor.  If you are using the
 305  *              internal polling loop, you can just ignore it.
 306  *
 307  *      LWS_CALLBACK_CLEAR_MODE_POLL_FD: This callback occurs when libwebsockets
 308  *              wants to modify the events for the socket descriptor in @user.
 309  *              The handler should AND ~@len on to the events member of the
 310  *              pollfd struct for this socket descriptor.  If you are using the
 311  *              internal polling loop, you can just ignore it.
 312  */
 313 extern int callback(struct libwebsocket_context * context,
 314                         struct libwebsocket *wsi,
 315                          enum libwebsocket_callback_reasons reason, void *user,
 316                                                           void *in, size_t len);
 317
 318 /**
 319  * struct libwebsocket_protocols -      List of protocols and handlers server
 320  *                                      supports.
 321  * @name:       Protocol name that must match the one given in the client
 322  *              Javascript new WebSocket(url, 'protocol') name
 323  * @callback:   The service callback used for this protocol.  It allows the
 324  *              service action for an entire protocol to be encapsulated in
 325  *              the protocol-specific callback
 326  * @per_session_data_size:      Each new connection using this protocol gets
 327  *              this much memory allocated on connection establishment and
 328  *              freed on connection takedown.  A pointer to this per-connection
 329  *              allocation is passed into the callback in the 'user' parameter
 330  * @owning_server:      the server init call fills in this opaque pointer when
 331  *              registering this protocol with the server.
 332  * @broadcast_socket_port: the server init call fills this in with the
 333  *              localhost port number used to forward broadcasts for this
 334  *              protocol
 335  * @broadcast_socket_user_fd:  the server init call fills this in ... the main()
 336  *              process context can write to this socket to perform broadcasts
 337  *              (use the libwebsockets_broadcast() api to do this instead,
 338  *              it works from any process context)
 339  * @protocol_index: which protocol we are starting from zero
 340  *
 341  *      This structure represents one protocol supported by the server.  An
 342  *      array of these structures is passed to libwebsocket_create_server()
 343  *      allows as many protocols as you like to be handled by one server.
 344  */
 345
 346 struct libwebsocket_protocols {
 347         const char *name;
 348         int (*callback)(struct libwebsocket_context * context,
 349                         struct libwebsocket *wsi,
 350                         enum libwebsocket_callback_reasons reason, void *user,
 351                                                           void *in, size_t len);
 352         size_t per_session_data_size;
 353
 354         /*
 355          * below are filled in on server init and can be left uninitialized,
 356          * no need for user to use them directly either
 357          */
 358
 359         struct libwebsocket_context *owning_server;
 360         int broadcast_socket_port;
 361         int broadcast_socket_user_fd;
 362         int protocol_index;
 363 };
 364
 365 extern struct libwebsocket_context *
 366 libwebsocket_create_context(int port, const char * interface,
 367                   struct libwebsocket_protocols *protocols,
 368                   const char *ssl_cert_filepath,
 369                   const char *ssl_private_key_filepath, int gid, int uid,
 370                   unsigned int options);
 371
 372 extern void
 373 libwebsocket_context_destroy(struct libwebsocket_context *context);
 374
 375 extern int
 376 libwebsockets_fork_service_loop(struct libwebsocket_context *context);
 377
 378 extern int
 379 libwebsocket_service(struct libwebsocket_context *context, int timeout_ms);
 380
 381 extern int
 382 libwebsocket_service_fd(struct libwebsocket_context *context,
 383                                                          struct pollfd *pollfd);
 384
 385 /*
 386  * IMPORTANT NOTICE!
 387  *
 388  * When sending with websocket protocol (LWS_WRITE_TEXT or LWS_WRITE_BINARY)
 389  * the send buffer has to have LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE
 390  * buf, and LWS_SEND_BUFFER_POST_PADDING bytes valid AFTER (buf + len).
 391  *
 392  * This allows us to add protocol info before and after the data, and send as
 393  * one packet on the network without payload copying, for maximum efficiency.
 394  *
 395  * So for example you need this kind of code to use libwebsocket_write with a
 396  * 128-byte payload
 397  *
 398  *   char buf[LWS_SEND_BUFFER_PRE_PADDING + 128 + LWS_SEND_BUFFER_POST_PADDING];
 399  *
 400  *   // fill your part of the buffer... for example here it's all zeros
 401  *   memset(&buf[LWS_SEND_BUFFER_PRE_PADDING], 0, 128);
 402  *
 403  *   libwebsocket_write(wsi, &buf[LWS_SEND_BUFFER_PRE_PADDING], 128);
 404  *
 405  * When sending LWS_WRITE_HTTP, there is no protocol addition and you can just
 406  * use the whole buffer without taking care of the above.
 407  */
 408
 409 /*
 410  * this is the frame nonce plus two header plus 8 length
 411  * 2 byte prepend on close will already fit because control frames cannot use
 412  * the big length style
 413  */
 414
 415 #define LWS_SEND_BUFFER_PRE_PADDING (4 + 10)
 416 #define LWS_SEND_BUFFER_POST_PADDING 1
 417
 418 extern int
 419 libwebsocket_write(struct libwebsocket *wsi, unsigned char *buf, size_t len,
 420                                      enum libwebsocket_write_protocol protocol);
 421
 422 extern int
 423 libwebsockets_serve_http_file(struct libwebsocket *wsi, const char *file,
 424                                                      const char *content_type);
 425
 426 /* notice - you need the pre- and post- padding allocation for buf below */
 427
 428 extern int
 429 libwebsockets_broadcast(const struct libwebsocket_protocols *protocol,
 430                                                 unsigned char *buf, size_t len);
 431
 432 extern const struct libwebsocket_protocols *
 433 libwebsockets_get_protocol(struct libwebsocket *wsi);
 434
 435 extern int
 436 libwebsocket_callback_on_writable(struct libwebsocket_context *context,
 437                                                       struct libwebsocket *wsi);
 438
 439 extern int
 440 libwebsocket_callback_on_writable_all_protocol(
 441                                  const struct libwebsocket_protocols *protocol);
 442
 443 extern int
 444 libwebsocket_get_socket_fd(struct libwebsocket *wsi);
 445
 446 extern int
 447 libwebsocket_rx_flow_control(struct libwebsocket *wsi, int enable);
 448
 449 extern size_t
 450 libwebsockets_remaining_packet_payload(struct libwebsocket *wsi);
 451
 452 extern struct libwebsocket *
 453 libwebsocket_client_connect(struct libwebsocket_context *clients,
 454                               const char *address,
 455                               int port,
 456                               int ssl_connection,
 457                               const char *path,
 458                               const char *host,
 459                               const char *origin,
 460                               const char *protocol,
 461                               int ietf_version_or_minus_one);
 462
 463 extern const char *
 464 libwebsocket_canonical_hostname(struct libwebsocket_context *context);
 465
 466
 467 extern void
 468 libwebsockets_get_peer_addresses(int fd, char *name, int name_len,
 469                                         char *rip, int rip_len);
 470
 471 extern void
 472 libwebsockets_hangup_on_client(struct libwebsocket_context *context, int fd);
 473
 474 extern void
 475 libwebsocket_close_and_free_session(struct libwebsocket_context *context,
 476                                struct libwebsocket *wsi, enum lws_close_status);
 477
 478 #endif