1# LWS System Helpers
2
3Lws now has a little collection of helper utilities for common network-based
4functions necessary for normal device operation, eg, async DNS, ntpclient
5(necessary for tls validation), and DHCP client.
6
7## Conventions
8
9If any system helper is enabled for build, lws creates an additional vhost
10"system" at Context Creation time.  Wsi that are created for the system
11features are bound to this.  In the context object, this is available as
12`.vhost_system`.
13
14# Attaching to an existing context from other threads
15
16To simplify the case different pieces of code want to attach to a single
17lws_context at runtime, from different thread contexts, lws_system has an api
18via an lws_system operation function pointer where the other threads can use
19platform-specific locking to request callbacks to their own code from the
20lws event loop thread context safely.
21
22For convenience, the callback can be delayed until the system has entered or
23passed a specified system state, eg, LWS_SYSTATE_OPERATIONAL so the code will
24only get called back after the network, ntpclient and auth have been done.
25Additionally an opaque pointer can be passed to the callback when it is called
26from the lws event loop context.
27
28## Implementing the system-specific locking
29
30`lws_system_ops_t` struct has a member `.attach`
31
32```
33	int (*attach)(struct lws_context *context, int tsi, lws_attach_cb_t *cb,
34		      lws_system_states_t state, void *opaque,
35		      struct lws_attach_item **get);
36```
37
38This should be defined in user code as setting locking, then passing the
39arguments through to a non-threadsafe helper
40
41```
42int
43__lws_system_attach(struct lws_context *context, int tsi, lws_attach_cb_t *cb,
44		    lws_system_states_t state, void *opaque,
45		    struct lws_attach_item **get);
46```
47
48that does the actual attach work.  When it returns, the locking should be
49unlocked and the return passed back.
50
51## Attaching the callback request
52
53User code should call the lws_system_ops_t `.attach` function like
54
55```
56	lws_system_get_ops(context)->attach(...);
57```
58
59The callback function which will be called from the lws event loop context
60should look like this
61
62```
63void my_callback(struct lws_context *context, int tsi, void *opaque);
64```
65
66with the callback function name passed into the (*attach)() call above.  When
67the callback happens, the opaque user pointer set at the (*attach)() call is
68passed back to it as an argument.
69