lws-system.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	lws_system_ops

Macros
#define	LWSSYSGAUTH_HEX   (1 << 0)

Typedefs
typedef struct lws_system_blob	lws_system_blob_t
typedef void(*	lws_attach_cb_t) (struct lws_context *context, int tsi, void *opaque)
typedef struct lws_system_ops	lws_system_ops_t

Enumerations
enum	lws_system_blob_item_t {   LWS_SYSBLOB_TYPE_AUTH , LWS_SYSBLOB_TYPE_CLIENT_CERT_DER = LWS_SYSBLOB_TYPE_AUTH + 2 , LWS_SYSBLOB_TYPE_CLIENT_KEY_DER , LWS_SYSBLOB_TYPE_DEVICE_SERIAL ,   LWS_SYSBLOB_TYPE_DEVICE_FW_VERSION , LWS_SYSBLOB_TYPE_DEVICE_TYPE , LWS_SYSBLOB_TYPE_NTP_SERVER , LWS_SYSBLOB_TYPE_MQTT_CLIENT_ID ,   LWS_SYSBLOB_TYPE_MQTT_USERNAME , LWS_SYSBLOB_TYPE_MQTT_PASSWORD , LWS_SYSBLOB_TYPE_COUNT }
enum	lws_system_states_t {   LWS_SYSTATE_UNKNOWN , LWS_SYSTATE_CONTEXT_CREATED , LWS_SYSTATE_INITIALIZED , LWS_SYSTATE_COLLECTING_STDIN ,   LWS_SYSTATE_IFACE_COLDPLUG , LWS_SYSTATE_DHCP , LWS_SYSTATE_CPD_PRE_TIME , LWS_SYSTATE_TIME_VALID ,   LWS_SYSTATE_CPD_POST_TIME , LWS_SYSTATE_POLICY_VALID , LWS_SYSTATE_REGISTERED , LWS_SYSTATE_AUTH1 ,   LWS_SYSTATE_AUTH2 , LWS_SYSTATE_ONE_TIME_UPDATES , LWS_SYSTATE_OPERATIONAL , LWS_SYSTATE_POLICY_INVALID ,   LWS_SYSTATE_CONTEXT_DESTROYING , LWS_SYSTATE_AWAITING_MODAL_UPDATING , LWS_SYSTATE_MODAL_UPDATING }
enum	lws_cpd_result_t { LWS_CPD_UNKNOWN = 0 , LWS_CPD_INTERNET_OK , LWS_CPD_CAPTIVE_PORTAL , LWS_CPD_NO_INTERNET }
enum	{   LWSDH_IPV4_SUBNET_MASK = 0 , LWSDH_IPV4_BROADCAST , LWSDH_LEASE_SECS , LWSDH_REBINDING_SECS ,   LWSDH_RENEWAL_SECS , _LWSDH_NUMS_COUNT , LWSDH_SA46_IP = 0 , LWSDH_SA46_DNS_SRV_1 ,   LWSDH_SA46_DNS_SRV_2 , LWSDH_SA46_DNS_SRV_3 , LWSDH_SA46_DNS_SRV_4 , LWSDH_SA46_IPV4_ROUTER ,   LWSDH_SA46_NTP_SERVER , LWSDH_SA46_DHCP_SERVER , _LWSDH_SA46_COUNT }

Functions
LWS_EXTERN LWS_VISIBLE void	lws_system_blob_direct_set (lws_system_blob_t *b, const uint8_t *ptr, size_t len)
LWS_EXTERN LWS_VISIBLE void	lws_system_blob_heap_empty (lws_system_blob_t *b)
LWS_EXTERN LWS_VISIBLE int	lws_system_blob_heap_append (lws_system_blob_t *b, const uint8_t *ptr, size_t len)
LWS_EXTERN LWS_VISIBLE size_t	lws_system_blob_get_size (lws_system_blob_t *b)
LWS_EXTERN LWS_VISIBLE int	lws_system_blob_get_single_ptr (lws_system_blob_t *b, const uint8_t **ptr)
LWS_EXTERN LWS_VISIBLE int	lws_system_blob_get (lws_system_blob_t *b, uint8_t *ptr, size_t *len, size_t ofs)
LWS_EXTERN LWS_VISIBLE void	lws_system_blob_destroy (lws_system_blob_t *b)
LWS_EXTERN LWS_VISIBLE lws_system_blob_t *	lws_system_get_blob (struct lws_context *context, lws_system_blob_item_t type, int idx)
LWS_EXTERN LWS_VISIBLE int	lws_tls_jit_trust_got_cert_cb (struct lws_context *cx, void *got_opaque, const uint8_t *skid, size_t skid_len, const uint8_t *der, size_t der_len)
LWS_EXTERN LWS_VISIBLE const lws_system_ops_t *	lws_system_get_ops (struct lws_context *context)
LWS_EXTERN LWS_VISIBLE int	__lws_system_attach (struct lws_context *context, int tsi, lws_attach_cb_t cb, lws_system_states_t state, void *opaque, struct lws_attach_item **get)

---

Data Structure Documentation

lws_system_ops

struct lws_system_ops

Definition at line 174 of file lws-system.h.

Collaboration diagram for lws_system_ops:

Data Fields
int(*)(void)	reboot
int(*)(lws_usec_t us)	set_clock
int(*)(struct lws_context *context, int tsi, lws_attach_cb_t cb, lws_system_states_t state, void *opaque, struct lws_attach_item **get)	attach	if get is NULL, add an attach callback request to the pt for cb with arg opaque, that should be called when we're at or past system state state. If get is non-NULL, look for the first listed item on the pt whose state situation is ready, and set *get to point to it. If no items, or none where the system state is right, set *get to NULL. It's done like this so (*attach) can perform system-specific locking outside of lws core, for both getting and adding items the same so it is thread-safe. A non-threadsafe helper __lws_system_attach() is provided to do the actual work inside the system-specific locking.
int(*)(struct lws_context *context)	captive_portal_detect_request	Check if we can go out on the internet cleanly, or if we are being redirected or intercepted by a captive portal. Start the check that proceeds asynchronously, and report the results by calling lws_captive_portal_detect_result() api
int(*)(struct lws_context *cx, const uint8_t *skid, size_t skid_len, void *got_opaque)	jit_trust_query	user defined trust store search, if we do trust a cert with SKID matching skid / skid_len, then it should get hold of the DER for the matching root CA and call lws_tls_jit_trust_got_cert_cb(..., got_opaque) before cleaning up and returning. The DER should be destroyed if in heap before returning.
int(*)(struct lws_context *cx, const char *buf, size_t len)	stdin_rx	anything from stdin turns up here, eg, echo -n 123 | ./myapp will cause this to be called with buf = "123" and len=3. If stdin closes before the event loop terminates, we will be called with buf = NULL and len = 0 and nothing further, since stdin will be closed. This is very handy for passing secrets into your app that will not be visible to others via the commandline and with solid behaviours whenever the stdin source closes.
uint32_t	wake_latency_us	time taken for this device to wake from suspend, in us

Macro Definition Documentation

LWSSYSGAUTH_HEX

#define LWSSYSGAUTH_HEX   (1 << 0)

Definition at line 253 of file lws-system.h.

Typedef Documentation

lws_system_blob_t

typedef struct lws_system_blob lws_system_blob_t

Definition at line 63 of file lws-system.h.

lws_attach_cb_t

typedef void(* lws_attach_cb_t) (struct lws_context *context, int tsi, void *opaque)

Definition at line 166 of file lws-system.h.

lws_system_ops_t

typedef struct lws_system_ops lws_system_ops_t

Enumeration Type Documentation

lws_system_blob_item_t

enum lws_system_blob_item_t

Enumerator
LWS_SYSBLOB_TYPE_AUTH
LWS_SYSBLOB_TYPE_CLIENT_CERT_DER
LWS_SYSBLOB_TYPE_CLIENT_KEY_DER
LWS_SYSBLOB_TYPE_DEVICE_SERIAL
LWS_SYSBLOB_TYPE_DEVICE_FW_VERSION
LWS_SYSBLOB_TYPE_DEVICE_TYPE
LWS_SYSBLOB_TYPE_NTP_SERVER
LWS_SYSBLOB_TYPE_MQTT_CLIENT_ID
LWS_SYSBLOB_TYPE_MQTT_USERNAME
LWS_SYSBLOB_TYPE_MQTT_PASSWORD
LWS_SYSBLOB_TYPE_COUNT

Definition at line 33 of file lws-system.h.

             {
        LWS_SYSBLOB_TYPE_AUTH,
        LWS_SYSBLOB_TYPE_CLIENT_CERT_DER = LWS_SYSBLOB_TYPE_AUTH + 2,
        LWS_SYSBLOB_TYPE_CLIENT_KEY_DER,
        LWS_SYSBLOB_TYPE_DEVICE_SERIAL,
        LWS_SYSBLOB_TYPE_DEVICE_FW_VERSION,
        LWS_SYSBLOB_TYPE_DEVICE_TYPE,
        LWS_SYSBLOB_TYPE_NTP_SERVER,
        LWS_SYSBLOB_TYPE_MQTT_CLIENT_ID,
        LWS_SYSBLOB_TYPE_MQTT_USERNAME,
        LWS_SYSBLOB_TYPE_MQTT_PASSWORD,
 
#if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4)
        /* extend 4 more auth blobs, each has 2 slots */
        LWS_SYSBLOB_TYPE_EXT_AUTH1,
        LWS_SYSBLOB_TYPE_EXT_AUTH2 = LWS_SYSBLOB_TYPE_EXT_AUTH1 + 2,
        LWS_SYSBLOB_TYPE_EXT_AUTH3 = LWS_SYSBLOB_TYPE_EXT_AUTH2 + 2,
        LWS_SYSBLOB_TYPE_EXT_AUTH4 = LWS_SYSBLOB_TYPE_EXT_AUTH3 + 2,
        LWS_SYSBLOB_TYPE_EXT_AUTH4_1,
#endif
 
        LWS_SYSBLOB_TYPE_COUNT /* ... always last */
} lws_system_blob_item_t;

lws_system_states_t

enum lws_system_states_t

Enumerator
LWS_SYSTATE_UNKNOWN
LWS_SYSTATE_CONTEXT_CREATED
LWS_SYSTATE_INITIALIZED
LWS_SYSTATE_COLLECTING_STDIN
LWS_SYSTATE_IFACE_COLDPLUG
LWS_SYSTATE_DHCP
LWS_SYSTATE_CPD_PRE_TIME
LWS_SYSTATE_TIME_VALID
LWS_SYSTATE_CPD_POST_TIME
LWS_SYSTATE_POLICY_VALID
LWS_SYSTATE_REGISTERED
LWS_SYSTATE_AUTH1
LWS_SYSTATE_AUTH2
LWS_SYSTATE_ONE_TIME_UPDATES
LWS_SYSTATE_OPERATIONAL
LWS_SYSTATE_POLICY_INVALID
LWS_SYSTATE_CONTEXT_DESTROYING
LWS_SYSTATE_AWAITING_MODAL_UPDATING
LWS_SYSTATE_MODAL_UPDATING

Definition at line 105 of file lws-system.h.

             { /* keep system_state_names[] in sync in context.c */
        LWS_SYSTATE_UNKNOWN,
 
        LWS_SYSTATE_CONTEXT_CREATED,  /* context was just created */
        LWS_SYSTATE_INITIALIZED,  /* protocols initialized.  Lws itself
                                          * can operate normally */
        LWS_SYSTATE_COLLECTING_STDIN,        /* we are waiting for stdin RX and / or
                                          * closure.  This is skipped if
                                          * system_ops.stdin_rx is NULL */
        LWS_SYSTATE_IFACE_COLDPLUG,    /* existing net ifaces iterated */
        LWS_SYSTATE_DHCP,                /* at least one net iface configured */
        LWS_SYSTATE_CPD_PRE_TIME,        /* Captive portal detect without valid
                                          * time, good for non-https tests... if
                                          * you care about it, implement and
                                          * call lws_system_ops_t
                                          * .captive_portal_detect_request()
                                          * and move the state forward according
                                          * to the result. */
        LWS_SYSTATE_TIME_VALID,            /* ntpclient ran, or hw time valid...
                                          * tls cannot work until we reach here
                                          */
        LWS_SYSTATE_CPD_POST_TIME,      /* Captive portal detect after time was
                                          * time, good for https tests... if
                                          * you care about it, implement and
                                          * call lws_system_ops_t
                                          * .captive_portal_detect_request()
                                          * and move the state forward according
                                          * to the result. */
 
        LWS_SYSTATE_POLICY_VALID,        /* user code knows how to operate... */
        LWS_SYSTATE_REGISTERED,            /* device has an identity... */
        LWS_SYSTATE_AUTH1,              /* identity used for main auth token */
        LWS_SYSTATE_AUTH2,              /* identity used for optional auth */
 
        LWS_SYSTATE_ONE_TIME_UPDATES,        /* pre-OPERATIONAL one-time updates,
                                          * when a firmware needs to perform
                                          * one-time upgrades to state before
                                          * OPERATIONAL */
 
        LWS_SYSTATE_OPERATIONAL,  /* user code can operate normally */
 
        LWS_SYSTATE_POLICY_INVALID,    /* user code is changing its policies
                                          * drop everything done with old
                                          * policy, switch to new then enter
                                          * LWS_SYSTATE_POLICY_VALID */
        LWS_SYSTATE_CONTEXT_DESTROYING,    /* Context is being destroyed */
        LWS_SYSTATE_AWAITING_MODAL_UPDATING,  /* We're negotiating with the
                                                  * user code for update mode */
        LWS_SYSTATE_MODAL_UPDATING,    /* We're updating the firmware */
} lws_system_states_t;

lws_cpd_result_t

enum lws_cpd_result_t

Enumerator
LWS_CPD_UNKNOWN
LWS_CPD_INTERNET_OK
LWS_CPD_CAPTIVE_PORTAL
LWS_CPD_NO_INTERNET

Definition at line 158 of file lws-system.h.

             {
        LWS_CPD_UNKNOWN = 0,     /* test didn't happen ince last DHCP acq yet */
        LWS_CPD_INTERNET_OK, /* no captive portal: our CPD test passed OK,
                                 * we can go out on the internet */
        LWS_CPD_CAPTIVE_PORTAL,   /* we inferred we're behind a captive portal */
        LWS_CPD_NO_INTERNET, /* we couldn't touch anything */
} lws_cpd_result_t;

anonymous enum

anonymous enum

Enumerator
LWSDH_IPV4_SUBNET_MASK
LWSDH_IPV4_BROADCAST
LWSDH_LEASE_SECS
LWSDH_REBINDING_SECS
LWSDH_RENEWAL_SECS
_LWSDH_NUMS_COUNT
LWSDH_SA46_IP
LWSDH_SA46_DNS_SRV_1
LWSDH_SA46_DNS_SRV_2
LWSDH_SA46_DNS_SRV_3
LWSDH_SA46_DNS_SRV_4
LWSDH_SA46_IPV4_ROUTER
LWSDH_SA46_NTP_SERVER
LWSDH_SA46_DHCP_SERVER
_LWSDH_SA46_COUNT

Definition at line 318 of file lws-system.h.

     {
        LWSDH_IPV4_SUBNET_MASK            = 0,
        LWSDH_IPV4_BROADCAST,
        LWSDH_LEASE_SECS,
        LWSDH_REBINDING_SECS,
        LWSDH_RENEWAL_SECS,
 
        _LWSDH_NUMS_COUNT,
 
        LWSDH_SA46_IP                      = 0,
        LWSDH_SA46_DNS_SRV_1,
        LWSDH_SA46_DNS_SRV_2,
        LWSDH_SA46_DNS_SRV_3,
        LWSDH_SA46_DNS_SRV_4,
        LWSDH_SA46_IPV4_ROUTER,
        LWSDH_SA46_NTP_SERVER,
        LWSDH_SA46_DHCP_SERVER,
 
        _LWSDH_SA46_COUNT,
};

Function Documentation

lws_system_blob_direct_set()

LWS_EXTERN LWS_VISIBLE void lws_system_blob_direct_set	(	lws_system_blob_t *	b,
		const uint8_t *	ptr,
		size_t	len )

References LWS_EXTERN, and LWS_VISIBLE.

lws_system_blob_heap_empty()

LWS_EXTERN LWS_VISIBLE void lws_system_blob_heap_empty

(

lws_system_blob_t *

b

)

References LWS_EXTERN, and LWS_VISIBLE.

lws_system_blob_heap_append()

LWS_EXTERN LWS_VISIBLE int lws_system_blob_heap_append	(	lws_system_blob_t *	b,
		const uint8_t *	ptr,
		size_t	len )

References LWS_EXTERN, and LWS_VISIBLE.

lws_system_blob_get_size()

LWS_EXTERN LWS_VISIBLE size_t lws_system_blob_get_size

(

lws_system_blob_t *

b

)

References LWS_EXTERN, and LWS_VISIBLE.

lws_system_blob_get_single_ptr()

LWS_EXTERN LWS_VISIBLE int lws_system_blob_get_single_ptr	(	lws_system_blob_t *	b,
		const uint8_t **	ptr )

References LWS_EXTERN, and LWS_VISIBLE.

lws_system_blob_get()

LWS_EXTERN LWS_VISIBLE int lws_system_blob_get	(	lws_system_blob_t *	b,
		uint8_t *	ptr,
		size_t *	len,
		size_t	ofs )

References LWS_EXTERN, and LWS_VISIBLE.

lws_system_blob_destroy()

LWS_EXTERN LWS_VISIBLE void lws_system_blob_destroy

(

lws_system_blob_t *

b

)

References LWS_EXTERN, and LWS_VISIBLE.

lws_system_get_blob()

LWS_EXTERN LWS_VISIBLE lws_system_blob_t * lws_system_get_blob	(	struct lws_context *	context,
		lws_system_blob_item_t	type,
		int	idx )

lws_tls_jit_trust_got_cert_cb()

LWS_EXTERN LWS_VISIBLE int lws_tls_jit_trust_got_cert_cb	(	struct lws_context *	cx,
		void *	got_opaque,
		const uint8_t *	skid,
		size_t	skid_len,
		const uint8_t *	der,
		size_t	der_len )

lws_system_get_ops()

LWS_EXTERN LWS_VISIBLE const lws_system_ops_t * lws_system_get_ops

(

struct lws_context *

context

)

lws_system_get_ops() - get ahold of the system ops struct from the context

Parameters

context

the lws_context

Returns the system ops struct. It may return NULL and if not, anything in there may be NULL.

References LWS_EXTERN, and LWS_VISIBLE.

__lws_system_attach()

LWS_EXTERN LWS_VISIBLE int __lws_system_attach	(	struct lws_context *	context,
		int	tsi,
		lws_attach_cb_t	cb,
		lws_system_states_t	state,
		void *	opaque,
		struct lws_attach_item **	get )

__lws_system_attach() - get and set items on context attach list

Parameters

context	context to get or set attach items to
tsi	thread service index (normally 0)
cb	callback to call from context event loop thread
state	the lws_system state we have to be in or have passed through
opaque	optional pointer to user specific info given to callback
get	NULL, or pointer to pointer to take detached tail item on exit

This allows other threads to enqueue callback requests to happen from a pt's event loop thread safely. The callback gets the context pointer and a user opaque pointer that can be optionally given when the item is added to the attach list.

This api is the no-locking core function for getting and setting items on the pt's attach list. The lws_system operation (*attach) is the actual api that user and internal code calls for this feature, it should perform system-specific locking, call this helper, release the locking and then return the result. This api is public only so it can be used in the locked implementation of (*attach).

If get is NULL, then the call adds to the head of the pt attach list using cb, state, and opaque; if get is non-NULL, then *get is set to the first waiting attached item that meets the state criteria and that item is removed from the list.

This is a non-threadsafe helper only designed to be called from implementations of struct lws_system's (*attach) operation where system- specific locking has been applied around it, making it threadsafe.