Secure Streams

Data Structures
struct	lws_ss_info

Macros
#define	LWS_SS_MTU   1540
#define	LWS_SS_USER_TYPEDEF
#define	LWS_SS_INFO(_streamtype, _type)
#define	lws_ss_from_user(_u)   (_u)->ss
#define	lws_ss_opaque_from_user(_u)   (_u)->opaque_data
#define	lws_ss_cx_from_user(_u)   lws_ss_get_context((_u)->ss)
#define	lws_context_info_defaults(_x, _y)   _lws_context_info_defaults(_x, _y)
#define	LWSSS_TIMEOUT_FROM_POLICY   0

Typedefs
typedef uint32_t	lws_ss_tx_ordinal_t
typedef enum lws_ss_state_return	lws_ss_state_return_t
typedef lws_ss_state_return_t(*	lws_sscb_rx) (void *userobj, const uint8_t *buf, size_t len, int flags)
typedef lws_ss_state_return_t(*	lws_sscb_tx) (void *userobj, lws_ss_tx_ordinal_t ord, uint8_t *buf, size_t *len, int *flags)
typedef lws_ss_state_return_t(*	lws_sscb_state) (void *userobj, void *h_src, lws_ss_constate_t state, lws_ss_tx_ordinal_t ack)
typedef struct lws_ss_info	lws_ss_info_t
typedef void(*	lws_sssfec_cb) (struct lws_ss_handle *h, void *arg)

Enumerations
enum	lws_ss_constate_t {   LWSSSCS_CREATING = 1 , LWSSSCS_DISCONNECTED , LWSSSCS_UNREACHABLE , LWSSSCS_AUTH_FAILED ,   LWSSSCS_CONNECTED , LWSSSCS_CONNECTING , LWSSSCS_DESTROYING , LWSSSCS_POLL ,   LWSSSCS_ALL_RETRIES_FAILED , LWSSSCS_QOS_ACK_REMOTE , LWSSSCS_QOS_NACK_REMOTE , LWSSSCS_QOS_ACK_LOCAL ,   LWSSSCS_QOS_NACK_LOCAL , LWSSSCS_TIMEOUT , LWSSSCS_SERVER_TXN , LWSSSCS_SERVER_UPGRADE ,   LWSSSCS_EVENT_WAIT_CANCELLED , LWSSSCS_UPSTREAM_LINK_RETRY , LWSSSCS_SINK_JOIN , LWSSSCS_SINK_PART ,   LWSSSCS_USER_BASE = 1000 }
enum	{   LWSSS_FLAG_SOM = (1 << 0) , LWSSS_FLAG_EOM = (1 << 1) , LWSSS_FLAG_POLL = (1 << 2) , LWSSS_FLAG_RELATED_START = (1 << 3) ,   LWSSS_FLAG_RELATED_END = (1 << 4) , LWSSS_FLAG_RIDESHARE = (1 << 5) , LWSSS_FLAG_PERF_JSON = (1 << 6) }
enum	lws_ss_state_return { LWSSSSRET_TX_DONT_SEND = 1 , LWSSSSRET_OK = 0 , LWSSSSRET_DISCONNECT_ME = -1 , LWSSSSRET_DESTROY_ME = -2 }
enum	{   LWSSSINFLAGS_REGISTER_SINK = (1 << 0) , LWSSSINFLAGS_PROXIED = (1 << 1) , LWSSSINFLAGS_SERVER = (1 << 2) , LWSSSINFLAGS_ACCEPTED = (1 << 3) ,   LWSSSINFLAGS_ACCEPTED_SINK = (1 << 4) }

Functions
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_ss_create (struct lws_context *context, int tsi, const lws_ss_info_t *ssi, void *opaque_user_data, struct lws_ss_handle **ppss, void *reserved, const char **ppayload_fmt)
LWS_VISIBLE LWS_EXTERN void	lws_ss_destroy (struct lws_ss_handle **ppss)
LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT	lws_ss_request_tx (struct lws_ss_handle *pss)
LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT	lws_ss_request_tx_len (struct lws_ss_handle *pss, unsigned long len)
LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT	lws_ss_client_connect (struct lws_ss_handle *h)
LWS_VISIBLE LWS_EXTERN int	lws_ss_proxy_create (struct lws_context *context, const char *bind, int port)
LWS_VISIBLE LWS_EXTERN const char *	lws_ss_state_name (int state)
LWS_VISIBLE LWS_EXTERN struct lws_context *	lws_ss_get_context (struct lws_ss_handle *h)
LWS_VISIBLE LWS_EXTERN struct lws_vhost *	lws_ss_get_vhost (struct lws_ss_handle *h)
LWS_VISIBLE LWS_EXTERN void	lws_ss_start_timeout (struct lws_ss_handle *h, unsigned int timeout_ms)
LWS_VISIBLE LWS_EXTERN void	lws_ss_cancel_timeout (struct lws_ss_handle *h)
LWS_VISIBLE LWS_EXTERN void *	lws_ss_to_user_object (struct lws_ss_handle *h)
LWS_VISIBLE LWS_EXTERN const char *	lws_ss_rideshare (struct lws_ss_handle *h)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_ss_set_metadata (struct lws_ss_handle *h, const char *name, const void *value, size_t len)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_ss_alloc_set_metadata (struct lws_ss_handle *h, const char *name, const void *value, size_t len)
LWS_VISIBLE LWS_EXTERN int	lws_ss_get_metadata (struct lws_ss_handle *h, const char *name, const void **value, size_t *len)
LWS_VISIBLE LWS_EXTERN void	lws_ss_server_ack (struct lws_ss_handle *h, int nack)
LWS_VISIBLE LWS_EXTERN void	lws_ss_server_foreach_client (struct lws_ss_handle *h, lws_sssfec_cb cb, void *arg)
LWS_VISIBLE LWS_EXTERN void	lws_ss_change_handlers (struct lws_ss_handle *h, lws_sscb_rx rx, lws_sscb_tx tx, lws_sscb_state state)
LWS_VISIBLE LWS_EXTERN int	lws_ss_add_peer_tx_credit (struct lws_ss_handle *h, int32_t add)
LWS_VISIBLE LWS_EXTERN int	lws_ss_get_est_peer_tx_credit (struct lws_ss_handle *h)
LWS_VISIBLE LWS_EXTERN const char *	lws_ss_tag (struct lws_ss_handle *h)
LWS_VISIBLE LWS_EXTERN int	lws_ss_adopt_raw (struct lws_ss_handle *ss, lws_sock_file_fd_type fd)

Detailed Description

Secure Streams

Secure Streams related apis

---

Data Structure Documentation

lws_ss_info

struct lws_ss_info

Definition at line 197 of file lws-secure-streams.h.

Collaboration diagram for lws_ss_info:

Data Fields
const char *	streamtype	type of stream we want to create
size_t	user_alloc	size of user allocation
size_t	handle_offset	offset of handle stg in user_alloc type, set to offsetof(mytype, my_handle_member)
size_t	opaque_user_data_offset	offset of opaque user data ptr in user_alloc type, set to offsetof(mytype, opaque_ud_member)
lws_sscb_rx	rx	callback with rx payload for this stream
lws_sscb_tx	tx	callback to send payload on this stream... 0 = send as set in len and flags, 1 = do not send anything (ie, not even 0 len frame)
lws_sscb_state	state	advisory cb about state of stream and QoS status if applicable... h_src is only used with sinks and LWSSSCS_SINK_JOIN/_PART events. Return nonzero to indicate you want to destroy the stream.
int	manual_initial_tx_credit	0 = manage any tx credit automatically, nonzero explicitly sets the peer stream to have the given amount of tx credit, if the protocol can support it. In the special case of _lws_smd streamtype, this is used to indicate the connection's rx class mask.
uint32_t	client_pid	used in proxy / serialization case to hold the client pid this proxied connection is to be tagged with
uint8_t	flags
uint8_t	sss_protocol_version	used in proxy / serialization case to hold the SS serialization protocol level to use with this peer... clients automatically request the most recent version they were built with (LWS_SSS_CLIENT_PROTOCOL_VERSION) and the proxy stores the requested version in here

Macro Definition Documentation

LWS_SS_MTU

#define LWS_SS_MTU   1540

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 60 of file lws-secure-streams.h.

LWS_SS_USER_TYPEDEF

#define LWS_SS_USER_TYPEDEF

#include <include/libwebsockets/lws-secure-streams.h>

Value:

        typedef struct { \
                struct lws_ss_handle    *ss; \
                void                    *opaque_data;

Definition at line 254 of file lws-secure-streams.h.

LWS_SS_INFO

#define LWS_SS_INFO	(		_streamtype,
			_type
	)

#include <include/libwebsockets/lws-secure-streams.h>

Value:

        const lws_ss_info_t ssi_##_type = { \
                .handle_offset = offsetof(_type, ss), \
                .opaque_user_data_offset = offsetof(_type, opaque_data), \
                .user_alloc = sizeof(_type), \
                .streamtype = _streamtype,

Definition at line 259 of file lws-secure-streams.h.

lws_ss_from_user

#define lws_ss_from_user

(

_u

)

(_u)->ss

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 266 of file lws-secure-streams.h.

lws_ss_opaque_from_user

#define lws_ss_opaque_from_user

(

_u

)

(_u)->opaque_data

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 267 of file lws-secure-streams.h.

lws_ss_cx_from_user

#define lws_ss_cx_from_user

(

_u

)

lws_ss_get_context((_u)->ss)

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 268 of file lws-secure-streams.h.

lws_context_info_defaults

#define lws_context_info_defaults	(		_x,
			_y
	)		_lws_context_info_defaults(_x, _y)

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 273 of file lws-secure-streams.h.

LWSSS_TIMEOUT_FROM_POLICY

#define LWSSS_TIMEOUT_FROM_POLICY   0

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 424 of file lws-secure-streams.h.

Typedef Documentation

lws_ss_tx_ordinal_t

typedef uint32_t lws_ss_tx_ordinal_t

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 63 of file lws-secure-streams.h.

lws_ss_state_return_t

typedef enum lws_ss_state_return lws_ss_state_return_t

#include <include/libwebsockets/lws-secure-streams.h>

lws_sscb_rx

typedef lws_ss_state_return_t(* lws_sscb_rx) (void *userobj, const uint8_t *buf, size_t len, int flags)

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 180 of file lws-secure-streams.h.

lws_sscb_tx

typedef lws_ss_state_return_t(* lws_sscb_tx) (void *userobj, lws_ss_tx_ordinal_t ord, uint8_t *buf, size_t *len, int *flags)

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 182 of file lws-secure-streams.h.

lws_sscb_state

typedef lws_ss_state_return_t(* lws_sscb_state) (void *userobj, void *h_src, lws_ss_constate_t state, lws_ss_tx_ordinal_t ack)

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 186 of file lws-secure-streams.h.

lws_ss_info_t

typedef struct lws_ss_info lws_ss_info_t

#include <include/libwebsockets/lws-secure-streams.h>

lws_sssfec_cb

typedef void(* lws_sssfec_cb) (struct lws_ss_handle *h, void *arg)

#include <include/libwebsockets/lws-secure-streams.h>

Definition at line 581 of file lws-secure-streams.h.

Enumeration Type Documentation

lws_ss_constate_t

enum lws_ss_constate_t

#include <include/libwebsockets/lws-secure-streams.h>

Enumerator
LWSSSCS_CREATING
LWSSSCS_DISCONNECTED
LWSSSCS_UNREACHABLE
LWSSSCS_AUTH_FAILED
LWSSSCS_CONNECTED
LWSSSCS_CONNECTING
LWSSSCS_DESTROYING
LWSSSCS_POLL
LWSSSCS_ALL_RETRIES_FAILED
LWSSSCS_QOS_ACK_REMOTE
LWSSSCS_QOS_NACK_REMOTE
LWSSSCS_QOS_ACK_LOCAL
LWSSSCS_QOS_NACK_LOCAL
LWSSSCS_TIMEOUT
LWSSSCS_SERVER_TXN
LWSSSCS_SERVER_UPGRADE
LWSSSCS_EVENT_WAIT_CANCELLED
LWSSSCS_UPSTREAM_LINK_RETRY
LWSSSCS_SINK_JOIN
LWSSSCS_SINK_PART
LWSSSCS_USER_BASE

Definition at line 76 of file lws-secure-streams.h.

             {
        /* zero means unset */
        LWSSSCS_CREATING                = 1,
        LWSSSCS_DISCONNECTED,
        LWSSSCS_UNREACHABLE,            /* oridinal arg = 1 = caused by dns
                                         * server reachability failure */
        LWSSSCS_AUTH_FAILED,
        LWSSSCS_CONNECTED,
        LWSSSCS_CONNECTING,
        LWSSSCS_DESTROYING,
        LWSSSCS_POLL,
        LWSSSCS_ALL_RETRIES_FAILED,     /* all retries in bo policy failed */
        LWSSSCS_QOS_ACK_REMOTE,         /* remote peer received and acked tx */
        LWSSSCS_QOS_NACK_REMOTE,
        LWSSSCS_QOS_ACK_LOCAL,          /* local proxy accepted our tx */
        LWSSSCS_QOS_NACK_LOCAL,         /* local proxy refused our tx */
        LWSSSCS_TIMEOUT,                /* optional timeout timer fired */
 
        LWSSSCS_SERVER_TXN,
        LWSSSCS_SERVER_UPGRADE,         /* the server protocol upgraded */
 
        LWSSSCS_EVENT_WAIT_CANCELLED, /* somebody called lws_cancel_service */
 
        LWSSSCS_UPSTREAM_LINK_RETRY,    /* if we are being proxied over some
                                         * intermediate link, this transient
                                         * state may be sent to indicate we are
                                         * waiting to establish that link before
                                         * creation can proceed.. ack is the
                                         * number of ms we have been trying */
 
        LWSSSCS_SINK_JOIN,              /* sinks get this when a new source
                                         * stream joins the sink */
        LWSSSCS_SINK_PART,              /* sinks get this when a new source
                                         * stream leaves the sink */
 
        LWSSSCS_USER_BASE = 1000
} lws_ss_constate_t;

anonymous enum

anonymous enum

#include <include/libwebsockets/lws-secure-streams.h>

Enumerator
LWSSS_FLAG_SOM
LWSSS_FLAG_EOM
LWSSS_FLAG_POLL
LWSSS_FLAG_RELATED_START
LWSSS_FLAG_RELATED_END
LWSSS_FLAG_RIDESHARE
LWSSS_FLAG_PERF_JSON

Definition at line 114 of file lws-secure-streams.h.

     {
        LWSSS_FLAG_SOM                                          = (1 << 0),
        /* payload contains the start of new message */
        LWSSS_FLAG_EOM                                          = (1 << 1),
        /* payload contains the end of message */
        LWSSS_FLAG_POLL                                         = (1 << 2),
        /* Not a real transmit... poll for rx if protocol needs it */
        LWSSS_FLAG_RELATED_START                                = (1 << 3),
        /* Appears in a zero-length message indicating a message group of zero
         * or more messages is now starting. */
        LWSSS_FLAG_RELATED_END                                  = (1 << 4),
        /* Appears in a zero-length message indicating a message group of zero
         * or more messages has now finished. */
        LWSSS_FLAG_RIDESHARE                                    = (1 << 5),
        /* Serialized payload starts with non-default rideshare name length and
         * name string without NUL, then payload */
        LWSSS_FLAG_PERF_JSON                                    = (1 << 6),
        /* This RX is JSON performance data, only on streams with "perf" flag
         * set */
};

lws_ss_state_return

enum lws_ss_state_return

#include <include/libwebsockets/lws-secure-streams.h>

Enumerator
LWSSSSRET_TX_DONT_SEND
LWSSSSRET_OK
LWSSSSRET_DISCONNECT_ME
LWSSSSRET_DESTROY_ME

Definition at line 140 of file lws-secure-streams.h.

                                 {
        LWSSSSRET_TX_DONT_SEND          =  1, /* (*tx) only, or failure */
 
        LWSSSSRET_OK                    =  0, /* no error */
        LWSSSSRET_DISCONNECT_ME         = -1, /* caller should disconnect us */
        LWSSSSRET_DESTROY_ME            = -2, /* caller should destroy us */
} lws_ss_state_return_t;

anonymous enum

anonymous enum

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_info_t: information about stream to be created

Prepare this struct with information about what the stream type is and how the stream should interface with your code, and pass it to lws_ss_create() to create the requested stream.

Enumerator
LWSSSINFLAGS_REGISTER_SINK	If set, we're not creating a specific stream, but registering ourselves as the "sink" for .streamtype. It's analogous to saying we want to be the many-to-one "server" for .streamtype; when other streams are created with that streamtype, they should be forwarded to this stream owner, where they join and part from the sink via (*state) LWSSSCS_SINK_JOIN / _PART events, the new client handle being provided in the h_src parameter.
LWSSSINFLAGS_PROXIED	Set if the stream is being created as a stand-in at the proxy
LWSSSINFLAGS_SERVER	Set on the server object copy of the ssi / info to indicate that stream creation using this ssi is for Accepted connections belonging to a server
LWSSSINFLAGS_ACCEPTED	Set on the accepted object copy of the ssi / info to indicate that we are an accepted connection from a server's listening socket
LWSSSINFLAGS_ACCEPTED_SINK	Set on the accepted object copy of the ssi / info to indicate that we are an accepted connection from a local sink

Definition at line 156 of file lws-secure-streams.h.

     {
        LWSSSINFLAGS_REGISTER_SINK                      =       (1 << 0),
        LWSSSINFLAGS_PROXIED                            =       (1 << 1),
        LWSSSINFLAGS_SERVER                             =       (1 << 2),
        LWSSSINFLAGS_ACCEPTED                           =       (1 << 3),
        LWSSSINFLAGS_ACCEPTED_SINK                      =       (1 << 4),
};

Function Documentation

lws_ss_create()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_ss_create	(	struct lws_context *	context,
		int	tsi,
		const lws_ss_info_t *	ssi,
		void *	opaque_user_data,
		struct lws_ss_handle **	ppss,
		void *	reserved,
		const char **	ppayload_fmt
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_create() - Create secure stream

Parameters

context	the lws context to create this inside
tsi	service thread index to create on (normally 0)
ssi	pointer to lws_ss_info_t filled in with info about desired stream
opaque_user_data	opaque data to set in the stream's user object
ppss	pointer to secure stream handle pointer set on exit
ppayload_fmt	NULL or pointer to a string ptr to take payload format name from the policy

Requests a new secure stream described by ssi be created. If successful, the stream is created, its state callback called with LWSSSCS_CREATING, *ppss is set to point to the handle, and it returns 0. If it failed, it returns nonzero.

Along with the opaque stream object, streams overallocate

1) a user data struct whose size is set in ssi 2) nauth plugin instantiation data (size set in the plugin struct) 3) sauth plugin instantiation data (size set in the plugin struct) 4) space for a copy of the stream type name

The user data struct is initialized to all zeros, then the .handle_offset and .opaque_user_data_offset fields of the ssi are used to prepare the user data struct with the ss handle that was created, and a copy of the opaque_user_data pointer given as an argument.

If you want to set up the stream with specific information, point to it in opaque_user_data and use the copy of that pointer in your user data member for it starting from the LWSSSCS_CREATING state call.

Since different endpoints chosen by the policy may require different payload formats, ppayload_fmt is set to point to the name of the needed payload format from the policy database if non-NULL.

lws_ss_destroy()

LWS_VISIBLE LWS_EXTERN void lws_ss_destroy

(

struct lws_ss_handle **

ppss

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_destroy() - Destroy secure stream

Parameters

ppss	pointer to lws_ss_t pointer to be destroyed

Destroys the lws_ss_t pointed to by *ppss, and sets *ppss to NULL.

lws_ss_request_tx()

LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT lws_ss_request_tx

(

struct lws_ss_handle *

pss

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_request_tx() - Schedule stream for tx

Parameters

pss	pointer to lws_ss_t representing stream that wants to transmit

Schedules a write on the stream represented by pss. When it's possible to write on this stream, the *tx callback will occur with an empty buffer for the stream owner to fill in.

Returns 0 or LWSSSSRET_DESTROY_ME

lws_ss_request_tx_len()

LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT lws_ss_request_tx_len	(	struct lws_ss_handle *	pss,
		unsigned long	len
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_request_tx() - Schedule stream for tx

Parameters

pss	pointer to lws_ss_t representing stream that wants to transmit
len	the length of the write in bytes

Schedules a write on the stream represented by pss. When it's possible to write on this stream, the *tx callback will occur with an empty buffer for the stream owner to fill in.

This api variant should be used when it's possible the payload will go out over h1 with x-web-form-urlencoded or similar Content-Type.

lws_ss_client_connect()

LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t LWS_WARN_UNUSED_RESULT lws_ss_client_connect

(

struct lws_ss_handle *

h

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_client_connect() - Attempt the client connect

Parameters

h	secure streams handle

Starts the connection process for the secure stream.

Can return any of the lws_ss_state_return_t values depending on user state callback returns.

LWSSSSRET_OK means the connection is ongoing.

lws_ss_proxy_create()

LWS_VISIBLE LWS_EXTERN int lws_ss_proxy_create	(	struct lws_context *	context,
		const char *	bind,
		int	port
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_proxy_create() - Start a unix domain socket proxy for Secure Streams

Parameters

context	lws_context
bind	if port is 0, unix domain path with leading @ for abstract. if port nonzero, NULL, or network interface to bind listen to
port	tcp port to listen on

Creates a vhost that listens either on an abstract namespace unix domain socket (port = 0) or a tcp listen socket (port nonzero). If bind is NULL and port is 0, the abstract unix domain socket defaults to "proxy.ss.lws".

Client connections to this proxy to Secure Streams are fulfilled using the policy local to the proxy and the data passed between the client and the proxy using serialized Secure Streams protocol.

lws_ss_state_name()

LWS_VISIBLE LWS_EXTERN const char* lws_ss_state_name

(

int

state

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_state_name() - convenience helper to get a printable conn state name

Parameters

state

the connection state index

Returns a printable name for the connection state index passed in.

lws_ss_get_context()

LWS_VISIBLE LWS_EXTERN struct lws_context* lws_ss_get_context

(

struct lws_ss_handle *

h

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_get_context() - convenience helper to recover the lws context

Parameters

h	secure streams handle

Returns the lws context. Dispenses with the need to pass a copy of it into your secure streams handler.

lws_ss_get_vhost()

LWS_VISIBLE LWS_EXTERN struct lws_vhost* lws_ss_get_vhost

(

struct lws_ss_handle *

h

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_get_vhost() - convenience helper to get the vhost the ss is bound to

Parameters

h	secure streams handle

Returns NULL if disconnected, or the the lws_vhost of the ss' wsi connection.

lws_ss_start_timeout()

LWS_VISIBLE LWS_EXTERN void lws_ss_start_timeout	(	struct lws_ss_handle *	h,
		unsigned int	timeout_ms
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_start_timeout() - start or restart the timeout on the stream

Parameters

h	secure streams handle
timeout_ms	LWSSS_TIMEOUT_FROM_POLICY for policy value, else use timeout_ms

Starts or restarts the stream's own timeout timer. If the specified time passes without lws_ss_cancel_timeout() being called on the stream, then the stream state callback receives LWSSSCS_TIMEOUT

The process being protected by the timeout is up to the user code, it may be arbitrarily long and cross multiple protocol transactions or involve other streams. It's up to the user to decide when to start and when / if to cancel the stream timeout.

lws_ss_cancel_timeout()

LWS_VISIBLE LWS_EXTERN void lws_ss_cancel_timeout

(

struct lws_ss_handle *

h

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_cancel_timeout() - remove any timeout on the stream

Parameters

h	secure streams handle

Disable any timeout that was applied to the stream by lws_ss_start_timeout().

lws_ss_to_user_object()

LWS_VISIBLE LWS_EXTERN void* lws_ss_to_user_object

(

struct lws_ss_handle *

h

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_to_user_object() - convenience helper to get user object from handle

Parameters

h	secure streams handle

Returns the user allocation related to the handle. Normally you won't need this since it's available in the rx, tx and state callbacks as "userdata" already.

lws_ss_rideshare()

LWS_VISIBLE LWS_EXTERN const char* lws_ss_rideshare

(

struct lws_ss_handle *

h

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_rideshare() - find the current streamtype when types rideshare

Parameters

h	the stream handle

Under some conditions, the payloads may be structured using protocol- specific formatting, eg, http multipart mime. It's possible to map the logical partitions in the payload to different stream types using the policy "rideshare" feature.

This api lets the callback code find out which rideshare stream type the current payload chunk belongs to.

lws_ss_set_metadata()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_ss_set_metadata	(	struct lws_ss_handle *	h,
		const char *	name,
		const void *	value,
		size_t	len
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_set_metadata() - allow user to bind external data to defined ss metadata

Parameters

h	secure streams handle
name	metadata name from the policy
value	pointer to user-managed data to bind to name
len	length of the user-managed data in value

Binds user-managed data to the named metadata item from the ss policy. If present, the metadata item is handled in a protocol-specific way using the associated policy information. For example, in the policy

    "\"metadata\":"         "["
    "{\"uptag\":"  "\"X-Upload-Tag:\"},"
    "{\"ctype\":"  "\"Content-Type:\"},"
    "{\"xctype\":" "\"\"}"
 "],"

when the policy is using h1 is interpreted to add h1 headers of the given name with the value of the metadata on the left.

Return 0 if OK or nonzero if, eg, metadata name does not exist on the streamtype. You must check the result of this, eg, transient OOM can cause these to fail and you should retry later.

lws_ss_alloc_set_metadata()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_ss_alloc_set_metadata	(	struct lws_ss_handle *	h,
		const char *	name,
		const void *	value,
		size_t	len
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_alloc_set_metadata() - copy data and bind to ss metadata

Parameters

h	secure streams handle
name	metadata name from the policy
value	pointer to user-managed data to bind to name
len	length of the user-managed data in value

Same as lws_ss_set_metadata(), but allocates a heap buffer for the data first and takes a copy of it, so the original can go out of scope immediately after.

lws_ss_get_metadata()

LWS_VISIBLE LWS_EXTERN int lws_ss_get_metadata	(	struct lws_ss_handle *	h,
		const char *	name,
		const void **	value,
		size_t *	len
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_get_metadata() - get current value of stream metadata item

Parameters

h	secure streams handle
name	metadata name from the policy
value	pointer to pointer to be set to point at the value
len	pointer to size_t to set to the length of the value

Binds user-managed data to the named metadata item from the ss policy. If present, the metadata item is handled in a protocol-specific way using the associated policy information. For example, in the policy

    "\"metadata\":"         "["
    "{\"uptag\":"  "\"X-Upload-Tag:\"},"
    "{\"ctype\":"  "\"Content-Type:\"},"
    "{\"xctype\":" "\"\"}"
 "],"

when the policy is using h1 is interpreted to add h1 headers of the given name with the value of the metadata on the left.

Return 0 if *value and *len set OK, or nonzero if, eg, metadata name does not exist on the streamtype.

The pointed-to values may only exist until the next time around the event loop.

lws_ss_server_ack()

LWS_VISIBLE LWS_EXTERN void lws_ss_server_ack	(	struct lws_ss_handle *	h,
		int	nack
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_server_ack() - indicate how we feel about what the server has sent

Parameters

h	ss handle of accepted connection
nack	0 means we are OK with it, else some problem

For SERVER secure streams

Depending on the protocol, the server sending us something may be transactional, ie, built into it sending something is the idea we will respond somehow out-of-band; HTTP is like this with, eg, 200 response code.

Calling this with nack=0 indicates that when we later respond, we want to acknowledge the transaction (eg, it means a 200 if http underneath), if nonzero that the transaction should act like it failed.

If the underlying protocol doesn't understand transactions (eg, ws) then this has no effect either way.

lws_ss_server_foreach_client()

LWS_VISIBLE LWS_EXTERN void lws_ss_server_foreach_client	(	struct lws_ss_handle *	h,
		lws_sssfec_cb	cb,
		void *	arg
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_server_foreach_client() - callback for each live client connected to server

Parameters

h	server ss handle
cb	the callback
arg	arg passed to callback

For SERVER secure streams

Call the callback cb once for each client ss connected to the server, passing arg as an additional callback argument each time.

lws_ss_change_handlers()

LWS_VISIBLE LWS_EXTERN void lws_ss_change_handlers	(	struct lws_ss_handle *	h,
		lws_sscb_rx	rx,
		lws_sscb_tx	tx,
		lws_sscb_state	state
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_change_handlers() - helper for dynamically changing stream handlers

Parameters

h	ss handle
rx	the new RX handler
tx	the new TX handler
state	the new state handler

Handlers set to NULL are left unchanged.

This works on any handle, client or server and takes effect immediately.

Depending on circumstances this may be helpful when

a) a server stream undergoes an LWSSSCS_SERVER_UPGRADE (as in http -> ws) and the payloads in the new protocol have a different purpose that is best handled in their own rx and tx callbacks, and

b) you may want to serve several different, possibly large things based on what was requested. Setting a customized handler allows clean encapsulation of the different serving strategies.

If the stream is long-lived, like ws, you should set the changed handler back to the default when the transaction wanting it is completed.

lws_ss_add_peer_tx_credit()

LWS_VISIBLE LWS_EXTERN int lws_ss_add_peer_tx_credit	(	struct lws_ss_handle *	h,
		int32_t	add
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_add_peer_tx_credit() - allow peer to transmit more to us

Parameters

h	secure streams handle
add	additional tx credit (signed)

Indicate to remote peer that we can accept add bytes more payload being sent to us.

lws_ss_get_est_peer_tx_credit()

LWS_VISIBLE LWS_EXTERN int lws_ss_get_est_peer_tx_credit

(

struct lws_ss_handle *

h

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_get_est_peer_tx_credit() - get our current estimate of peer's tx credit

Parameters

h	secure streams handle

Based on what credit we gave it, and what we have received, report our estimate of peer's tx credit usable to transmit to us. This may be outdated in that some or all of its credit may already have been expended by sending stuff to us that is in flight already.

lws_ss_tag()

LWS_VISIBLE LWS_EXTERN const char* lws_ss_tag

(

struct lws_ss_handle *

h

)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_adopt_raw()

LWS_VISIBLE LWS_EXTERN int lws_ss_adopt_raw	(	struct lws_ss_handle *	ss,
		lws_sock_file_fd_type	fd
	)

#include <include/libwebsockets/lws-secure-streams.h>

lws_ss_adopt_raw() - bind ss to existing fd

Parameters

ss	pointer to lws_ss_t to adopt the fd
fd	the existing fd

"connects" the existing ss to a wsi adoption of fd, it's useful for cases like local representation of eg a pipe() fd using ss.