2 * libwebsockets - small server side websockets and web server implementation
4 * Copyright (C) 2010 Andy Green <andy@warmcat.com>
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.
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.
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,
22 #ifndef __LIBWEBSOCKET_H__
23 #define __LIBWEBSOCKET_H__
27 #define CONTEXT_PORT_NO_LISTEN 0
30 enum libwebsocket_context_options {
31 LWS_SERVER_OPTION_DEFEAT_CLIENT_MASK = 1,
34 enum libwebsocket_callback_reasons {
35 LWS_CALLBACK_ESTABLISHED,
36 LWS_CALLBACK_CLIENT_ESTABLISHED,
39 LWS_CALLBACK_CLIENT_RECEIVE,
40 LWS_CALLBACK_CLIENT_RECEIVE_PONG,
41 LWS_CALLBACK_CLIENT_WRITEABLE,
43 LWS_CALLBACK_BROADCAST,
44 LWS_CALLBACK_FILTER_NETWORK_CONNECTION,
45 LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION,
47 /* external poll() management support */
48 LWS_CALLBACK_ADD_POLL_FD,
49 LWS_CALLBACK_DEL_POLL_FD,
50 LWS_CALLBACK_SET_MODE_POLL_FD,
51 LWS_CALLBACK_CLEAR_MODE_POLL_FD,
54 enum libwebsocket_write_protocol {
59 /* special 04+ opcodes */
67 LWS_WRITE_NO_FIN = 0x40,
69 * client packet payload goes out on wire unmunged
70 * only useful for security tests since normal servers cannot
71 * decode the content if used
73 LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
77 * you need these to look at headers that have been parsed if using the
78 * LWS_CALLBACK_FILTER_CONNECTION callback. If a header from the enum
79 * list below is absent, .token = NULL and token_len = 0. Otherwise .token
80 * points to .token_len chars containing that header content.
88 enum lws_token_indexes {
106 WSI_TOKEN_EXTENSIONS,
108 /* client receives these */
113 /* always last real token index*/
115 /* parser state additions */
118 WSI_TOKEN_SKIPPING_SAW_CR,
123 struct libwebsocket_context;
125 /* document the generic callback (it's a fake prototype under this) */
127 * callback() - User server actions
128 * @this: Websockets context
129 * @wsi: Opaque websocket instance pointer
130 * @reason: The reason for the call
131 * @user: Pointer to per-session user data allocated by library
132 * @in: Pointer used for some callback reasons
133 * @len: Length set for some callback reasons
135 * This callback is the way the user controls what is served. All the
136 * protocol detail is hidden and handled by the library.
138 * For each connection / session there is user data allocated that is
139 * pointed to by "user". You set the size of this user data area when
140 * the library is initialized with libwebsocket_create_server.
142 * You get an opportunity to initialize user data when called back with
143 * LWS_CALLBACK_ESTABLISHED reason.
145 * LWS_CALLBACK_ESTABLISHED: after the server completes a handshake with
148 * LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed
149 * a handshake with the remote server
151 * LWS_CALLBACK_CLOSED: when the websocket session ends
153 * LWS_CALLBACK_BROADCAST: signal to send to client (you would use
154 * libwebsocket_write() taking care about the
155 * special buffer requirements
157 * LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a
158 * remote client, it can be found at *in and is
161 * LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,
162 * they appear with this callback reason. PONG
163 * packets only exist in 04+ protocol
165 * LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the
166 * client connection, it can be found at *in and
169 * LWS_CALLBACK_HTTP: an http request has come from a client that is not
170 * asking to upgrade the connection to a websocket
171 * one. This is a chance to serve http content,
172 * for example, to send a script to the client
173 * which will then open the websockets connection.
174 * @in points to the URI path requested and
175 * libwebsockets_serve_http_file() makes it very
176 * simple to send back a file to the client.
178 * LWS_CALLBACK_CLIENT_WRITEABLE: if you call
179 * libwebsocket_callback_on_writable() on a connection, you will
180 * get this callback coming when the connection socket is able to
181 * accept another write packet without blocking. If it already
182 * was able to take another packet without blocking, you'll get
183 * this callback at the next call to the service loop function.
185 * LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to
186 * the server at network level; the connection is accepted but then
187 * passed to this callback to decide whether to hang up immediately
188 * or not, based on the client IP. @user contains the connection
189 * socket's descriptor. Return non-zero to terminate
190 * the connection before sending or receiving anything.
191 * Because this happens immediately after the network connection
192 * from the client, there's no websocket protocol selected yet so
193 * this callback is issued only to protocol 0.
195 * LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has
196 * been received and parsed from the client, but the response is
197 * not sent yet. Return non-zero to disallow the connection.
198 * @user is a pointer to an array of struct lws_tokens, you can
199 * use the header enums lws_token_indexes from libwebsockets.h
200 * to check for and read the supported header presence and
201 * content before deciding to allow the handshake to proceed or
202 * to kill the connection.
205 * The next four reasons are optional and only need taking care of if you
206 * will be integrating libwebsockets sockets into an external polling
209 * LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
210 * internally, but in the case you are integrating with another
211 * server you will need to have libwebsocket sockets share a
212 * polling array with the other server. This and the other
213 * POLL_FD related callbacks let you put your specialized
214 * poll array interface code in the callback for protocol 0, the
215 * first protocol you support, usually the HTTP protocol in the
216 * serving case. This callback happens when a socket needs to be
217 * added to the polling loop: @user contains the fd, and
218 * @len is the events bitmap (like, POLLIN). If you are using the
219 * internal polling loop (the "service" callback), you can just
220 * ignore these callbacks.
222 * LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
223 * needs to be removed from an external polling array. @user is
224 * the socket desricptor. If you are using the internal polling
225 * loop, you can just ignore it.
227 * LWS_CALLBACK_SET_MODE_POLL_FD: This callback happens when libwebsockets
228 * wants to modify the events for the socket descriptor in @user.
229 * The handler should OR @len on to the events member of the pollfd
230 * struct for this socket descriptor. If you are using the
231 * internal polling loop, you can just ignore it.
233 * LWS_CALLBACK_CLEAR_MODE_POLL_FD: This callback occurs when libwebsockets
234 * wants to modify the events for the socket descriptor in @user.
235 * The handler should AND ~@len on to the events member of the
236 * pollfd struct for this socket descriptor. If you are using the
237 * internal polling loop, you can just ignore it.
239 extern int callback(struct libwebsocket_context * this,
240 struct libwebsocket *wsi,
241 enum libwebsocket_callback_reasons reason, void *user,
242 void *in, size_t len);
245 * struct libwebsocket_protocols - List of protocols and handlers server
247 * @name: Protocol name that must match the one given in the client
248 * Javascript new WebSocket(url, 'protocol') name
249 * @callback: The service callback used for this protocol. It allows the
250 * service action for an entire protocol to be encapsulated in
251 * the protocol-specific callback
252 * @per_session_data_size: Each new connection using this protocol gets
253 * this much memory allocated on connection establishment and
254 * freed on connection takedown. A pointer to this per-connection
255 * allocation is passed into the callback in the 'user' parameter
256 * @owning_server: the server init call fills in this opaque pointer when
257 * registering this protocol with the server.
258 * @broadcast_socket_port: the server init call fills this in with the
259 * localhost port number used to forward broadcasts for this
261 * @broadcast_socket_user_fd: the server init call fills this in ... the main()
262 * process context can write to this socket to perform broadcasts
263 * (use the libwebsockets_broadcast() api to do this instead,
264 * it works from any process context)
265 * @protocol_index: which protocol we are starting from zero
267 * This structure represents one protocol supported by the server. An
268 * array of these structures is passed to libwebsocket_create_server()
269 * allows as many protocols as you like to be handled by one server.
272 struct libwebsocket_protocols {
274 int (*callback)(struct libwebsocket_context * this,
275 struct libwebsocket *wsi,
276 enum libwebsocket_callback_reasons reason, void *user,
277 void *in, size_t len);
278 size_t per_session_data_size;
281 * below are filled in on server init and can be left uninitialized,
282 * no need for user to use them directly either
285 struct libwebsocket_context *owning_server;
286 int broadcast_socket_port;
287 int broadcast_socket_user_fd;
291 extern struct libwebsocket_context *
292 libwebsocket_create_context(int port,
293 struct libwebsocket_protocols *protocols,
294 const char *ssl_cert_filepath,
295 const char *ssl_private_key_filepath, int gid, int uid,
296 unsigned int options);
299 libwebsocket_context_destroy(struct libwebsocket_context *this);
302 libwebsockets_fork_service_loop(struct libwebsocket_context *this);
305 libwebsocket_service(struct libwebsocket_context *this, int timeout_ms);
308 libwebsocket_service_fd(struct libwebsocket_context *this,
309 struct pollfd *pollfd);
314 * When sending with websocket protocol (LWS_WRITE_TEXT or LWS_WRITE_BINARY)
315 * the send buffer has to have LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE
316 * buf, and LWS_SEND_BUFFER_POST_PADDING bytes valid AFTER (buf + len).
318 * This allows us to add protocol info before and after the data, and send as
319 * one packet on the network without payload copying, for maximum efficiency.
321 * So for example you need this kind of code to use libwebsocket_write with a
324 * char buf[LWS_SEND_BUFFER_PRE_PADDING + 128 + LWS_SEND_BUFFER_POST_PADDING];
326 * // fill your part of the buffer... for example here it's all zeros
327 * memset(&buf[LWS_SEND_BUFFER_PRE_PADDING], 0, 128);
329 * libwebsocket_write(wsi, &buf[LWS_SEND_BUFFER_PRE_PADDING], 128);
331 * When sending LWS_WRITE_HTTP, there is no protocol addition and you can just
332 * use the whole buffer without taking care of the above.
335 /* this is the frame nonce plus two header plus 8 length */
337 #define LWS_SEND_BUFFER_PRE_PADDING (4 + 10)
338 #define LWS_SEND_BUFFER_POST_PADDING 1
341 libwebsocket_write(struct libwebsocket *wsi, unsigned char *buf, size_t len,
342 enum libwebsocket_write_protocol protocol);
345 libwebsockets_serve_http_file(struct libwebsocket *wsi, const char *file,
346 const char *content_type);
348 /* notice - you need the pre- and post- padding allocation for buf below */
351 libwebsockets_broadcast(const struct libwebsocket_protocols *protocol,
352 unsigned char *buf, size_t len);
354 extern const struct libwebsocket_protocols *
355 libwebsockets_get_protocol(struct libwebsocket *wsi);
358 libwebsocket_callback_on_writable(struct libwebsocket_context *this,
359 struct libwebsocket *wsi);
362 libwebsocket_callback_on_writable_all_protocol(
363 const struct libwebsocket_protocols *protocol);
366 libwebsocket_get_socket_fd(struct libwebsocket *wsi);
369 libwebsocket_rx_flow_control(struct libwebsocket *wsi, int enable);
372 libwebsockets_remaining_packet_payload(struct libwebsocket *wsi);
374 extern struct libwebsocket *
375 libwebsocket_client_connect(struct libwebsocket_context *clients,
382 const char *protocol,
383 int ietf_version_or_minus_one);
386 libwebsocket_canonical_hostname(struct libwebsocket_context *this);
390 libwebsockets_get_peer_addresses(int fd, char *name, int name_len,
391 char *rip, int rip_len);
394 libwebsockets_hangup_on_client(struct libwebsocket_context *this, int fd);
397 libwebsocket_close_and_free_session(struct libwebsocket_context *this,
398 struct libwebsocket *wsi);