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 timeout Connection timeouts 26 27 APIs related to setting connection timeouts 28 */ 29 //@{ 30 31 /* 32 * NOTE: These public enums are part of the abi. If you want to add one, 33 * add it at where specified so existing users are unaffected. 34 */ 35 enum pending_timeout { 36 NO_PENDING_TIMEOUT = 0, 37 PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE = 1, 38 PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE = 2, 39 PENDING_TIMEOUT_ESTABLISH_WITH_SERVER = 3, 40 PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE = 4, 41 PENDING_TIMEOUT_AWAITING_PING = 5, 42 PENDING_TIMEOUT_CLOSE_ACK = 6, 43 PENDING_TIMEOUT_UNUSED1 = 7, 44 PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE = 8, 45 PENDING_TIMEOUT_SSL_ACCEPT = 9, 46 PENDING_TIMEOUT_HTTP_CONTENT = 10, 47 PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND = 11, 48 PENDING_FLUSH_STORED_SEND_BEFORE_CLOSE = 12, 49 PENDING_TIMEOUT_SHUTDOWN_FLUSH = 13, 50 PENDING_TIMEOUT_CGI = 14, 51 PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE = 15, 52 PENDING_TIMEOUT_WS_PONG_CHECK_SEND_PING = 16, 53 PENDING_TIMEOUT_WS_PONG_CHECK_GET_PONG = 17, 54 PENDING_TIMEOUT_CLIENT_ISSUE_PAYLOAD = 18, 55 PENDING_TIMEOUT_AWAITING_SOCKS_GREETING_REPLY = 19, 56 PENDING_TIMEOUT_AWAITING_SOCKS_CONNECT_REPLY = 20, 57 PENDING_TIMEOUT_AWAITING_SOCKS_AUTH_REPLY = 21, 58 PENDING_TIMEOUT_KILLED_BY_SSL_INFO = 22, 59 PENDING_TIMEOUT_KILLED_BY_PARENT = 23, 60 PENDING_TIMEOUT_CLOSE_SEND = 24, 61 PENDING_TIMEOUT_HOLDING_AH = 25, 62 PENDING_TIMEOUT_UDP_IDLE = 26, 63 PENDING_TIMEOUT_CLIENT_CONN_IDLE = 27, 64 PENDING_TIMEOUT_LAGGING = 28, 65 PENDING_TIMEOUT_THREADPOOL = 29, 66 PENDING_TIMEOUT_THREADPOOL_TASK = 30, 67 PENDING_TIMEOUT_KILLED_BY_PROXY_CLIENT_CLOSE = 31, 68 PENDING_TIMEOUT_USER_OK = 32, 69 70 /****** add new things just above ---^ ******/ 71 72 PENDING_TIMEOUT_USER_REASON_BASE = 1000 73 }; 74 75 #define lws_time_in_microseconds lws_now_usecs 76 77 #define LWS_TO_KILL_ASYNC -1 78 /**< If LWS_TO_KILL_ASYNC is given as the timeout sec in a lws_set_timeout() 79 * call, then the connection is marked to be killed at the next timeout 80 * check. This is how you should force-close the wsi being serviced if 81 * you are doing it outside the callback (where you should close by nonzero 82 * return). 83 */ 84 #define LWS_TO_KILL_SYNC -2 85 /**< If LWS_TO_KILL_SYNC is given as the timeout sec in a lws_set_timeout() 86 * call, then the connection is closed before returning (which may delete 87 * the wsi). This should only be used where the wsi being closed is not the 88 * wsi currently being serviced. 89 */ 90 /** 91 * lws_set_timeout() - marks the wsi as subject to a timeout some seconds hence 92 * 93 * \param wsi: Websocket connection instance 94 * \param reason: timeout reason 95 * \param secs: how many seconds. You may set to LWS_TO_KILL_ASYNC to 96 * force the connection to timeout at the next opportunity, or 97 * LWS_TO_KILL_SYNC to close it synchronously if you know the 98 * wsi is not the one currently being serviced. 99 */ 100 LWS_VISIBLE LWS_EXTERN void 101 lws_set_timeout(struct lws *wsi, enum pending_timeout reason, int secs); 102 103 /** 104 * lws_set_timeout_us() - marks the wsi as subject to a timeout some us hence 105 * 106 * \param wsi: Websocket connection instance 107 * \param reason: timeout reason 108 * \param us: 0 removes the timeout, otherwise number of us to wait 109 * 110 * Higher-resolution version of lws_set_timeout(). Actual resolution depends 111 * on platform and load, usually ms. 112 */ 113 void 114 lws_set_timeout_us(struct lws *wsi, enum pending_timeout reason, lws_usec_t us); 115 116 #define LWS_SET_TIMER_USEC_CANCEL ((lws_usec_t)-1ll) 117 #define LWS_USEC_PER_SEC ((lws_usec_t)1000000) 118 119 /** 120 * lws_set_timer_usecs() - schedules a callback on the wsi in the future 121 * 122 * \param wsi: Websocket connection instance 123 * \param usecs: LWS_SET_TIMER_USEC_CANCEL removes any existing scheduled 124 * callback, otherwise number of microseconds in the future 125 * the callback will occur at. 126 * 127 * NOTE: event loop support for this: 128 * 129 * default poll() loop: yes 130 * libuv event loop: yes 131 * libev: not implemented (patch welcome) 132 * libevent: not implemented (patch welcome) 133 * 134 * After the deadline expires, the wsi will get a callback of type 135 * LWS_CALLBACK_TIMER and the timer is exhausted. The deadline may be 136 * continuously deferred by further calls to lws_set_timer_usecs() with a later 137 * deadline, or cancelled by lws_set_timer_usecs(wsi, -1). 138 * 139 * If the timer should repeat, lws_set_timer_usecs() must be called again from 140 * LWS_CALLBACK_TIMER. 141 * 142 * Accuracy depends on the platform and the load on the event loop or system... 143 * all that's guaranteed is the callback will come after the requested wait 144 * period. 145 */ 146 LWS_VISIBLE LWS_EXTERN void 147 lws_set_timer_usecs(struct lws *wsi, lws_usec_t usecs); 148 149 /* 150 * lws_timed_callback_vh_protocol() - calls back a protocol on a vhost after 151 * the specified delay in seconds 152 * 153 * \param vh: the vhost to call back 154 * \param protocol: the protocol to call back 155 * \param reason: callback reason 156 * \param secs: how many seconds in the future to do the callback. 157 * 158 * Callback the specified protocol with a fake wsi pointing to the specified 159 * vhost and protocol, with the specified reason, at the specified time in the 160 * future. 161 * 162 * Returns 0 if OK or 1 on OOM. 163 * 164 * In the multithreaded service case, the callback will occur in the same 165 * service thread context as the call to this api that requested it. If it is 166 * called from a non-service thread, tsi 0 will handle it. 167 */ 168 LWS_VISIBLE LWS_EXTERN int 169 lws_timed_callback_vh_protocol(struct lws_vhost *vh, 170 const struct lws_protocols *prot, 171 int reason, int secs); 172 173 /* 174 * lws_timed_callback_vh_protocol_us() - calls back a protocol on a vhost after 175 * the specified delay in us 176 * 177 * \param vh: the vhost to call back 178 * \param protocol: the protocol to call back 179 * \param reason: callback reason 180 * \param us: how many us in the future to do the callback. 181 * 182 * Callback the specified protocol with a fake wsi pointing to the specified 183 * vhost and protocol, with the specified reason, at the specified time in the 184 * future. 185 * 186 * Returns 0 if OK or 1 on OOM. 187 * 188 * In the multithreaded service case, the callback will occur in the same 189 * service thread context as the call to this api that requested it. If it is 190 * called from a non-service thread, tsi 0 will handle it. 191 */ 192 LWS_VISIBLE LWS_EXTERN int 193 lws_timed_callback_vh_protocol_us(struct lws_vhost *vh, 194 const struct lws_protocols *prot, int reason, 195 lws_usec_t us); 196 197 struct lws_sorted_usec_list; 198 199 typedef void (*sul_cb_t)(struct lws_sorted_usec_list *sul); 200 201 typedef struct lws_sorted_usec_list { 202 struct lws_dll2 list; /* simplify the code by keeping this at start */ 203 sul_cb_t cb; 204 lws_usec_t us; 205 } lws_sorted_usec_list_t; 206 207 208 /* 209 * lws_sul_schedule() - schedule a callback 210 * 211 * \param context: the lws_context 212 * \param tsi: the thread service index (usually 0) 213 * \param sul: pointer to the sul element 214 * \param cb: the scheduled callback 215 * \param us: the delay before the callback arrives, or 216 * LWS_SET_TIMER_USEC_CANCEL to cancel it. 217 * 218 * Generic callback-at-a-later time function. The callback happens on the 219 * event loop thread context. 220 * 221 * Although the api has us resultion, the actual resolution depends on the 222 * platform and is commonly 1ms. 223 * 224 * This doesn't allocate and doesn't fail. 225 * 226 * You can call it again with another us value to change the delay. 227 */ 228 LWS_VISIBLE LWS_EXTERN void 229 lws_sul_schedule(struct lws_context *context, int tsi, 230 lws_sorted_usec_list_t *sul, sul_cb_t cb, lws_usec_t us); 231 232 /* 233 * lws_validity_confirmed() - reset the validity timer for a network connection 234 * 235 * \param wsi: the connection that saw traffic proving the connection valid 236 * 237 * Network connections are subject to intervals defined by the context, the 238 * vhost if server connections, or the client connect info if a client 239 * connection. If the connection goes longer than the specified time since 240 * last observing traffic that can only happen if traffic is passing in both 241 * directions, then lws will try to create a PING transaction on the network 242 * connection. 243 * 244 * If the connection reaches the specified `.secs_since_valid_hangup` time 245 * still without any proof of validity, the connection will be closed. 246 * 247 * If the PONG comes, or user code observes traffic that satisfies the proof 248 * that both directions are passing traffic to the peer and calls this api, 249 * the connection validity timer is reset and the scheme repeats. 250 */ 251 LWS_VISIBLE LWS_EXTERN void 252 lws_validity_confirmed(struct lws *wsi); 253 254 /* 255 * These are not normally needed, they're exported for the case there's code 256 * using lws_sul for which lws is an optional link dependency. 257 */ 258 259 LWS_VISIBLE LWS_EXTERN int 260 __lws_sul_insert(lws_dll2_owner_t *own, lws_sorted_usec_list_t *sul, 261 lws_usec_t us); 262 263 LWS_VISIBLE LWS_EXTERN lws_usec_t 264 __lws_sul_service_ripe(lws_dll2_owner_t *own, lws_usec_t usnow); 265 266 ///@} 267