libwebsockets
Lightweight C library for HTML5 websockets
Callback when writeable

Macros

#define LWSTXCR_US_TO_PEER   0
 
#define LWSTXCR_PEER_TO_US   1
 

Functions

LWS_VISIBLE LWS_EXTERN int lws_callback_on_writable (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN int lws_callback_on_writable_all_protocol (const struct lws_context *context, const struct lws_protocols *protocol)
 
LWS_VISIBLE LWS_EXTERN int lws_callback_on_writable_all_protocol_vhost (const struct lws_vhost *vhost, const struct lws_protocols *protocol)
 
LWS_VISIBLE LWS_EXTERN int lws_callback_all_protocol (struct lws_context *context, const struct lws_protocols *protocol, int 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_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_VISIBLE LWS_EXTERN int lws_callback_vhost_protocols (struct lws *wsi, int reason, void *in, size_t len) LWS_WARN_DEPRECATED
 
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_VISIBLE LWS_EXTERN lws_sockfd_type lws_get_socket_fd (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN lws_fileofs_t lws_get_peer_write_allowance (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN int lws_wsi_tx_credit (struct lws *wsi, char peer_to_us, int add)
 

Detailed Description

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.

Macro Definition Documentation

◆ LWSTXCR_US_TO_PEER

#define LWSTXCR_US_TO_PEER   0

#include <include/libwebsockets/lws-writeable.h>

lws_wsi_tx_credit() - get / set generic tx credit if role supports it

Parameters
wsiconnection to set / get tx credit on
peer_to_us0 = set / get us-to-peer direction, else peer-to-us
addamount 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, add is added to the selected tx credit value for the wsi.

Function Documentation

◆ lws_callback_all_protocol()

LWS_VISIBLE LWS_EXTERN int lws_callback_all_protocol ( struct lws_context *  context,
const struct lws_protocols protocol,
int  reason 
)

#include <include/libwebsockets/lws-writeable.h>

lws_callback_all_protocol() - Callback all connections using the given protocol with the given reason

Parameters
contextlws_context
protocolProtocol whose connections will get callbacks
reasonCallback 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_callback_all_protocol_vhost()

LWS_VISIBLE LWS_EXTERN int lws_callback_all_protocol_vhost ( struct lws_vhost *  vh,
const struct lws_protocols protocol,
int  reason 
)

#include <include/libwebsockets/lws-writeable.h>

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

Parameters
vhVhost whose connections will get callbacks
protocolWhich protocol to match. NULL means all.
reasonCallback reason index
  • Which: connections using this protocol on GIVEN VHOST ONLY
  • When: now
  • What: reason

◆ lws_callback_all_protocol_vhost_args()

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 
)

#include <include/libwebsockets/lws-writeable.h>

lws_callback_all_protocol_vhost_args() - Callback all connections using the given protocol with the given reason and args

Parameters
vhVhost whose connections will get callbacks
protocolWhich protocol to match. NULL means all.
reasonCallback reason index
argpCallback "in" parameter
lenCallback "len" parameter
  • Which: connections using this protocol on GIVEN VHOST ONLY
  • When: now
  • What: reason

◆ lws_callback_on_writable()

LWS_VISIBLE LWS_EXTERN int lws_callback_on_writable ( struct lws *  wsi)

#include <include/libwebsockets/lws-writeable.h>

lws_callback_on_writable() - Request a callback when this socket becomes able to be written to without blocking

Parameters
wsiWebsocket connection instance to get callback for
  • Which: only this wsi
  • When: when the individual connection becomes writeable
  • What: LWS_CALLBACK_*_WRITEABLE

◆ lws_callback_on_writable_all_protocol()

LWS_VISIBLE LWS_EXTERN int lws_callback_on_writable_all_protocol ( const struct lws_context *  context,
const struct lws_protocols protocol 
)

#include <include/libwebsockets/lws-writeable.h>

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.

Parameters
contextlws_context
protocolProtocol 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_callback_on_writable_all_protocol_vhost()

LWS_VISIBLE LWS_EXTERN int lws_callback_on_writable_all_protocol_vhost ( const struct lws_vhost *  vhost,
const struct lws_protocols protocol 
)

#include <include/libwebsockets/lws-writeable.h>

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.

Parameters
vhostOnly consider connections on this lws_vhost
protocolProtocol 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_callback_vhost_protocols()

LWS_VISIBLE LWS_EXTERN int lws_callback_vhost_protocols ( struct lws *  wsi,
int  reason,
void *  in,
size_t  len 
)

#include <include/libwebsockets/lws-writeable.h>

lws_callback_vhost_protocols() - Callback all protocols enabled on a vhost with the given reason

Parameters
wsiwsi whose vhost will get callbacks
reasonCallback reason index
inin argument to callback
lenlen 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_callback_vhost_protocols_vhost()

LWS_VISIBLE LWS_EXTERN int lws_callback_vhost_protocols_vhost ( struct lws_vhost *  vh,
int  reason,
void *  in,
size_t  len 
)

#include <include/libwebsockets/lws-writeable.h>

lws_callback_vhost_protocols_vhost() - Callback all protocols enabled on a vhost with the given reason

Parameters
vhvhost that will get callbacks
reasonCallback reason index
inin argument to callback
lenlen argument to callback
  • Which: connections using this protocol on same VHOST as wsi ONLY
  • When: now
  • What: reason

◆ lws_get_peer_write_allowance()

LWS_VISIBLE LWS_EXTERN lws_fileofs_t lws_get_peer_write_allowance ( struct lws *  wsi)

#include <include/libwebsockets/lws-writeable.h>

lws_get_peer_write_allowance() - get the amount of data writeable to peer if known

Parameters
wsiWebsocket 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_get_socket_fd()

LWS_VISIBLE LWS_EXTERN lws_sockfd_type lws_get_socket_fd ( struct lws *  wsi)

#include <include/libwebsockets/lws-writeable.h>

lws_get_socket_fd() - returns the socket file descriptor

This is needed to use sendto() on UDP raw sockets

Parameters
wsiWebsocket connection instance