 |
libwebsockets
Lightweight C library for HTML5 websockets
|
|
libwebsockets
Lightweight C library for HTML5 websockets
|
#include <lws-io-ops.h>
Data Fields | |
| uint32_t | abi_version |
| int(* | want_write )(struct lws *wsi) |
| int(* | want_read )(struct lws *wsi, int on) |
| void(* | deadline )(struct lws_context *cx, int tsi, lws_usec_t us) |
| int(* | close )(struct lws *wsi, int phase) |
| int(* | path )(struct lws *wsi, int op, const union lws_sockaddr46 *peer) |
| void(* | created )(struct lws *wsi) |
| int(* | transfer )(struct lws *from, struct lws *to) |
| struct lws *(* | transport_start )(struct lws *wsi) |
| int(* | transport_connected )(struct lws *wsi) |
| void(* | transport_established )(struct lws *wsi) |
| int(* | transport_failed )(struct lws *wsi) |
| struct lws *(* | client_connect )(const struct lws_client_connect_info *i) |
| const char *(* | peer_address )(struct lws *wsi, char *buf, size_t len) |
| void *(* | tls_session )(struct lws *wsi) |
| const uint8_t *(* | tls_hs_ca_id )(struct lws *wsi) |
| int(* | tls_peer_cert_info )(struct lws *wsi, enum lws_tls_cert_info type, union lws_tls_cert_info_results *buf, size_t len) |
| int(* | tls_quic_session )(struct lws *wsi, lws_tls_quic_secret_cb cb) |
| int(* | tls_quic_handshake )(struct lws *wsi, int level, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len) |
| int(* | tls_quic_set_tp )(struct lws *wsi, const uint8_t *tp, size_t tp_len) |
| int(* | tls_quic_get_tp )(struct lws *wsi, const uint8_t **tp, size_t *tp_len) |
| int(* | tls_confirm_peer_cert )(struct lws *wsi, char *ebuf, size_t ebuf_len) |
| int(* | tls_quic_aead )(struct lws *wsi) |
| int(* | tls_quic_alert )(struct lws *wsi) |
| int(* | tls_quic_alpn )(struct lws *wsi, char *buf, size_t len) |
| int(* | tx_push )(struct lws *wsi, unsigned char *buf, size_t len) |
| void(* | tx_now )(struct lws *wsi) |
| int(* | tx_choked )(struct lws *wsi) |
| int(* | tx_file )(struct lws *wsi) |
| int(* | service_writable )(struct lws *wsi) |
| int(* | service_now )(struct lws *wsi) |
| int(* | flag_pending_rx )(struct lws *wsi) |
| void(* | wake )(struct lws *wsi) |
| int(* | http_client_read )(struct lws *wsi, char **buf, int *len) |
| int(* | finalize_startup )(struct lws_context *cx, const char *where) |
| void(* | vhost_destroy )(struct lws_vhost *vh) |
Definition at line 95 of file lws-io-ops.h.
| uint32_t lws_io_ops::abi_version |
LWS_IO_OPS_ABI_VERSION as the embedder was compiled with it: start a table with lws_io_ops_init(), or set it in the table's initializer. lws_io_ops_default's is 0, so a plain copy of it, which takes the library's members up to the embedder's size of the struct, is refused until it is stamped.
Definition at line 96 of file lws-io-ops.h.
| int(* lws_io_ops::want_write) (struct lws *wsi) |
the wsi's transport connection should be written when it can take bytes: IO will call the wsi's writeable handling then. wsi is the connection with the transport (a mux parent, not its stream). Called with the wsi's service thread lock held. 0 = ok
Definition at line 103 of file lws-io-ops.h.
| int(* lws_io_ops::want_read) (struct lws *wsi, int on) |
feed (on) or stop feeding (off) the wsi's rx from its transport. Called with the wsi's service thread lock held. 0 = ok
Definition at line 108 of file lws-io-ops.h.
| void(* lws_io_ops::deadline) (struct lws_context *cx, int tsi, lws_usec_t us) |
the earliest deadline on service thread tsi moved to us (an absolute lws_now_usecs() time): sansIO must be serviced by then. A deadline that is cancelled is not announced; a wake that finds nothing due is harmless. May be NULL: the built-in event loops ask what is due each time round instead.
Definition at line 111 of file lws-io-ops.h.
| int(* lws_io_ops::close) (struct lws *wsi, int phase) |
the wsi's transport is closing, by enum lws_io_close_phase. QUIESCE returns 1 when the wsi was still waiting for its socket (for dns, or for the fd budget): its user was never told it existed, so the close owes it the close callback; else 0. UNWATCH and RELEASE return 0. SHUTDOWN returns 1 when the tls shutdown wants more service (the close re-enters as the transport becomes readable or writable), 2 when it has wanted that too often and will not complete, 0 when the write side is shut, -1 when the shutdown failed. STAGE returns 1 when the transport can be kept until the peer finishes, so the close continues when the peer's end arrives through rx, 0 when it cannot. Called from the wsi's close path with the context and vhost locks held.
Definition at line 117 of file lws-io-ops.h.
| int(* lws_io_ops::path) (struct lws *wsi, int op, const union lws_sockaddr46 *peer) |
the datagram connection wsi's path changed, by enum lws_io_path_op. wsi is the connection, which on a server shares its listener's socket: there is nothing to aim, and COMMIT only records the peer. A wsi on a transport (lws_set_transport()) has no socket either. Called without the service thread lock. 0 = ok, nonzero when the socket could not be aimed or made: after a failed NEW_SOCKET the old socket is still in place if the new one could not be opened, else the wsi is left with none. May be NULL when no datagram connection is carried.
Definition at line 130 of file lws-io-ops.h.
| void(* lws_io_ops::created) (struct lws *wsi) |
a connection object was just made: IO sets up its half of it, as having no transport yet (no socket, no place in the poll set). Its end is the close's RELEASE, and a move to another object is transfer. May be NULL when the embedder's IO keeps nothing of its own in the object.
Definition at line 140 of file lws-io-ops.h.
| int(* lws_io_ops::transfer) (struct lws *from, struct lws *to) |
the connection sansIO knew as from goes on as to (a quic connection leaving the wsi that dialled it for its own network wsi, a kept-warm connection joining the wsi that queued on it): the socket, its place in the poll set, its event-loop watcher and its tls session move to to. Called with or without the service thread lock. 0 = ok, nonzero when to could not take them: what could be handed on is to's, and goes when to is closed.
Definition at line 146 of file lws-io-ops.h.
| struct lws *(* lws_io_ops::transport_start) (struct lws *wsi) |
the client wsi's request is ready to go (it waited for its header table and has it): start its transport, dns first. Returns wsi, or NULL when it failed and wsi was closed and freed.
Definition at line 146 of file lws-io-ops.h.
| int(* lws_io_ops::transport_connected) (struct lws *wsi) |
the socks or http CONNECT leg the client wsi's role ran over the raw transport is done, the tunnel is up: carry on with the transport (tls, if it has it, then the role hears the transport is up). 0 ok. When the connection cannot go on, the wsi is closed here: 1 when that freed it, 2 when it lives on in its close (a restart, a staged close); either way the caller touches it no more. -1, failed and the caller should close the wsi, is also understood.
Definition at line 164 of file lws-io-ops.h.
| void(* lws_io_ops::transport_established) (struct lws *wsi) |
the client wsi's role made its transport inside its own protocol (quic's handshake completed): it won any race for the connection, so drop what else was trying to be it (the tcp connects racing it, their timers, the h3 grace).
Definition at line 173 of file lws-io-ops.h.
| int(* lws_io_ops::transport_failed) (struct lws *wsi) |
such a role's transport failed before it was up: retarget the connection if possible (the next dns result, then tcp instead of udp) and return 1, else 0 and the close goes on. May be NULL when no such role is carried.
Definition at line 178 of file lws-io-ops.h.
| struct lws *(* lws_io_ops::client_connect) (const struct lws_client_connect_info *i) |
make a new client connection, as the public lws_client_connect_via_info() does, which is IO's: the http server asks for the onward leg of a proxied transaction. Returns the new wsi or NULL. May be NULL without http proxying.
Definition at line 178 of file lws-io-ops.h.
| const char *(* lws_io_ops::peer_address) (struct lws *wsi, char *buf, size_t len) |
the address of wsi's peer, as numeric text into buf of len (a mux stream's is its network connection's), returning buf. IO's is lws_get_peer_simple(). May be NULL: sansIO then says "unknown".
Definition at line 188 of file lws-io-ops.h.
| void *(* lws_io_ops::tls_session) (struct lws *wsi) |
the tls library's session object for wsi's connection, handed to the user with the ESTABLISHED callbacks, or NULL when it has none. May be NULL: no connection has a session.
Definition at line 199 of file lws-io-ops.h.
| const uint8_t *(* lws_io_ops::tls_hs_ca_id) (struct lws *wsi) |
which CA store verified the peer's certificate in wsi's server handshake (the id of the vhost's client CA it was made with), for binding an mTLS connection only to vhosts trusting that CA; NULL when nothing was recorded. May be NULL.
Definition at line 203 of file lws-io-ops.h.
| int(* lws_io_ops::tls_peer_cert_info) (struct lws *wsi, enum lws_tls_cert_info type, union lws_tls_cert_info_results *buf, size_t len) |
information of type from the peer's certificate on wsi's connection into buf, as the public lws_tls_peer_cert_info(), which is IO's. 0 ok, nonzero when there is none. May be NULL: there is never any.
Definition at line 208 of file lws-io-ops.h.
| int(* lws_io_ops::tls_quic_session) (struct lws *wsi, lws_tls_quic_secret_cb cb) |
make the quic connection wsi's tls session, set up for quic: cb is called with each traffic secret as the handshake derives it. A client's is made when its transport is up, a server's when the connection's first Initial arrives; a server vhost without tls has none to make. 0 ok, -1 it could not be made.
Definition at line 221 of file lws-io-ops.h.
| int(* lws_io_ops::tls_quic_handshake) (struct lws *wsi, int level, const uint8_t *in, size_t in_len, uint8_t *out, size_t *out_len) |
feed in, the handshake bytes of CRYPTO frames at encryption level, to wsi's session and advance the handshake; with out, what it has to send next is put there, *out_len being its size on entry and what was written on return. IO's is the public lws_tls_quic_advance_handshake(): <0 the handshake failed.
Definition at line 227 of file lws-io-ops.h.
| int(* lws_io_ops::tls_quic_set_tp) (struct lws *wsi, const uint8_t *tp, size_t tp_len) |
set the quic transport parameters extension wsi's handshake will carry. 0 ok.
Definition at line 234 of file lws-io-ops.h.
| int(* lws_io_ops::tls_quic_get_tp) (struct lws *wsi, const uint8_t **tp, size_t *tp_len) |
point *tp at the peer's quic transport parameters from the handshake, *tp_len long. 0 ok, nonzero when there are none yet.
Definition at line 237 of file lws-io-ops.h.
| int(* lws_io_ops::tls_confirm_peer_cert) (struct lws *wsi, char *ebuf, size_t ebuf_len) |
the quic connection wsi's handshake is done: is the peer's certificate acceptable, as tls over tcp decides it... on a client, the server's under its LCCSCF_ flags, on a server, the client's under the client-certificate policy of the vhost it is bound to (since ABI version 2; before, it was asked only on a client). 0 yes, else nonzero with the reason in ebuf.
Definition at line 241 of file lws-io-ops.h.
| int(* lws_io_ops::tls_quic_aead) (struct lws *wsi) |
the packet protection AEAD wsi's handshake negotiated, an enum lws_tls_quic_aead.
Definition at line 249 of file lws-io-ops.h.
| int(* lws_io_ops::tls_quic_alert) (struct lws *wsi) |
the tls alert wsi's failed handshake raised, for quic's CONNECTION_CLOSE, or 0.
Definition at line 252 of file lws-io-ops.h.
| int(* lws_io_ops::tls_quic_alpn) (struct lws *wsi, char *buf, size_t len) |
the alpn wsi's handshake selected: 1 with it copied into buf of len, 0 when there is none.
Definition at line 255 of file lws-io-ops.h.
| int(* lws_io_ops::tx_push) (struct lws *wsi, unsigned char *buf, size_t len) |
tx, in its push spelling: take these bytes for wsi's transport now. IO takes them all, keeping what the transport does not take at once and sending it first when it can, and returns len; -1 when the transport failed. buf NULL continues such a partial, returning what of it went. What sansIO produces when IO asks is the pull (the role's tx op); the push is for what the app's writeable pass hands lws_write(), framed in place in its LWS_PRE headroom so it is not copied, and the one-shot messages of the proxy legs (socks, http CONNECT) composed at a state change. Called on the wsi's service thread.
Definition at line 263 of file lws-io-ops.h.
| void(* lws_io_ops::tx_now) (struct lws *wsi) |
the datagram connection wsi has datagrams that must go now, not on its next writeable pass (a closing quic connection's CONNECTION_CLOSE): IO pulls its tx now. May be NULL when no datagram connection is carried.
Definition at line 274 of file lws-io-ops.h.
| int(* lws_io_ops::tx_choked) (struct lws *wsi) |
would the transport under wsi, the connection owning it, not take bytes now? 1 if a write would block, else 0. What sansIO holds itself (a partial send, a compression remainder, frames waiting for tx credit) it has already answered for: lws_send_pipe_choked() asks this last.
Definition at line 279 of file lws-io-ops.h.
| int(* lws_io_ops::tx_file) (struct lws *wsi) |
the server wsi is sending a file: while the transport takes more, ask the file for its next payload (lws_http_file_tx()) and write it, and when it is done and nothing of it is left buffered, complete the response. <0 the wsi should be closed, >0 the file was sent and its completion delivered, 0 more is to be sent on a later writeable pass. IO's is lws_serve_http_file_fragment(). May be NULL in a build without files (LWS_WITH_FILE_OPS) or server.
Definition at line 285 of file lws-io-ops.h.
| int(* lws_io_ops::service_writable) (struct lws *wsi) |
want_write served now rather than on the next turn of the loop: service wsi as though its transport had just said it can take bytes, so a role gets its first protocol write out in the same call that saw the transport come up. 0 ok, -1 failed, 1 the wsi was closed in the service.
Definition at line 298 of file lws-io-ops.h.
| int(* lws_io_ops::service_now) (struct lws *wsi) |
service wsi now as though its transport had rx pending, for a role that already holds bytes for it (a pipelined request that got its header table). <0 failed, 1 the wsi was closed in the service, 0 otherwise; a wsi with no transport yet gets 0.
Definition at line 304 of file lws-io-ops.h.
| int(* lws_io_ops::flag_pending_rx) (struct lws *wsi) |
mark wsi as having rx pending, so the service pass running now services it without waiting on its transport: for a role holding bytes it has not finished with (ws extension data still draining). Called from the role's service_flag_pending op with the service thread lock held. 1 the wsi is watched for rx and will be serviced, else 0.
Definition at line 309 of file lws-io-ops.h.
| void(* lws_io_ops::wake) (struct lws *wsi) |
make sure wsi's service thread comes round its loop soon, without waiting for its transport or a deadline: sansIO left work for the pass that runs at the top of each turn for connections holding buffered rx. Callable with the service thread lock held.
Definition at line 316 of file lws-io-ops.h.
| int(* lws_io_ops::http_client_read) (struct lws *wsi, char **buf, int *len) |
the app pulls its client response body: read from wsi's transport what fits the app's buffer, *buf of *len (or, with *buf NULL, IO's own), and hand it to sansIO's body rx, which delivers the payload to the app; *buf and *len are left describing what was read. 0 ok, -1 the connection failed. IO's is lws_http_client_read(). May be NULL in a build without an http client.
Definition at line 326 of file lws-io-ops.h.
| int(* lws_io_ops::finalize_startup) (struct lws_context *cx, const char *where) |
every vhost's protocols have had their first init and none asked to keep them (LWS_SERVER_OPTION_VH_SKIP_PRIV_DROP): the process may drop its initial privileges now, as the public lws_finalize_startup(), which is IO's, does. where names the caller for the log. 0 ok, nonzero failed. May be NULL: there are no privileges to drop.
Definition at line 340 of file lws-io-ops.h.
| void(* lws_io_ops::vhost_destroy) (struct lws_vhost *vh) |
the last connection bound to vh, which is being destroyed, went: finish destroying it (its protocols' destroy callbacks, its listen sockets, its tls contexts, its memory). Called with the context lock held.
Definition at line 348 of file lws-io-ops.h.
1.19.0 