lws-writeable.h (8900B)
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///@}