libwebsockets
Lightweight C library for HTML5 websockets
lws-secure-streams-client.h
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2019 - 2020 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 is the headers for secure stream api variants that deal with clients in
25  * different threads or even different processes.
26  *
27  * lws_ss_ when client is directly using the event loop
28  * lws_sstc_ when client is in a different thread to the event loop
29  * lws_sspc_ when client is in a different process to the event loop
30  *
31  * The client api is almost the same except the slightly diffent names.
32  *
33  * This header is included as part of libwebsockets.h, for link against the
34  * libwebsockets library.
35  */
36 
37 /*
38  * lws_sspc_ apis... different process
39  */
40 
41 /*
42  * Helper translation so user code written to lws_ss_ can be built for
43  * lws_sspc_ in one step by #define LWS_SS_USE_SSPC before including
44  */
45 
46 
47 struct lws_sspc_handle;
48 
49 #if defined(LWS_SS_USE_SSPC)
50 #define lws_ss_handle lws_sspc_handle
51 #define lws_ss_create lws_sspc_create
52 #define lws_ss_destroy lws_sspc_destroy
53 #define lws_ss_request_tx lws_sspc_request_tx
54 #define lws_ss_request_tx_len lws_sspc_request_tx_len
55 #define lws_ss_client_connect lws_sspc_client_connect
56 #define lws_ss_get_sequencer lws_sspc_get_sequencer
57 #define lws_ss_proxy_create lws_sspc_proxy_create
58 #define lws_ss_get_context lws_sspc_get_context
59 #define lws_ss_rideshare lws_sspc_rideshare
60 #define lws_ss_set_metadata lws_sspc_set_metadata
61 #define lws_ss_get_metadata lws_sspc_get_metadata
62 #define lws_ss_add_peer_tx_credit lws_sspc_add_peer_tx_credit
63 #define lws_ss_get_est_peer_tx_credit lws_sspc_get_est_peer_tx_credit
64 #define lws_ss_start_timeout lws_sspc_start_timeout
65 #define lws_ss_cancel_timeout lws_sspc_cancel_timeout
66 #define lws_ss_to_user_object lws_sspc_to_user_object
67 #define lws_ss_change_handlers lws_sspc_change_handlers
68 #define lws_smd_ss_rx_forward lws_smd_sspc_rx_forward
69 #define lws_ss_server_ack lws_sspc_server_ack
70 #define lws_ss_tag lws_sspc_tag
71 #define _lws_fi_user_ss_fi _lws_fi_user_sspc_fi
72 #define lwsl_ss_get_cx lwsl_sspc_get_cx
73 
74 #undef lwsl_ss
75 #define lwsl_ss lwsl_sspc
76 
77 #undef lwsl_hexdump_ss
78 #define lwsl_hexdump_ss lwsl_hexdump_sspc
79 #endif
80 
81 LWS_VISIBLE LWS_EXTERN void
82 lws_log_prepend_sspc(struct lws_log_cx *cx, void *obj, char **p, char *e);
83 
84 LWS_VISIBLE LWS_EXTERN struct lws_log_cx *
85 lwsl_sspc_get_cx(struct lws_sspc_handle *ss);
86 
87 #define lwsl_sspc(_h, _fil, ...) \
88  _lws_log_cx(lwsl_sspc_get_cx(_h), lws_log_prepend_sspc, _h, \
89  _fil, __func__, __VA_ARGS__)
90 
91 #define lwsl_hexdump_sspc(_h, _fil, _buf, _len) \
92  lwsl_hexdump_level_cx(lwsl_sspc_get_cx(_h), \
93  lws_log_prepend_sspc, \
94  _h, _fil, _buf, _len)
95 
96 /*
97  * lwsl_sspc
98  */
99 
100 #if (_LWS_ENABLED_LOGS & LLL_ERR)
101 #define lwsl_sspc_err(_w, ...) lwsl_sspc(_w, LLL_ERR, __VA_ARGS__)
102 #else
103 #define lwsl_sspc_err(_w, ...) do {} while(0)
104 #endif
105 
106 #if (_LWS_ENABLED_LOGS & LLL_WARN)
107 #define lwsl_sspc_warn(_w, ...) lwsl_sspc(_w, LLL_WARN, __VA_ARGS__)
108 #else
109 #define lwsl_sspc_warn(_w, ...) do {} while(0)
110 #endif
111 
112 #if (_LWS_ENABLED_LOGS & LLL_NOTICE)
113 #define lwsl_sspc_notice(_w, ...) lwsl_sspc(_w, LLL_NOTICE, __VA_ARGS__)
114 #else
115 #define lwsl_sspc_notice(_w, ...) do {} while(0)
116 #endif
117 
118 #if (_LWS_ENABLED_LOGS & LLL_INFO)
119 #define lwsl_sspc_info(_w, ...) lwsl_sspc(_w, LLL_INFO, __VA_ARGS__)
120 #else
121 #define lwsl_sspc_info(_w, ...) do {} while(0)
122 #endif
123 
124 #if (_LWS_ENABLED_LOGS & LLL_DEBUG)
125 #define lwsl_sspc_debug(_w, ...) lwsl_sspc(_w, LLL_DEBUG, __VA_ARGS__)
126 #else
127 #define lwsl_sspc_debug(_w, ...) do {} while(0)
128 #endif
129 
130 #if (_LWS_ENABLED_LOGS & LLL_PARSER)
131 #define lwsl_sspc_parser(_w, ...) lwsl_sspc(_w, LLL_PARSER, __VA_ARGS__)
132 #else
133 #define lwsl_sspc_parser(_w, ...) do {} while(0)
134 #endif
135 
136 #if (_LWS_ENABLED_LOGS & LLL_HEADER)
137 #define lwsl_sspc_header(_w, ...) lwsl_sspc(_w, LLL_HEADER, __VA_ARGS__)
138 #else
139 #define lwsl_sspc_header(_w, ...) do {} while(0)
140 #endif
141 
142 #if (_LWS_ENABLED_LOGS & LLL_EXT)
143 #define lwsl_sspc_ext(_w, ...) lwsl_sspc(_w, LLL_EXT, __VA_ARGS__)
144 #else
145 #define lwsl_sspc_ext(_w, ...) do {} while(0)
146 #endif
147 
148 #if (_LWS_ENABLED_LOGS & LLL_CLIENT)
149 #define lwsl_sspc_client(_w, ...) lwsl_sspc(_w, LLL_CLIENT, __VA_ARGS__)
150 #else
151 #define lwsl_sspc_client(_w, ...) do {} while(0)
152 #endif
153 
154 #if (_LWS_ENABLED_LOGS & LLL_LATENCY)
155 #define lwsl_sspc_latency(_w, ...) lwsl_sspc(_w, LLL_LATENCY, __VA_ARGS__)
156 #else
157 #define lwsl_sspc_latency(_w, ...) do {} while(0)
158 #endif
159 
160 #if (_LWS_ENABLED_LOGS & LLL_THREAD)
161 #define lwsl_sspc_thread(_w, ...) lwsl_sspc(_w, LLL_THREAD, __VA_ARGS__)
162 #else
163 #define lwsl_sspc_thread(_w, ...) do {} while(0)
164 #endif
165 
166 #if (_LWS_ENABLED_LOGS & LLL_USER)
167 #define lwsl_sspc_user(_w, ...) lwsl_sspc(_w, LLL_USER, __VA_ARGS__)
168 #else
169 #define lwsl_sspc_user(_w, ...) do {} while(0)
170 #endif
171 
172 #define lwsl_hexdump_sspc_err(_v, ...) lwsl_hexdump_sspc(_v, LLL_ERR, __VA_ARGS__)
173 #define lwsl_hexdump_sspc_warn(_v, ...) lwsl_hexdump_sspc(_v, LLL_WARN, __VA_ARGS__)
174 #define lwsl_hexdump_sspc_notice(_v, ...) lwsl_hexdump_sspc(_v, LLL_NOTICE, __VA_ARGS__)
175 #define lwsl_hexdump_sspc_info(_v, ...) lwsl_hexdump_sspc(_v, LLL_INFO, __VA_ARGS__)
176 #define lwsl_hexdump_sspc_debug(_v, ...) lwsl_hexdump_sspc(_v, LLL_DEBUG, __VA_ARGS__)
177 
178 /*
179  * How lws refers to your per-proxy-link private data... not allocated or freed
180  * by lws, nor used except to pass a pointer to it through to ops callbacks
181  * below. Should be set to your transport private instance object, it's set to
182  * the wsi for the wsi transport. Notice it is provided as a ** (ptr-to-ptr) in
183  * most apis.
184  */
185 
186 /*
187  * Stub context when using LWS_ONLY_SSPC
188  */
189 
191  lws_txp_path_client_t txp_cpath;
192  lws_dll2_owner_t ss_client_owner;
193  uint32_t ssidx;
194 };
195 
196 #if defined(STANDALONE)
197 #define lws_context lws_context_standalone
199 #endif
200 
201 LWS_VISIBLE LWS_EXTERN int
202 lws_sspc_create(struct lws_context *context, int tsi, const lws_ss_info_t *ssi,
203  void *opaque_user_data, struct lws_sspc_handle **ppss,
204  void *reserved, const char **ppayload_fmt);
205 
213 LWS_VISIBLE LWS_EXTERN void
214 lws_sspc_destroy(struct lws_sspc_handle **ppss);
215 
225 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
226 lws_sspc_request_tx(struct lws_sspc_handle *pss);
227 
245 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
246 lws_sspc_request_tx_len(struct lws_sspc_handle *h, unsigned long len);
247 
256 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
257 lws_sspc_client_connect(struct lws_sspc_handle *h);
258 
267 LWS_VISIBLE LWS_EXTERN int
268 lws_sspc_proxy_create(struct lws_context *context);
269 
279 LWS_VISIBLE LWS_EXTERN struct lws_context *
280 lws_sspc_get_context(struct lws_sspc_handle *h);
281 
282 #if defined(LWS_WITH_NETWORK)
283 extern const struct lws_protocols lws_sspc_protocols[2];
284 #endif
285 
286 LWS_VISIBLE LWS_EXTERN const char *
287 lws_sspc_rideshare(struct lws_sspc_handle *h);
288 
289 
313 LWS_VISIBLE LWS_EXTERN int
314 lws_sspc_set_metadata(struct lws_sspc_handle *h, const char *name,
315  const void *value, size_t len);
316 
317 LWS_VISIBLE LWS_EXTERN int
318 lws_sspc_get_metadata(struct lws_sspc_handle *h, const char *name,
319  const void **value, size_t *len);
320 
321 LWS_VISIBLE LWS_EXTERN int
322 lws_sspc_add_peer_tx_credit(struct lws_sspc_handle *h, int32_t add);
323 
324 LWS_VISIBLE LWS_EXTERN int
325 lws_sspc_get_est_peer_tx_credit(struct lws_sspc_handle *h);
326 
327 LWS_VISIBLE LWS_EXTERN void
328 lws_sspc_start_timeout(struct lws_sspc_handle *h, unsigned int timeout_ms);
329 
330 LWS_VISIBLE LWS_EXTERN void
331 lws_sspc_cancel_timeout(struct lws_sspc_handle *h);
332 
333 LWS_VISIBLE LWS_EXTERN void *
334 lws_sspc_to_user_object(struct lws_sspc_handle *h);
335 
336 LWS_VISIBLE LWS_EXTERN void
337 lws_sspc_change_handlers(struct lws_sspc_handle *h,
338  lws_sscb_rx rx,lws_sscb_tx tx, lws_sscb_state state);
339 
340 LWS_VISIBLE LWS_EXTERN void
341 lws_sspc_server_ack(struct lws_sspc_handle *h, int nack);
342 
343 
344 /*
345  * Helpers offered by lws to handle transport SSPC-side proxy link events
346  */
347 
355 LWS_VISIBLE LWS_EXTERN const char *
356 lws_sspc_tag(struct lws_sspc_handle *h);
357 
358 
359 #if defined(STANDALONE)
360 #undef lws_context
361 #endif
362 
363 
Definition: lws-secure-streams-client.h:190
Definition: lws-dll2.h:203
Definition: lws-logs.h:80
Definition: lws-protocols-plugins.h:44
const char * name
Definition: lws-protocols-plugins.h:45
Definition: lws-secure-streams.h:197