libwebsockets
Lightweight C library for HTML5 websockets
lws-write.h
Go to the documentation of this file.
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  */
24 
25 /*! \defgroup sending-data Sending data
26 
27  APIs related to writing data on a connection
28 */
29 //@{
30 #define LWS_WRITE_RAW LWS_WRITE_HTTP
31 
32 /*
33  * NOTE: These public enums are part of the abi. If you want to add one,
34  * add it at where specified so existing users are unaffected.
35  */
37  LWS_WRITE_TEXT = 0,
38  /**< Send a ws TEXT message,the pointer must have LWS_PRE valid
39  * memory behind it.
40  *
41  * The receiver expects only valid utf-8 in the payload */
42  LWS_WRITE_BINARY = 1,
43  /**< Send a ws BINARY message, the pointer must have LWS_PRE valid
44  * memory behind it.
45  *
46  * Any sequence of bytes is valid */
48  /**< Continue a previous ws message, the pointer must have LWS_PRE valid
49  * memory behind it */
50  LWS_WRITE_HTTP = 3,
51  /**< Send HTTP content */
52 
53  /* LWS_WRITE_CLOSE is handled by lws_close_reason() */
56 
57  /* Same as write_http but we know this write ends the transaction */
59 
60  /* HTTP2 */
61 
63  /**< Send http headers (http2 encodes this payload and LWS_WRITE_HTTP
64  * payload differently, http 1.x links also handle this correctly. so
65  * to be compatible with both in the future,header response part should
66  * be sent using this regardless of http version expected)
67  */
69  /**< Continuation of http/2 headers
70  */
71 
72  /****** add new things just above ---^ ******/
73 
74  /* flags */
75 
76  LWS_WRITE_BUFLIST = 0x20,
77  /**< Don't actually write it... stick it on the output buflist and
78  * write it as soon as possible. Useful if you learn you have to
79  * write something, have the data to write to hand but the timing is
80  * unrelated as to whether the connection is writable or not, and were
81  * otherwise going to have to allocate a temp buffer and write it
82  * later anyway */
83 
84  LWS_WRITE_NO_FIN = 0x40,
85  /**< This part of the message is not the end of the message */
86 
88  /**< Flag indicates this packet should go out with STREAM_END if h2
89  * STREAM_END is allowed on DATA or HEADERS.
90  */
91 
93  /**< client packet payload goes out on wire unmunged
94  * only useful for security tests since normal servers cannot
95  * decode the content if used */
96 };
97 
98 /* used with LWS_CALLBACK_CHILD_WRITE_VIA_PARENT */
99 
101  struct lws *wsi;
102  unsigned char *buf;
104  enum lws_write_protocol wp;
105 };
106 
107 
108 /**
109  * lws_write() - Apply protocol then write data to client
110  *
111  * \param wsi: Websocket instance (available from user callback)
112  * \param buf: The data to send. For data being sent on a websocket
113  * connection (ie, not default http), this buffer MUST have
114  * LWS_PRE bytes valid BEFORE the pointer.
115  * This is so the protocol header data can be added in-situ.
116  * \param len: Count of the data bytes in the payload starting from buf
117  * \param protocol: Use LWS_WRITE_HTTP to reply to an http connection, and one
118  * of LWS_WRITE_BINARY or LWS_WRITE_TEXT to send appropriate
119  * data on a websockets connection. Remember to allow the extra
120  * bytes before and after buf if LWS_WRITE_BINARY or LWS_WRITE_TEXT
121  * are used.
122  *
123  * This function provides the way to issue data back to the client, for any
124  * role (h1, h2, ws, raw, etc). It can only be called from the WRITEABLE
125  * callback.
126  *
127  * IMPORTANT NOTICE!
128  *
129  * When sending with ws protocol
130  *
131  * LWS_WRITE_TEXT,
132  * LWS_WRITE_BINARY,
133  * LWS_WRITE_CONTINUATION,
134  * LWS_WRITE_PING,
135  * LWS_WRITE_PONG,
136  *
137  * or sending on http/2... the send buffer has to have LWS_PRE bytes valid
138  * BEFORE the buffer pointer you pass to lws_write(). Since you'll probably
139  * want to use http/2 before too long, it's wise to just always do this with
140  * lws_write buffers... LWS_PRE is typically 16 bytes it's not going to hurt
141  * usually.
142  *
143  * start of alloc ptr passed to lws_write end of allocation
144  * | | |
145  * v <-- LWS_PRE bytes --> v v
146  * [---------------- allocated memory ---------------]
147  * (for lws use) [====== user buffer ======]
148  *
149  * This allows us to add protocol info before the data, and send as one packet
150  * on the network without payload copying, for maximum efficiency.
151  *
152  * So for example you need this kind of code to use lws_write with a
153  * 128-byte payload
154  *
155  * char buf[LWS_PRE + 128];
156  *
157  * // fill your part of the buffer... for example here it's all zeros
158  * memset(&buf[LWS_PRE], 0, 128);
159  *
160  * if (lws_write(wsi, &buf[LWS_PRE], 128, LWS_WRITE_TEXT) < 128) {
161  * ... the connection is dead ...
162  * return -1;
163  * }
164  *
165  * LWS_PRE is currently 16, which covers ws and h2 frame headers, and is
166  * compatible with 32 and 64-bit alignment requirements.
167  *
168  * (LWS_SEND_BUFFER_POST_PADDING is deprecated, it's now 0 and can be left off.)
169  *
170  * Return may be -1 is the write failed in a way indicating that the connection
171  * has ended already, in which case you can close your side, or a positive
172  * number that is at least the number of bytes requested to send (under some
173  * encapsulation scenarios, it can indicate more than you asked was sent).
174  *
175  * The recommended test of the return is less than what you asked indicates
176  * the connection has failed.
177  *
178  * Truncated Writes
179  * ================
180  *
181  * The OS may not accept everything you asked to write on the connection.
182  *
183  * Posix defines POLLOUT indication from poll() to show that the connection
184  * will accept more write data, but it doesn't specifiy how much. It may just
185  * accept one byte of whatever you wanted to send.
186  *
187  * LWS will buffer the remainder automatically, and send it out autonomously.
188  *
189  * During that time, WRITABLE callbacks to user code will be suppressed and
190  * instead used internally. After it completes, it will send an extra WRITEABLE
191  * callback to the user code, in case any request was missed. So it is possible
192  * to receive unasked-for WRITEABLE callbacks, the user code should have enough
193  * state to know if it wants to write anything and just return if not.
194  *
195  * This is to handle corner cases where unexpectedly the OS refuses what we
196  * usually expect it to accept. It's not recommended as the way to randomly
197  * send huge payloads, since it is being copied on to heap and is inefficient.
198  *
199  * Huge payloads should instead be sent in fragments that are around 2 x mtu,
200  * which is almost always directly accepted by the OS. To simplify this for
201  * ws fragments, there is a helper lws_write_ws_flags() below that simplifies
202  * selecting the correct flags to give lws_write() for each fragment.
203  *
204  * In the case of RFC8441 ws-over-h2, you cannot send ws fragments larger than
205  * the max h2 frame size, typically 16KB, but should further restrict it to
206  * the same ~2 x mtu limit mentioned above.
207  */
208 LWS_VISIBLE LWS_EXTERN int
209 lws_write(struct lws *wsi, unsigned char *buf, size_t len,
210  enum lws_write_protocol protocol);
211 
212 /* helper for case where buffer may be const */
213 #define lws_write_http(wsi, buf, len)
214  lws_write(wsi, (unsigned char *)(buf), len, LWS_WRITE_HTTP)
215 
216 /**
217  * lws_write_ws_flags() - Helper for multi-frame ws message flags
218  *
219  * \param initial: the lws_write flag to use for the start fragment, eg,
220  * LWS_WRITE_TEXT
221  * \param is_start: nonzero if this is the first fragment of the message
222  * \param is_end: nonzero if this is the last fragment of the message
223  *
224  * Returns the correct LWS_WRITE_ flag to use for each fragment of a message
225  * in turn.
226  */
227 static LWS_INLINE int
228 lws_write_ws_flags(int initial, int is_start, int is_end)
229 {
230  int r;
231 
232  if (is_start)
233  r = initial;
234  else
236 
237  if (!is_end)
238  r |= LWS_WRITE_NO_FIN;
239 
240  return r;
241 }
242 
243 /**
244  * lws_raw_transaction_completed() - Helper for flushing before close
245  *
246  * \param wsi: the struct lws to operate on
247  *
248  * Returns -1 if the wsi can close now. However if there is buffered, unsent
249  * data, the wsi is marked as to be closed when the output buffer data is
250  * drained, and it returns 0.
251  *
252  * For raw cases where the transaction completed without failure,
253  * `return lws_raw_transaction_completed(wsi)` should better be used than
254  * return -1.
255  */
256 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
257 lws_raw_transaction_completed(struct lws *wsi);
258 
259 ///@}