Callback when writeable

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_VISIBLE LWS_EXTERN int	lws_callback_vhost_protocols (struct lws *wsi, int reason, void *in, int 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 int	lws_get_socket_fd (struct lws *wsi)
LWS_VISIBLE LWS_EXTERN size_t	lws_get_peer_write_allowance (struct lws *wsi)

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.

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 <lib/libwebsockets.h>

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

Parameters

context	lws_context
protocol	Protocol whose connections will get callbacks
reason	Callback reason index

• Which: connections using this protocol on ALL VHOSTS
• When: when the individual connection becomes writeable
• What: reason

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 <lib/libwebsockets.h>

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

Parameters

vh	Vhost whose connections will get callbacks
protocol	Which protocol to match
reason	Callback reason index

• 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 <lib/libwebsockets.h>

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

Parameters

wsi	Websocket 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 <lib/libwebsockets.h>

lws_callback_on_writable_all_protocol() - 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

context	lws_context
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_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 <lib/libwebsockets.h>

lws_callback_on_writable_all_protocol_vhost() - Request a callback for all connections using the given protocol when it becomes possible to write to each socket without blocking in turn.

Parameters

vhost	Only consider connections on this lws_vhost
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_callback_vhost_protocols()

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

#include <lib/libwebsockets.h>

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

Parameters

wsi	wsi whose vhost will get callbacks
reason	Callback reason index
in	in argument to callback
len	len 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 size_t lws_get_peer_write_allowance

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

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

Parameters

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

LWS_VISIBLE LWS_EXTERN int lws_get_socket_fd

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

lws_get_socket_fd() - returns the socket file descriptor

You will not need this unless you are doing something special

Parameters

wsi	Websocket connection instance