247 lines
8.7 KiB
C
247 lines
8.7 KiB
C
|
/*
|
||
|
|
* libwebsockets - small server side websockets and web server implementation
|
||
|
|
*
|
||
|
|
* Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
|
||
|
|
*
|
||
|
|
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
||
|
|
* of this software and associated documentation files (the "Software"), to
|
||
|
|
* deal in the Software without restriction, including without limitation the
|
||
|
|
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
||
|
|
* sell copies of the Software, and to permit persons to whom the Software is
|
||
|
|
* furnished to do so, subject to the following conditions:
|
||
|
|
*
|
||
|
|
* The above copyright notice and this permission notice shall be included in
|
||
|
|
* all copies or substantial portions of the Software.
|
||
|
|
*
|
||
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||
|
|
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||
|
|
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||
|
|
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||
|
|
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
|
||
|
|
* IN THE SOFTWARE.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/** \defgroup callback-when-writeable Callback when writeable
|
||
|
|
*
|
||
|
|
* ##Callback When Writeable
|
||
|
|
*
|
||
|
|
* lws can only write data on a connection when it is able to accept more
|
||
|
|
* data without blocking.
|
||
|
|
*
|
||
|
|
* So a basic requirement is we should only use the lws_write() apis when the
|
||
|
|
* connection we want to write on says that he can accept more data.
|
||
|
|
*
|
||
|
|
* When lws cannot complete your send at the time, it will buffer the data
|
||
|
|
* and send it in the background, suppressing any further WRITEABLE callbacks
|
||
|
|
* on that connection until it completes. So it is important to write new
|
||
|
|
* things in a new writeable callback.
|
||
|
|
*
|
||
|
|
* These apis reflect the various ways we can indicate we would like to be
|
||
|
|
* called back when one or more connections is writeable.
|
||
|
|
*/
|
||
|
|
///@{
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_callback_on_writable() - Request a callback when this socket
|
||
|
|
* becomes able to be written to without
|
||
|
|
* blocking
|
||
|
|
*
|
||
|
|
* \param wsi: Websocket connection instance to get callback for
|
||
|
|
*
|
||
|
|
* - Which: only this wsi
|
||
|
|
* - When: when the individual connection becomes writeable
|
||
|
|
* - What: LWS_CALLBACK_*_WRITEABLE
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE LWS_EXTERN int
|
||
|
|
lws_callback_on_writable(struct lws *wsi);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_callback_on_writable_all_protocol() - Request a callback for all
|
||
|
|
* connections using the given protocol when it
|
||
|
|
* becomes possible to write to each socket without
|
||
|
|
* blocking in turn.
|
||
|
|
*
|
||
|
|
* \param context: lws_context
|
||
|
|
* \param protocol: Protocol whose connections will get callbacks
|
||
|
|
*
|
||
|
|
* - Which: connections using this protocol on ANY VHOST
|
||
|
|
* - When: when the individual connection becomes writeable
|
||
|
|
* - What: LWS_CALLBACK_*_WRITEABLE
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE LWS_EXTERN int
|
||
|
|
lws_callback_on_writable_all_protocol(const struct lws_context *context,
|
||
|
|
const struct lws_protocols *protocol);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_callback_on_writable_all_protocol_vhost() - Request a callback for
|
||
|
|
* all connections on same vhost using the given protocol
|
||
|
|
* when it becomes possible to write to each socket without
|
||
|
|
* blocking in turn.
|
||
|
|
*
|
||
|
|
* \param vhost: Only consider connections on this lws_vhost
|
||
|
|
* \param protocol: Protocol whose connections will get callbacks
|
||
|
|
*
|
||
|
|
* - Which: connections using this protocol on GIVEN VHOST ONLY
|
||
|
|
* - When: when the individual connection becomes writeable
|
||
|
|
* - What: LWS_CALLBACK_*_WRITEABLE
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE LWS_EXTERN int
|
||
|
|
lws_callback_on_writable_all_protocol_vhost(const struct lws_vhost *vhost,
|
||
|
|
const struct lws_protocols *protocol);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_callback_all_protocol() - Callback all connections using
|
||
|
|
* the given protocol with the given reason
|
||
|
|
*
|
||
|
|
* \param context: lws_context
|
||
|
|
* \param protocol: Protocol whose connections will get callbacks
|
||
|
|
* \param reason: Callback reason index
|
||
|
|
*
|
||
|
|
* - Which: connections using this protocol on ALL VHOSTS
|
||
|
|
* - When: before returning
|
||
|
|
* - What: reason
|
||
|
|
*
|
||
|
|
* This isn't normally what you want... normally any update of connection-
|
||
|
|
* specific information can wait until a network-related callback like rx,
|
||
|
|
* writable, or close.
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE LWS_EXTERN int
|
||
|
|
lws_callback_all_protocol(struct lws_context *context,
|
||
|
|
const struct lws_protocols *protocol, int reason);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_callback_all_protocol_vhost() - Callback all connections using
|
||
|
|
* the given protocol with the given reason. This is
|
||
|
|
* deprecated since v2.4: use lws_callback_all_protocol_vhost_args
|
||
|
|
*
|
||
|
|
* \param vh: Vhost whose connections will get callbacks
|
||
|
|
* \param protocol: Which protocol to match. NULL means all.
|
||
|
|
* \param reason: Callback reason index
|
||
|
|
*
|
||
|
|
* - Which: connections using this protocol on GIVEN VHOST ONLY
|
||
|
|
* - When: now
|
||
|
|
* - What: reason
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE LWS_EXTERN int
|
||
|
|
lws_callback_all_protocol_vhost(struct lws_vhost *vh,
|
||
|
|
const struct lws_protocols *protocol,
|
||
|
|
int reason)
|
||
|
|
LWS_WARN_DEPRECATED;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_callback_all_protocol_vhost_args() - Callback all connections using
|
||
|
|
* the given protocol with the given reason and args
|
||
|
|
*
|
||
|
|
* \param vh: Vhost whose connections will get callbacks
|
||
|
|
* \param protocol: Which protocol to match. NULL means all.
|
||
|
|
* \param reason: Callback reason index
|
||
|
|
* \param argp: Callback "in" parameter
|
||
|
|
* \param len: Callback "len" parameter
|
||
|
|
*
|
||
|
|
* - Which: connections using this protocol on GIVEN VHOST ONLY
|
||
|
|
* - When: now
|
||
|
|
* - What: reason
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE int
|
||
|
|
lws_callback_all_protocol_vhost_args(struct lws_vhost *vh,
|
||
|
|
const struct lws_protocols *protocol,
|
||
|
|
int reason, void *argp, size_t len);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_callback_vhost_protocols() - Callback all protocols enabled on a vhost
|
||
|
|
* with the given reason
|
||
|
|
*
|
||
|
|
* \param wsi: wsi whose vhost will get callbacks
|
||
|
|
* \param reason: Callback reason index
|
||
|
|
* \param in: in argument to callback
|
||
|
|
* \param len: len argument to callback
|
||
|
|
*
|
||
|
|
* - Which: connections using this protocol on same VHOST as wsi ONLY
|
||
|
|
* - When: now
|
||
|
|
* - What: reason
|
||
|
|
*
|
||
|
|
* This is deprecated since v2.5, use lws_callback_vhost_protocols_vhost()
|
||
|
|
* which takes the pointer to the vhost directly without using or needing the
|
||
|
|
* wsi.
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE LWS_EXTERN int
|
||
|
|
lws_callback_vhost_protocols(struct lws *wsi, int reason, void *in, size_t len)
|
||
|
|
LWS_WARN_DEPRECATED;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_callback_vhost_protocols_vhost() - Callback all protocols enabled on a vhost
|
||
|
|
* with the given reason
|
||
|
|
*
|
||
|
|
* \param vh: vhost that will get callbacks
|
||
|
|
* \param reason: Callback reason index
|
||
|
|
* \param in: in argument to callback
|
||
|
|
* \param len: len argument to callback
|
||
|
|
*
|
||
|
|
* - Which: connections using this protocol on same VHOST as wsi ONLY
|
||
|
|
* - When: now
|
||
|
|
* - What: reason
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE LWS_EXTERN int
|
||
|
|
lws_callback_vhost_protocols_vhost(struct lws_vhost *vh, int reason, void *in,
|
||
|
|
size_t len);
|
||
|
|
|
||
|
|
LWS_VISIBLE LWS_EXTERN int
|
||
|
|
lws_callback_http_dummy(struct lws *wsi, enum lws_callback_reasons reason,
|
||
|
|
void *user, void *in, size_t len);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_get_socket_fd() - returns the socket file descriptor
|
||
|
|
*
|
||
|
|
* This is needed to use sendto() on UDP raw sockets
|
||
|
|
*
|
||
|
|
* \param wsi: Websocket connection instance
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE LWS_EXTERN lws_sockfd_type
|
||
|
|
lws_get_socket_fd(struct lws *wsi);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_get_peer_write_allowance() - get the amount of data writeable to peer
|
||
|
|
* if known
|
||
|
|
*
|
||
|
|
* \param wsi: Websocket connection instance
|
||
|
|
*
|
||
|
|
* if the protocol does not have any guidance, returns -1. Currently only
|
||
|
|
* http2 connections get send window information from this API. But your code
|
||
|
|
* should use it so it can work properly with any protocol.
|
||
|
|
*
|
||
|
|
* If nonzero return is the amount of payload data the peer or intermediary has
|
||
|
|
* reported it has buffer space for. That has NO relationship with the amount
|
||
|
|
* of buffer space your OS can accept on this connection for a write action.
|
||
|
|
*
|
||
|
|
* This number represents the maximum you could send to the peer or intermediary
|
||
|
|
* on this connection right now without the protocol complaining.
|
||
|
|
*
|
||
|
|
* lws manages accounting for send window updates and payload writes
|
||
|
|
* automatically, so this number reflects the situation at the peer or
|
||
|
|
* intermediary dynamically.
|
||
|
|
*/
|
||
|
|
LWS_VISIBLE LWS_EXTERN lws_fileofs_t
|
||
|
|
lws_get_peer_write_allowance(struct lws *wsi);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* lws_wsi_tx_credit() - get / set generic tx credit if role supports it
|
||
|
|
*
|
||
|
|
* \param wsi: connection to set / get tx credit on
|
||
|
|
* \param peer_to_us: 0 = set / get us-to-peer direction, else peer-to-us
|
||
|
|
* \param add: amount of credit to add
|
||
|
|
*
|
||
|
|
* If the wsi does not support tx credit, returns 0.
|
||
|
|
*
|
||
|
|
* If add is zero, returns one of the wsi tx credit values for the wsi.
|
||
|
|
* If add is nonzero, \p add is added to the selected tx credit value
|
||
|
|
* for the wsi.
|
||
|
|
*/
|
||
|
|
#define LWSTXCR_US_TO_PEER 0
|
||
|
|
#define LWSTXCR_PEER_TO_US 1
|
||
|
|
|
||
|
|
LWS_VISIBLE LWS_EXTERN int
|
||
|
|
lws_wsi_tx_credit(struct lws *wsi, char peer_to_us, int add);
|
||
|
|
|
||
|
|
///@}
|