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 */
36enum lws_write_protocol {
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 */
47 LWS_WRITE_CONTINUATION = 2,
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() */
54 LWS_WRITE_PING = 5,
55 LWS_WRITE_PONG = 6,
56
57 /* Same as write_http but we know this write ends the transaction */
58 LWS_WRITE_HTTP_FINAL = 7,
59
60 /* HTTP2 */
61
62 LWS_WRITE_HTTP_HEADERS = 8,
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 */
68 LWS_WRITE_HTTP_HEADERS_CONTINUATION = 9,
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
87 LWS_WRITE_H2_STREAM_END = 0x80,
88 /**< Flag indicates this packet should go out with STREAM_END if h2
89 * STREAM_END is allowed on DATA or HEADERS.
90 */
91
92 LWS_WRITE_CLIENT_IGNORE_XOR_MASK = 0x80
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
100struct lws_write_passthru {
101 struct lws *wsi;
102 unsigned char *buf;
103 size_t len;
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 */
208LWS_VISIBLE LWS_EXTERN int
209lws_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 */
227static LWS_INLINE int
228lws_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
235 r = LWS_WRITE_CONTINUATION;
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 */
256LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
257lws_raw_transaction_completed(struct lws *wsi);
258
259///@}
260