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 callback-when-writeable Callback when writeable
26 *
27 * ##Callback When Writeable
28 *
29 * lws can only write data on a connection when it is able to accept more
30 * data without blocking.
31 *
32 * So a basic requirement is we should only use the lws_write() apis when the
33 * connection we want to write on says that he can accept more data.
34 *
35 * When lws cannot complete your send at the time, it will buffer the data
36 * and send it in the background, suppressing any further WRITEABLE callbacks
37 * on that connection until it completes. So it is important to write new
38 * things in a new writeable callback.
39 *
40 * These apis reflect the various ways we can indicate we would like to be
41 * called back when one or more connections is writeable.
42 */
43///@{
44
45/**
46 * lws_callback_on_writable() - Request a callback when this socket
47 * becomes able to be written to without
48 * blocking
49 *
50 * \param wsi: Websocket connection instance to get callback for
51 *
52 * - Which: only this wsi
53 * - When: when the individual connection becomes writeable
54 * - What: LWS_CALLBACK_*_WRITEABLE
55 */
56LWS_VISIBLE LWS_EXTERN int
57lws_callback_on_writable(struct lws *wsi);
58
59/**
60 * lws_callback_on_writable_all_protocol() - Request a callback for all
61 * connections using the given protocol when it
62 * becomes possible to write to each socket without
63 * blocking in turn.
64 *
65 * \param context: lws_context
66 * \param protocol: Protocol whose connections will get callbacks
67 *
68 * - Which: connections using this protocol on ANY VHOST
69 * - When: when the individual connection becomes writeable
70 * - What: LWS_CALLBACK_*_WRITEABLE
71 */
72LWS_VISIBLE LWS_EXTERN int
73lws_callback_on_writable_all_protocol(const struct lws_context *context,
74 const struct lws_protocols *protocol);
75
76/**
77 * lws_callback_on_writable_all_protocol_vhost() - Request a callback for
78 * all connections on same vhost using the given protocol
79 * when it becomes possible to write to each socket without
80 * blocking in turn.
81 *
82 * \param vhost: Only consider connections on this lws_vhost
83 * \param protocol: Protocol whose connections will get callbacks
84 *
85 * - Which: connections using this protocol on GIVEN VHOST ONLY
86 * - When: when the individual connection becomes writeable
87 * - What: LWS_CALLBACK_*_WRITEABLE
88 */
89LWS_VISIBLE LWS_EXTERN int
90lws_callback_on_writable_all_protocol_vhost(const struct lws_vhost *vhost,
91 const struct lws_protocols *protocol);
92
93/**
94 * lws_callback_all_protocol() - Callback all connections using
95 * the given protocol with the given reason
96 *
97 * \param context: lws_context
98 * \param protocol: Protocol whose connections will get callbacks
99 * \param reason: Callback reason index
100 *
101 * - Which: connections using this protocol on ALL VHOSTS
102 * - When: before returning
103 * - What: reason
104 *
105 * This isn't normally what you want... normally any update of connection-
106 * specific information can wait until a network-related callback like rx,
107 * writable, or close.
108 */
109LWS_VISIBLE LWS_EXTERN int
110lws_callback_all_protocol(struct lws_context *context,
111 const struct lws_protocols *protocol, int reason);
112
113/**
114 * lws_callback_all_protocol_vhost() - Callback all connections using
115 * the given protocol with the given reason. This is
116 * deprecated since v2.4: use lws_callback_all_protocol_vhost_args
117 *
118 * \param vh: Vhost whose connections will get callbacks
119 * \param protocol: Which protocol to match. NULL means all.
120 * \param reason: Callback reason index
121 *
122 * - Which: connections using this protocol on GIVEN VHOST ONLY
123 * - When: now
124 * - What: reason
125 */
126LWS_VISIBLE LWS_EXTERN int
127lws_callback_all_protocol_vhost(struct lws_vhost *vh,
128 const struct lws_protocols *protocol,
129 int reason)
130LWS_WARN_DEPRECATED;
131
132/**
133 * lws_callback_all_protocol_vhost_args() - Callback all connections using
134 * the given protocol with the given reason and args
135 *
136 * \param vh: Vhost whose connections will get callbacks
137 * \param protocol: Which protocol to match. NULL means all.
138 * \param reason: Callback reason index
139 * \param argp: Callback "in" parameter
140 * \param len: Callback "len" parameter
141 *
142 * - Which: connections using this protocol on GIVEN VHOST ONLY
143 * - When: now
144 * - What: reason
145 */
146LWS_VISIBLE int
147lws_callback_all_protocol_vhost_args(struct lws_vhost *vh,
148 const struct lws_protocols *protocol,
149 int reason, void *argp, size_t len);
150
151/**
152 * lws_callback_vhost_protocols() - Callback all protocols enabled on a vhost
153 * with the given reason
154 *
155 * \param wsi: wsi whose vhost will get callbacks
156 * \param reason: Callback reason index
157 * \param in: in argument to callback
158 * \param len: len argument to callback
159 *
160 * - Which: connections using this protocol on same VHOST as wsi ONLY
161 * - When: now
162 * - What: reason
163 *
164 * This is deprecated since v2.5, use lws_callback_vhost_protocols_vhost()
165 * which takes the pointer to the vhost directly without using or needing the
166 * wsi.
167 */
168LWS_VISIBLE LWS_EXTERN int
169lws_callback_vhost_protocols(struct lws *wsi, int reason, void *in, size_t len)
170LWS_WARN_DEPRECATED;
171
172/**
173 * lws_callback_vhost_protocols_vhost() - Callback all protocols enabled on a vhost
174 * with the given reason
175 *
176 * \param vh: vhost that will get callbacks
177 * \param reason: Callback reason index
178 * \param in: in argument to callback
179 * \param len: len argument to callback
180 *
181 * - Which: connections using this protocol on same VHOST as wsi ONLY
182 * - When: now
183 * - What: reason
184 */
185LWS_VISIBLE LWS_EXTERN int
186lws_callback_vhost_protocols_vhost(struct lws_vhost *vh, int reason, void *in,
187 size_t len);
188
189LWS_VISIBLE LWS_EXTERN int
190lws_callback_http_dummy(struct lws *wsi, enum lws_callback_reasons reason,
191 void *user, void *in, size_t len);
192
193/**
194 * lws_get_socket_fd() - returns the socket file descriptor
195 *
196 * This is needed to use sendto() on UDP raw sockets
197 *
198 * \param wsi: Websocket connection instance
199 */
200LWS_VISIBLE LWS_EXTERN lws_sockfd_type
201lws_get_socket_fd(struct lws *wsi);
202
203/**
204 * lws_get_peer_write_allowance() - get the amount of data writeable to peer
205 * if known
206 *
207 * \param wsi: Websocket connection instance
208 *
209 * if the protocol does not have any guidance, returns -1. Currently only
210 * http2 connections get send window information from this API. But your code
211 * should use it so it can work properly with any protocol.
212 *
213 * If nonzero return is the amount of payload data the peer or intermediary has
214 * reported it has buffer space for. That has NO relationship with the amount
215 * of buffer space your OS can accept on this connection for a write action.
216 *
217 * This number represents the maximum you could send to the peer or intermediary
218 * on this connection right now without the protocol complaining.
219 *
220 * lws manages accounting for send window updates and payload writes
221 * automatically, so this number reflects the situation at the peer or
222 * intermediary dynamically.
223 */
224LWS_VISIBLE LWS_EXTERN lws_fileofs_t
225lws_get_peer_write_allowance(struct lws *wsi);
226
227/**
228 * lws_wsi_tx_credit() - get / set generic tx credit if role supports it
229 *
230 * \param wsi: connection to set / get tx credit on
231 * \param peer_to_us: 0 = set / get us-to-peer direction, else peer-to-us
232 * \param add: amount of credit to add
233 *
234 * If the wsi does not support tx credit, returns 0.
235 *
236 * If add is zero, returns one of the wsi tx credit values for the wsi.
237 * If add is nonzero, \p add is added to the selected tx credit value
238 * for the wsi.
239 */
240#define LWSTXCR_US_TO_PEER 0
241#define LWSTXCR_PEER_TO_US 1
242
243LWS_VISIBLE LWS_EXTERN int
244lws_wsi_tx_credit(struct lws *wsi, char peer_to_us, int add);
245
246///@}
247