libwebsockets
Lightweight C library for HTML5 websockets
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 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)
 

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

◆ lws_ss_opaque_from_user

#define lws_ss_opaque_from_user (   _u)    (_u)->opaque_data

◆ lws_ss_cx_from_user

#define lws_ss_cx_from_user (   _u)    lws_ss_get_context((_u)->ss)

◆ lws_context_info_defaults

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

◆ LWSSS_TIMEOUT_FROM_POLICY

#define LWSSS_TIMEOUT_FROM_POLICY   0

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

◆ lws_sscb_rx

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

◆ 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)

◆ 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)

◆ lws_ss_info_t

◆ lws_sssfec_cb

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

Enumeration Type Documentation

◆ 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.

76  {
77  /* zero means unset */
78  LWSSSCS_CREATING = 1,
80  LWSSSCS_UNREACHABLE, /* oridinal arg = 1 = caused by dns
81  * server reachability failure */
87  LWSSSCS_ALL_RETRIES_FAILED, /* all retries in bo policy failed */
88  LWSSSCS_QOS_ACK_REMOTE, /* remote peer received and acked tx */
90  LWSSSCS_QOS_ACK_LOCAL, /* local proxy accepted our tx */
91  LWSSSCS_QOS_NACK_LOCAL, /* local proxy refused our tx */
92  LWSSSCS_TIMEOUT, /* optional timeout timer fired */
93 
95  LWSSSCS_SERVER_UPGRADE, /* the server protocol upgraded */
96 
97  LWSSSCS_EVENT_WAIT_CANCELLED, /* somebody called lws_cancel_service */
98 
99  LWSSSCS_UPSTREAM_LINK_RETRY, /* if we are being proxied over some
100  * intermediate link, this transient
101  * state may be sent to indicate we are
102  * waiting to establish that link before
103  * creation can proceed.. ack is the
104  * number of ms we have been trying */
105 
106  LWSSSCS_SINK_JOIN, /* sinks get this when a new source
107  * stream joins the sink */
108  LWSSSCS_SINK_PART, /* sinks get this when a new source
109  * stream leaves the sink */
110 
111  LWSSSCS_USER_BASE = 1000
lws_ss_constate_t
@ LWSSSCS_DESTROYING
@ LWSSSCS_POLL
@ LWSSSCS_CREATING
@ LWSSSCS_QOS_NACK_REMOTE
@ LWSSSCS_DISCONNECTED
@ LWSSSCS_EVENT_WAIT_CANCELLED
@ LWSSSCS_SINK_JOIN
@ LWSSSCS_TIMEOUT
@ LWSSSCS_SERVER_UPGRADE
@ LWSSSCS_ALL_RETRIES_FAILED
@ LWSSSCS_AUTH_FAILED
@ LWSSSCS_SINK_PART
@ LWSSSCS_UNREACHABLE
@ LWSSSCS_QOS_NACK_LOCAL
@ LWSSSCS_CONNECTED
@ LWSSSCS_QOS_ACK_LOCAL
@ LWSSSCS_UPSTREAM_LINK_RETRY
@ LWSSSCS_QOS_ACK_REMOTE
@ LWSSSCS_SERVER_TXN
@ LWSSSCS_CONNECTING
@ LWSSSCS_USER_BASE

◆ 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.

114  {
115  LWSSS_FLAG_SOM = (1 << 0),
116  /* payload contains the start of new message */
117  LWSSS_FLAG_EOM = (1 << 1),
118  /* payload contains the end of message */
119  LWSSS_FLAG_POLL = (1 << 2),
120  /* Not a real transmit... poll for rx if protocol needs it */
121  LWSSS_FLAG_RELATED_START = (1 << 3),
122  /* Appears in a zero-length message indicating a message group of zero
123  * or more messages is now starting. */
124  LWSSS_FLAG_RELATED_END = (1 << 4),
125  /* Appears in a zero-length message indicating a message group of zero
126  * or more messages has now finished. */
127  LWSSS_FLAG_RIDESHARE = (1 << 5),
128  /* Serialized payload starts with non-default rideshare name length and
129  * name string without NUL, then payload */
130  LWSSS_FLAG_PERF_JSON = (1 << 6),
131  /* This RX is JSON performance data, only on streams with "perf" flag
132  * set */
133 };
@ LWSSS_FLAG_RELATED_START
@ LWSSS_FLAG_SOM
@ LWSSS_FLAG_EOM
@ LWSSS_FLAG_PERF_JSON
@ LWSSS_FLAG_POLL
@ LWSSS_FLAG_RELATED_END
@ LWSSS_FLAG_RIDESHARE

◆ 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.

140  {
141  LWSSSSRET_TX_DONT_SEND = 1, /* (*tx) only, or failure */
142 
143  LWSSSSRET_OK = 0, /* no error */
144  LWSSSSRET_DISCONNECT_ME = -1, /* caller should disconnect us */
145  LWSSSSRET_DESTROY_ME = -2, /* caller should destroy us */
enum lws_ss_state_return lws_ss_state_return_t
@ LWSSSSRET_OK
@ LWSSSSRET_DISCONNECT_ME
@ LWSSSSRET_DESTROY_ME
@ LWSSSSRET_TX_DONT_SEND

◆ 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.

156  {
157  LWSSSINFLAGS_REGISTER_SINK = (1 << 0),
166  LWSSSINFLAGS_PROXIED = (1 << 1),
168  LWSSSINFLAGS_SERVER = (1 << 2),
172  LWSSSINFLAGS_ACCEPTED = (1 << 3),
175  LWSSSINFLAGS_ACCEPTED_SINK = (1 << 4),
178 };
@ LWSSSINFLAGS_REGISTER_SINK
@ LWSSSINFLAGS_ACCEPTED_SINK
@ LWSSSINFLAGS_SERVER
@ LWSSSINFLAGS_ACCEPTED
@ LWSSSINFLAGS_PROXIED

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
contextthe lws context to create this inside
tsiservice thread index to create on (normally 0)
ssipointer to lws_ss_info_t filled in with info about desired stream
opaque_user_dataopaque data to set in the stream's user object
ppsspointer to secure stream handle pointer set on exit
ppayload_fmtNULL 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
ppsspointer 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
psspointer 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
psspointer to lws_ss_t representing stream that wants to transmit
lenthe 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
hsecure 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
contextlws_context
bindif port is 0, unix domain path with leading @ for abstract. if port nonzero, NULL, or network interface to bind listen to
porttcp 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
statethe 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
hsecure streams handle

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

◆ 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
hsecure streams handle
timeout_msLWSSS_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
hsecure 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
hsecure 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
hthe 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
hsecure streams handle
namemetadata name from the policy
valuepointer to user-managed data to bind to name
lenlength 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
hsecure streams handle
namemetadata name from the policy
valuepointer to user-managed data to bind to name
lenlength 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
hsecure streams handle
namemetadata name from the policy
valuepointer to pointer to be set to point at the value
lenpointer 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
hss handle of accepted connection
nack0 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
hserver ss handle
cbthe callback
argarg 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
hss handle
rxthe new RX handler
txthe new TX handler
statethe 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
hsecure streams handle
addadditional 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
hsecure 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)