libwebsockets
Lightweight C library for HTML5 websockets
Loading...
Searching...
No Matches
lws-system.h
Go to the documentation of this file.
1 /*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2021 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 *
24 * This provides a clean way to interface lws user code to be able to
25 * work unchanged on different systems for fetching common system information,
26 * and performing common system operations like reboot.
27 */
28
29/*
30 * Types of system blob that can be set and retreived
31 */
32
33typedef enum {
44
45#if defined(LWS_WITH_SECURE_STREAMS_AUTH_SIGV4)
46 /* extend 4 more auth blobs, each has 2 slots */
47 LWS_SYSBLOB_TYPE_EXT_AUTH1,
48 LWS_SYSBLOB_TYPE_EXT_AUTH2 = LWS_SYSBLOB_TYPE_EXT_AUTH1 + 2,
49 LWS_SYSBLOB_TYPE_EXT_AUTH3 = LWS_SYSBLOB_TYPE_EXT_AUTH2 + 2,
50 LWS_SYSBLOB_TYPE_EXT_AUTH4 = LWS_SYSBLOB_TYPE_EXT_AUTH3 + 2,
51 LWS_SYSBLOB_TYPE_EXT_AUTH4_1,
52#endif
53
54 LWS_SYSBLOB_TYPE_COUNT /* ... always last */
56
57/* opaque generic blob whose content may be on-the-heap or pointed-to
58 * directly case by case. When it's on the heap, it can be produced by
59 * appending (it's a buflist underneath). Either way, it can be consumed by
60 * copying out a given length from a given offset.
61 */
62
63typedef struct lws_system_blob lws_system_blob_t;
64
67
70
73
76
77/* return 0 and sets *ptr to point to blob data if possible, nonzero = fail */
80
82lws_system_blob_get(lws_system_blob_t *b, uint8_t *ptr, size_t *len, size_t ofs);
83
86
87/*
88 * Get the opaque blob for index idx of various system blobs. Returns 0 if
89 * *b was set otherwise nonzero means out of range
90 */
91
93lws_system_get_blob(struct lws_context *context, lws_system_blob_item_t type,
94 int idx);
95
96/*
97 * Lws view of system state... normal operation from user code perspective is
98 * dependent on implicit (eg, knowing the date for cert validation) and
99 * explicit dependencies.
100 *
101 * Bit of lws and user code can register notification handlers that can enforce
102 * dependent operations before state transitions can complete.
103 */
104
105typedef enum { /* keep system_state_names[] in sync in context.c */
107
108 LWS_SYSTATE_CONTEXT_CREATED, /* context was just created */
109 LWS_SYSTATE_INITIALIZED, /* protocols initialized. Lws itself
110 * can operate normally */
111 LWS_SYSTATE_COLLECTING_STDIN, /* we are waiting for stdin RX and / or
112 * closure. This is skipped if
113 * system_ops.stdin_rx is NULL */
114 LWS_SYSTATE_IFACE_COLDPLUG, /* existing net ifaces iterated */
115 LWS_SYSTATE_DHCP, /* at least one net iface configured */
116 LWS_SYSTATE_CPD_PRE_TIME, /* Captive portal detect without valid
117 * time, good for non-https tests... if
118 * you care about it, implement and
119 * call lws_system_ops_t
120 * .captive_portal_detect_request()
121 * and move the state forward according
122 * to the result. */
123 LWS_SYSTATE_TIME_VALID, /* ntpclient ran, or hw time valid...
124 * tls cannot work until we reach here
125 */
126 LWS_SYSTATE_CPD_POST_TIME, /* Captive portal detect after time was
127 * time, good for https tests... if
128 * you care about it, implement and
129 * call lws_system_ops_t
130 * .captive_portal_detect_request()
131 * and move the state forward according
132 * to the result. */
133
134 LWS_SYSTATE_POLICY_VALID, /* user code knows how to operate... */
135 LWS_SYSTATE_REGISTERED, /* device has an identity... */
136 LWS_SYSTATE_AUTH1, /* identity used for main auth token */
137 LWS_SYSTATE_AUTH2, /* identity used for optional auth */
138
139 LWS_SYSTATE_ONE_TIME_UPDATES, /* pre-OPERATIONAL one-time updates,
140 * when a firmware needs to perform
141 * one-time upgrades to state before
142 * OPERATIONAL */
143
144 LWS_SYSTATE_OPERATIONAL, /* user code can operate normally */
145
146 LWS_SYSTATE_POLICY_INVALID, /* user code is changing its policies
147 * drop everything done with old
148 * policy, switch to new then enter
149 * LWS_SYSTATE_POLICY_VALID */
150 LWS_SYSTATE_CONTEXT_DESTROYING, /* Context is being destroyed */
151 LWS_SYSTATE_AWAITING_MODAL_UPDATING, /* We're negotiating with the
152 * user code for update mode */
153 LWS_SYSTATE_MODAL_UPDATING, /* We're updating the firmware */
155
156/* Captive Portal Detect -related */
157
158typedef enum {
159 LWS_CPD_UNKNOWN = 0, /* test didn't happen ince last DHCP acq yet */
160 LWS_CPD_INTERNET_OK, /* no captive portal: our CPD test passed OK,
161 * we can go out on the internet */
162 LWS_CPD_CAPTIVE_PORTAL, /* we inferred we're behind a captive portal */
163 LWS_CPD_NO_INTERNET, /* we couldn't touch anything */
165
166typedef void (*lws_attach_cb_t)(struct lws_context *context, int tsi, void *opaque);
167struct lws_attach_item;
168
170lws_tls_jit_trust_got_cert_cb(struct lws_context *cx, void *got_opaque,
171 const uint8_t *skid, size_t skid_len,
172 const uint8_t *der, size_t der_len);
173
174typedef struct lws_system_ops {
175 int (*reboot)(void);
177 int (*attach)(struct lws_context *context, int tsi, lws_attach_cb_t cb,
178 lws_system_states_t state, void *opaque,
179 struct lws_attach_item **get);
194 int (*captive_portal_detect_request)(struct lws_context *context);
200
201#if defined(LWS_WITH_NETWORK)
202 int (*metric_report)(lws_metric_pub_t *mdata);
206#endif
207 int (*jit_trust_query)(struct lws_context *cx, const uint8_t *skid,
208 size_t skid_len, void *got_opaque);
215
216 int (*stdin_rx)(struct lws_context *cx, const char *buf, size_t len);
225
226#if defined(LWS_WITH_OTA)
227 lws_ota_ops_t ota_ops;
229#endif
230
235
236#if defined(LWS_WITH_SYS_STATE)
237
245
246LWS_EXTERN LWS_VISIBLE lws_state_manager_t *
247lws_system_get_state_manager(struct lws_context *context);
248
249#endif
250
251/* wrappers handle NULL members or no ops struct set at all cleanly */
252
253#define LWSSYSGAUTH_HEX (1 << 0)
254
264lws_system_get_ops(struct lws_context *context);
265
266#if defined(LWS_WITH_SYS_STATE)
267
276LWS_EXTERN LWS_VISIBLE struct lws_context *
277lws_system_context_from_system_mgr(lws_state_manager_t *mgr);
278
279#endif
280
313__lws_system_attach(struct lws_context *context, int tsi, lws_attach_cb_t cb,
314 lws_system_states_t state, void *opaque,
315 struct lws_attach_item **get);
316
317
318enum {
324
326
335
337};
338
339#if defined(LWS_WITH_NETWORK)
340typedef struct lws_dhcpc_ifstate {
341 char ifname[16];
342 char domain[64];
343 uint8_t mac[6];
345 lws_sockaddr46 sa46[_LWSDH_SA46_COUNT];
346} lws_dhcpc_ifstate_t;
347
348typedef int (*dhcpc_cb_t)(void *opaque, lws_dhcpc_ifstate_t *is);
349
363lws_dhcpc_request(struct lws_context *c, const char *i, int af, dhcpc_cb_t cb,
364 void *opaque);
365
375lws_dhcpc_remove(struct lws_context *context, const char *iface);
376
387lws_dhcpc_status(struct lws_context *context, lws_sockaddr46 *sa46);
388
399lws_system_cpd_start(struct lws_context *context);
400
402lws_system_cpd_start_defer(struct lws_context *cx, lws_usec_t defer_us);
403
404
415lws_system_cpd_set(struct lws_context *context, lws_cpd_result_t result);
416
417
427lws_system_cpd_state_get(struct lws_context *context);
428
429enum {
430 LWS_SAS_FLAG__APPEND_COMMANDLINE = (1 << 0)
431};
432
461lws_system_adopt_stdin(struct lws_context *cx, unsigned int flags);
462
463
464#endif
465
unsigned int uint32_t
#define LWS_EXTERN
int64_t lws_usec_t
unsigned char uint8_t
#define LWS_VISIBLE
struct lws_metric_pub lws_metric_pub_t
LWS_EXTERN LWS_VISIBLE int lws_system_blob_get_single_ptr(lws_system_blob_t *b, const uint8_t **ptr)
lws_cpd_result_t
Definition lws-system.h:158
@ LWS_CPD_UNKNOWN
Definition lws-system.h:159
@ LWS_CPD_CAPTIVE_PORTAL
Definition lws-system.h:162
@ LWS_CPD_NO_INTERNET
Definition lws-system.h:163
@ LWS_CPD_INTERNET_OK
Definition lws-system.h:160
int(* stdin_rx)(struct lws_context *cx, const char *buf, size_t len)
Definition lws-system.h:216
lws_system_states_t
Definition lws-system.h:105
@ LWS_SYSTATE_POLICY_VALID
Definition lws-system.h:134
@ LWS_SYSTATE_AUTH1
Definition lws-system.h:136
@ LWS_SYSTATE_MODAL_UPDATING
Definition lws-system.h:153
@ LWS_SYSTATE_AUTH2
Definition lws-system.h:137
@ LWS_SYSTATE_CONTEXT_DESTROYING
Definition lws-system.h:150
@ LWS_SYSTATE_CPD_PRE_TIME
Definition lws-system.h:116
@ LWS_SYSTATE_AWAITING_MODAL_UPDATING
Definition lws-system.h:151
@ LWS_SYSTATE_UNKNOWN
Definition lws-system.h:106
@ LWS_SYSTATE_IFACE_COLDPLUG
Definition lws-system.h:114
@ LWS_SYSTATE_DHCP
Definition lws-system.h:115
@ LWS_SYSTATE_REGISTERED
Definition lws-system.h:135
@ LWS_SYSTATE_COLLECTING_STDIN
Definition lws-system.h:111
@ LWS_SYSTATE_OPERATIONAL
Definition lws-system.h:144
@ LWS_SYSTATE_INITIALIZED
Definition lws-system.h:109
@ LWS_SYSTATE_ONE_TIME_UPDATES
Definition lws-system.h:139
@ LWS_SYSTATE_TIME_VALID
Definition lws-system.h:123
@ LWS_SYSTATE_CONTEXT_CREATED
Definition lws-system.h:108
@ LWS_SYSTATE_POLICY_INVALID
Definition lws-system.h:146
@ LWS_SYSTATE_CPD_POST_TIME
Definition lws-system.h:126
int(* attach)(struct lws_context *context, int tsi, lws_attach_cb_t cb, lws_system_states_t state, void *opaque, struct lws_attach_item **get)
Definition lws-system.h:177
@ LWSDH_REBINDING_SECS
Definition lws-system.h:322
@ LWSDH_SA46_DNS_SRV_4
Definition lws-system.h:331
@ LWSDH_SA46_IPV4_ROUTER
Definition lws-system.h:332
@ LWSDH_IPV4_BROADCAST
Definition lws-system.h:320
@ LWSDH_SA46_NTP_SERVER
Definition lws-system.h:333
@ _LWSDH_NUMS_COUNT
Definition lws-system.h:325
@ LWSDH_SA46_IP
Definition lws-system.h:327
@ LWSDH_SA46_DHCP_SERVER
Definition lws-system.h:334
@ LWSDH_SA46_DNS_SRV_3
Definition lws-system.h:330
@ LWSDH_IPV4_SUBNET_MASK
Definition lws-system.h:319
@ LWSDH_RENEWAL_SECS
Definition lws-system.h:323
@ LWSDH_SA46_DNS_SRV_1
Definition lws-system.h:328
@ LWSDH_LEASE_SECS
Definition lws-system.h:321
@ LWSDH_SA46_DNS_SRV_2
Definition lws-system.h:329
@ _LWSDH_SA46_COUNT
Definition lws-system.h:336
int(* jit_trust_query)(struct lws_context *cx, const uint8_t *skid, size_t skid_len, void *got_opaque)
Definition lws-system.h:207
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_EXTERN LWS_VISIBLE void lws_system_blob_destroy(lws_system_blob_t *b)
struct lws_system_ops lws_system_ops_t
int(* captive_portal_detect_request)(struct lws_context *context)
Definition lws-system.h:194
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 void lws_system_blob_heap_empty(lws_system_blob_t *b)
LWS_EXTERN LWS_VISIBLE int lws_system_blob_get(lws_system_blob_t *b, uint8_t *ptr, size_t *len, size_t ofs)
struct lws_system_blob lws_system_blob_t
Definition lws-system.h:63
void(* lws_attach_cb_t)(struct lws_context *context, int tsi, void *opaque)
Definition lws-system.h:166
LWS_EXTERN LWS_VISIBLE size_t lws_system_blob_get_size(lws_system_blob_t *b)
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 lws_system_blob_t * lws_system_get_blob(struct lws_context *context, lws_system_blob_item_t type, int idx)
uint32_t wake_latency_us
Definition lws-system.h:231
int(* set_clock)(lws_usec_t us)
Definition lws-system.h:176
LWS_EXTERN LWS_VISIBLE const lws_system_ops_t * lws_system_get_ops(struct lws_context *context)
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)
int(* reboot)(void)
Definition lws-system.h:175
lws_system_blob_item_t
Definition lws-system.h:33
@ LWS_SYSBLOB_TYPE_NTP_SERVER
Definition lws-system.h:40
@ LWS_SYSBLOB_TYPE_MQTT_USERNAME
Definition lws-system.h:42
@ LWS_SYSBLOB_TYPE_MQTT_PASSWORD
Definition lws-system.h:43
@ LWS_SYSBLOB_TYPE_MQTT_CLIENT_ID
Definition lws-system.h:41
@ LWS_SYSBLOB_TYPE_CLIENT_CERT_DER
Definition lws-system.h:35
@ LWS_SYSBLOB_TYPE_COUNT
Definition lws-system.h:54
@ LWS_SYSBLOB_TYPE_DEVICE_SERIAL
Definition lws-system.h:37
@ LWS_SYSBLOB_TYPE_DEVICE_FW_VERSION
Definition lws-system.h:38
@ LWS_SYSBLOB_TYPE_AUTH
Definition lws-system.h:34
@ LWS_SYSBLOB_TYPE_DEVICE_TYPE
Definition lws-system.h:39
@ LWS_SYSBLOB_TYPE_CLIENT_KEY_DER
Definition lws-system.h:36