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 * @wsi: Opaque websocket instance pointer
129 * @reason: The reason for the call
130 * @user: Pointer to per-session user data allocated by library
131 * @in: Pointer used for some callback reasons
132 * @len: Length set for some callback reasons
134 * This callback is the way the user controls what is served. All the
135 * protocol detail is hidden and handled by the library.
137 * For each connection / session there is user data allocated that is
138 * pointed to by "user". You set the size of this user data area when
139 * the library is initialized with libwebsocket_create_server.
141 * You get an opportunity to initialize user data when called back with
142 * LWS_CALLBACK_ESTABLISHED reason.
144 * LWS_CALLBACK_ESTABLISHED: after the server completes a handshake with
147 * LWS_CALLBACK_CLIENT_ESTABLISHED: after your client connection completed
148 * a handshake with the remote server
150 * LWS_CALLBACK_CLOSED: when the websocket session ends
152 * LWS_CALLBACK_BROADCAST: signal to send to client (you would use
153 * libwebsocket_write() taking care about the
154 * special buffer requirements
156 * LWS_CALLBACK_RECEIVE: data has appeared for this server endpoint from a
157 * remote client, it can be found at *in and is
160 * LWS_CALLBACK_CLIENT_RECEIVE_PONG: if you elected to see PONG packets,
161 * they appear with this callback reason. PONG
162 * packets only exist in 04+ protocol
164 * LWS_CALLBACK_CLIENT_RECEIVE: data has appeared from the server for the
165 * client connection, it can be found at *in and
168 * LWS_CALLBACK_HTTP: an http request has come from a client that is not
169 * asking to upgrade the connection to a websocket
170 * one. This is a chance to serve http content,
171 * for example, to send a script to the client
172 * which will then open the websockets connection.
173 * @in points to the URI path requested and
174 * libwebsockets_serve_http_file() makes it very
175 * simple to send back a file to the client.
177 * LWS_CALLBACK_CLIENT_WRITEABLE: if you call
178 * libwebsocket_callback_on_writable() on a connection, you will
179 * get this callback coming when the connection socket is able to
180 * accept another write packet without blocking. If it already
181 * was able to take another packet without blocking, you'll get
182 * this callback at the next call to the service loop function.
184 * LWS_CALLBACK_FILTER_NETWORK_CONNECTION: called when a client connects to
185 * the server at network level; the connection is accepted but then
186 * passed to this callback to decide whether to hang up immediately
187 * or not, based on the client IP. @user contains the connection
188 * socket's descriptor. Return non-zero to terminate
189 * the connection before sending or receiving anything.
190 * Because this happens immediately after the network connection
191 * from the client, there's no websocket protocol selected yet so
192 * this callback is issued only to protocol 0.
194 * LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION: called when the handshake has
195 * been received and parsed from the client, but the response is
196 * not sent yet. Return non-zero to disallow the connection.
197 * @user is a pointer to an array of struct lws_tokens, you can
198 * use the header enums lws_token_indexes from libwebsockets.h
199 * to check for and read the supported header presence and
200 * content before deciding to allow the handshake to proceed or
201 * to kill the connection.
204 * The next four reasons are optional and only need taking care of if you
205 * will be integrating libwebsockets sockets into an external polling
208 * LWS_CALLBACK_ADD_POLL_FD: libwebsocket deals with its poll() loop
209 * internally, but in the case you are integrating with another
210 * server you will need to have libwebsocket sockets share a
211 * polling array with the other server. This and the other
212 * POLL_FD related callbacks let you put your specialized
213 * poll array interface code in the callback for protocol 0, the
214 * first protocol you support, usually the HTTP protocol in the
215 * serving case. This callback happens when a socket needs to be
216 * added to the polling loop: @user contains the fd, and
217 * @len is the events bitmap (like, POLLIN). If you are using the
218 * internal polling loop (the "service" callback), you can just
219 * ignore these callbacks.
221 * LWS_CALLBACK_DEL_POLL_FD: This callback happens when a socket descriptor
222 * needs to be removed from an external polling array. @user is
223 * the socket desricptor. If you are using the internal polling
224 * loop, you can just ignore it.
226 * LWS_CALLBACK_SET_MODE_POLL_FD: This callback happens when libwebsockets
227 * wants to modify the events for the socket descriptor in @user.
228 * The handler should OR @len on to the events member of the pollfd
229 * struct for this socket descriptor. If you are using the
230 * internal polling loop, you can just ignore it.
232 * LWS_CALLBACK_CLEAR_MODE_POLL_FD: This callback occurs when libwebsockets
233 * wants to modify the events for the socket descriptor in @user.
234 * The handler should AND ~@len on to the events member of the
235 * pollfd struct for this socket descriptor. If you are using the
236 * internal polling loop, you can just ignore it.
238 extern int callback(struct libwebsocket *wsi,
239 enum libwebsocket_callback_reasons reason, void *user,
240 void *in, size_t len);
243 * struct libwebsocket_protocols - List of protocols and handlers server
245 * @name: Protocol name that must match the one given in the client
246 * Javascript new WebSocket(url, 'protocol') name
247 * @callback: The service callback used for this protocol. It allows the
248 * service action for an entire protocol to be encapsulated in
249 * the protocol-specific callback
250 * @per_session_data_size: Each new connection using this protocol gets
251 * this much memory allocated on connection establishment and
252 * freed on connection takedown. A pointer to this per-connection
253 * allocation is passed into the callback in the 'user' parameter
254 * @owning_server: the server init call fills in this opaque pointer when
255 * registering this protocol with the server.
256 * @broadcast_socket_port: the server init call fills this in with the
257 * localhost port number used to forward broadcasts for this
259 * @broadcast_socket_user_fd: the server init call fills this in ... the main()
260 * process context can write to this socket to perform broadcasts
261 * (use the libwebsockets_broadcast() api to do this instead,
262 * it works from any process context)
263 * @protocol_index: which protocol we are starting from zero
265 * This structure represents one protocol supported by the server. An
266 * array of these structures is passed to libwebsocket_create_server()
267 * allows as many protocols as you like to be handled by one server.
270 struct libwebsocket_protocols {
272 int (*callback)(struct libwebsocket *wsi,
273 enum libwebsocket_callback_reasons reason, void *user,
274 void *in, size_t len);
275 size_t per_session_data_size;
278 * below are filled in on server init and can be left uninitialized,
279 * no need for user to use them directly either
282 struct libwebsocket_context *owning_server;
283 int broadcast_socket_port;
284 int broadcast_socket_user_fd;
288 extern struct libwebsocket_context *
289 libwebsocket_create_context(int port,
290 struct libwebsocket_protocols *protocols,
291 const char *ssl_cert_filepath,
292 const char *ssl_private_key_filepath, int gid, int uid,
293 unsigned int options);
296 libwebsocket_context_destroy(struct libwebsocket_context *this);
299 libwebsockets_fork_service_loop(struct libwebsocket_context *this);
302 libwebsocket_service(struct libwebsocket_context *this, int timeout_ms);
305 libwebsocket_service_fd(struct libwebsocket_context *this,
306 struct pollfd *pollfd);
311 * When sending with websocket protocol (LWS_WRITE_TEXT or LWS_WRITE_BINARY)
312 * the send buffer has to have LWS_SEND_BUFFER_PRE_PADDING bytes valid BEFORE
313 * buf, and LWS_SEND_BUFFER_POST_PADDING bytes valid AFTER (buf + len).
315 * This allows us to add protocol info before and after the data, and send as
316 * one packet on the network without payload copying, for maximum efficiency.
318 * So for example you need this kind of code to use libwebsocket_write with a
321 * char buf[LWS_SEND_BUFFER_PRE_PADDING + 128 + LWS_SEND_BUFFER_POST_PADDING];
323 * // fill your part of the buffer... for example here it's all zeros
324 * memset(&buf[LWS_SEND_BUFFER_PRE_PADDING], 0, 128);
326 * libwebsocket_write(wsi, &buf[LWS_SEND_BUFFER_PRE_PADDING], 128);
328 * When sending LWS_WRITE_HTTP, there is no protocol addition and you can just
329 * use the whole buffer without taking care of the above.
332 /* this is the frame nonce plus two header plus 8 length */
334 #define LWS_SEND_BUFFER_PRE_PADDING (4 + 10)
335 #define LWS_SEND_BUFFER_POST_PADDING 1
338 libwebsocket_write(struct libwebsocket *wsi, unsigned char *buf, size_t len,
339 enum libwebsocket_write_protocol protocol);
342 libwebsockets_serve_http_file(struct libwebsocket *wsi, const char *file,
343 const char *content_type);
345 /* notice - you need the pre- and post- padding allocation for buf below */
348 libwebsockets_broadcast(const struct libwebsocket_protocols *protocol,
349 unsigned char *buf, size_t len);
351 extern const struct libwebsocket_protocols *
352 libwebsockets_get_protocol(struct libwebsocket *wsi);
355 libwebsocket_callback_on_writable(struct libwebsocket *wsi);
358 libwebsocket_callback_on_writable_all_protocol(
359 const struct libwebsocket_protocols *protocol);
362 libwebsocket_get_socket_fd(struct libwebsocket *wsi);
365 libwebsocket_rx_flow_control(struct libwebsocket *wsi, int enable);
368 libwebsockets_remaining_packet_payload(struct libwebsocket *wsi);
370 extern struct libwebsocket *
371 libwebsocket_client_connect(struct libwebsocket_context *clients,
378 const char *protocol,
379 int ietf_version_or_minus_one);
382 libwebsocket_canonical_hostname(struct libwebsocket_context *this);
386 libwebsockets_get_peer_addresses(int fd, char *name, int name_len,
387 char *rip, int rip_len);
390 libwebsockets_hangup_on_client(struct libwebsocket_context *this, int fd);
393 libwebsocket_close_and_free_session(struct libwebsocket_context *this,
394 struct libwebsocket *wsi);