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
  26 enum libwebsocket_callback_reasons {
  27         LWS_CALLBACK_ESTABLISHED,
  28         LWS_CALLBACK_CLOSED,
  29         LWS_CALLBACK_RECEIVE,
  30         LWS_CALLBACK_HTTP,
  31         LWS_CALLBACK_BROADCAST,
  32 };
  33
  34 enum libwebsocket_write_protocol {
  35         LWS_WRITE_TEXT,
  36         LWS_WRITE_BINARY,
  37         LWS_WRITE_HTTP
  38 };
  39
  40 struct libwebsocket;
  41 struct libwebsocket_context;
  42
  43 /**
  44  * struct libwebsocket_protocols -      List of protocols and handlers server
  45  *                                      supports.
  46  * @name:       Protocol name that must match the one given in the client
  47  *              Javascript new WebSocket(url, 'protocol') name
  48  * @callback:   The service callback used for this protocol.  It allows the
  49  *              service action for an entire protocol to be encapsulated in
  50  *              the protocol-specific callback
  51  * @per_session_data_size:      Each new connection using this protocol gets
  52  *              this much memory allocated on connection establishment and
  53  *              freed on connection takedown.  A pointer to this per-connection
  54  *              allocation is passed into the callback in the 'user' parameter
  55  * @owning_server:      the server init call fills in this opaque pointer when
  56  *              registering this protocol with the server.
  57  * @broadcast_socket_port: the server init call fills this in with the
  58  *              localhost port number used to forward broadcasts for this
  59  *              protocol
  60  * @broadcast_socket_user_fd:  the server init call fills this in ... the main()
  61  *              process context can write to this socket to perform broadcasts
  62  *              (use the libwebsockets_broadcast() api to do this instead,
  63  *              it works from any process context)
  64  * @protocol_index: which protocol we are starting from zero
  65  *
  66  *      This structure represents one protocol supported by the server.  An
  67  *      array of these structures is passed to libwebsocket_create_server()
  68  *      allows as many protocols as you like to be handled by one server.
  69  */
  70
  71 struct libwebsocket_protocols {
  72         const char *name;
  73         int (*callback)(struct libwebsocket *wsi,
  74                         enum libwebsocket_callback_reasons reason, void *user,
  75                                                           void *in, size_t len);
  76         size_t per_session_data_size;
  77
  78         /*
  79          * below are filled in on server init and can be left uninitialized,
  80          * no need for user to use them directly either
  81          */
  82
  83         struct libwebsocket_context *owning_server;
  84         int broadcast_socket_port;
  85         int broadcast_socket_user_fd;
  86         int protocol_index;
  87 };
  88
  89 extern int libwebsocket_create_server(int port,
  90                   struct libwebsocket_protocols *protocols,
  91                   const char *ssl_cert_filepath,
  92                   const char *ssl_private_key_filepath, int gid, int uid);
  93
  94 /*
  95  * IMPORTANT NOTICE!
  96  *
  97  * When sending with websocket protocol (LWS_WRITE_TEXT or LWS_WRITE_BINARY)
  98  * the send buffer has to have LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE
  99  * buf, and LWS_SEND_BUFFER_POST_PADDING bytes valid AFTER (buf + len).
 100  *
 101  * This allows us to add protocol info before and after the data, and send as
 102  * one packet on the network without payload copying, for maximum efficiency.
 103  *
 104  * So for example you need this kind of code to use libwebsocket_write with a
 105  * 128-byte payload
 106  *
 107  *   char buf[LWS_SEND_BUFFER_PRE_PADDING + 128 + LWS_SEND_BUFFER_POST_PADDING];
 108  *
 109  *   // fill your part of the buffer... for example here it's all zeros
 110  *   memset(&buf[LWS_SEND_BUFFER_PRE_PADDING], 0, 128);
 111  *
 112  *   libwebsocket_write(wsi, &buf[LWS_SEND_BUFFER_PRE_PADDING], 128);
 113  *
 114  * When sending LWS_WRITE_HTTP, there is no protocol addition and you can just
 115  * use the whole buffer without taking care of the above.
 116  */
 117
 118 #define LWS_SEND_BUFFER_PRE_PADDING 12
 119 #define LWS_SEND_BUFFER_POST_PADDING 1
 120
 121 extern int
 122 libwebsocket_write(struct libwebsocket *wsi, unsigned char *buf, size_t len,
 123                                      enum libwebsocket_write_protocol protocol);
 124
 125 extern int
 126 libwebsockets_serve_http_file(struct libwebsocket *wsi, const char *file,
 127                                                      const char *content_type);
 128
 129 /* notice - you need the pre- and post- padding allocation for buf below */
 130
 131 extern int
 132 libwebsockets_broadcast(const struct libwebsocket_protocols * protocol,
 133                                                 unsigned char *buf, size_t len);
 134
 135 extern const struct libwebsocket_protocols *
 136 libwebsockets_get_protocol(struct libwebsocket *wsi);
 137
 138 #endif