Outline ![]()
Files ![]()
loading...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
/*
* SPDX-FileCopyrightText: 2019-2023 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#ifdef __cplusplus
extern "C" {
#endif
#include <sdkconfig.h>
#ifdef CONFIG_ESP_HTTPS_SERVER_ENABLE
#include <esp_https_server.h>
#else
#include <esp_http_server.h>
#endif
#include <protocomm.h>
/**
* @brief Property description data structure, which is to be populated
* and passed to the `esp_local_ctrl_add_property()` function
*
* Once a property is added, its structure is available for read-only access
* inside `get_prop_values()` and `set_prop_values()` handlers.
*/
typedef struct esp_local_ctrl_prop {
/**
* Unique name of property
*/
char *name;
/**
* Type of property. This may be set to application defined enums
*/
uint32_t type;
/**
* Size of the property value, which:
* - if zero, the property can have values of variable size
* - if non-zero, the property can have values of fixed size only,
* therefore, checks are performed internally by esp_local_ctrl
* when setting the value of such a property
*/
size_t size;
/**
* Flags set for this property. This could be a bit field.
* A flag may indicate property behavior, e.g. read-only / constant
*/
uint32_t flags;
/**
* Pointer to some context data relevant for this property. This will
* be available for use inside the `get_prop_values` and `set_prop_values`
* handlers as a part of this property structure. When set, this is valid
* throughout the lifetime of a property, till either the property is
* removed or the esp_local_ctrl service is stopped.
*/
void *ctx;
/**
* Function used by esp_local_ctrl to internally free the property
* context when `esp_local_ctrl_remove_property()` or
* `esp_local_ctrl_stop()` is called.
*/
void (*ctx_free_fn)(void *ctx);
} esp_local_ctrl_prop_t;
/**
* @brief Property value data structure. This gets passed to the
* `get_prop_values()` and `set_prop_values()` handlers for
* the purpose of retrieving or setting the present value
* of a property.
*/
typedef struct esp_local_ctrl_prop_val {
/**
* Pointer to memory holding property value
*/
void *data;
/**
* Size of property value
*/
size_t size;
/**
* This may be set by the application in `get_prop_values()` handler
* to tell `esp_local_ctrl` to call this function on the data pointer
* above, for freeing its resources after sending the `get_prop_values`
* response.
*/
void (*free_fn)(void *data);
} esp_local_ctrl_prop_val_t;
/**
* @brief Handlers for receiving and responding to local
* control commands for getting and setting properties.
*/
typedef struct esp_local_ctrl_handlers {
/**
* @brief Handler function to be implemented for retrieving current
* values of properties
*
* @note If any of the properties have fixed sizes, the size field of
* corresponding element in `prop_values` need to be set
*
* @param[in] props_count Total elements in the props array
* @param[in] props Array of properties, the current values for which
* have been requested by the client
* @param[out] prop_values Array of empty property values, the elements of
* which need to be populated with the current values
* of those properties specified by props argument
* @param[in] usr_ctx This provides value of the `usr_ctx` field of
* `esp_local_ctrl_handlers_t` structure
*
* @return Returning different error codes will convey the corresponding
* protocol level errors to the client :
* - ESP_OK : Success
* - ESP_ERR_INVALID_ARG : InvalidArgument
* - ESP_ERR_INVALID_STATE : InvalidProto
* - All other error codes : InternalError
*/
esp_err_t (*get_prop_values)(size_t props_count,
const esp_local_ctrl_prop_t props[],
esp_local_ctrl_prop_val_t prop_values[],
void *usr_ctx);
/**
* @brief Handler function to be implemented for changing values of properties
*
* @note If any of the properties have variable sizes, the size field
* of the corresponding element in `prop_values` must be checked
* explicitly before making any assumptions on the size.
*
* @param[in] props_count Total elements in the props array
* @param[in] props Array of properties, the values for which the
* client requests to change
* @param[in] prop_values Array of property values, the elements of which
* need to be used for updating those properties
* specified by props argument
* @param[in] usr_ctx This provides value of the `usr_ctx` field of
* `esp_local_ctrl_handlers_t` structure
*
* @return Returning different error codes will convey the corresponding
* protocol level errors to the client :
* - ESP_OK : Success
* - ESP_ERR_INVALID_ARG : InvalidArgument
* - ESP_ERR_INVALID_STATE : InvalidProto
* - All other error codes : InternalError
*/
esp_err_t (*set_prop_values)(size_t props_count,
const esp_local_ctrl_prop_t props[],
const esp_local_ctrl_prop_val_t prop_values[],
void *usr_ctx);
/**
* Context pointer to be passed to above handler functions upon invocation.
* This is different from the property level context, as this is valid
* throughout the lifetime of the `esp_local_ctrl` service, and freed only
* when the service is stopped.
*/
void *usr_ctx;
/**
* Pointer to function which will be internally invoked on `usr_ctx` for
* freeing the context resources when `esp_local_ctrl_stop()` is called.
*/
void (*usr_ctx_free_fn)(void *usr_ctx);
} esp_local_ctrl_handlers_t;
/**
* @brief Transport mode (BLE / HTTPD) over which the service will be provided
*
* This is forward declaration of a private structure, implemented internally
* by `esp_local_ctrl`.
*/
typedef struct esp_local_ctrl_transport esp_local_ctrl_transport_t;
/**
* @brief Function for obtaining BLE transport mode
*/
const esp_local_ctrl_transport_t *esp_local_ctrl_get_transport_ble(void);
/**
* @brief Function for obtaining HTTPD transport mode
*/
const esp_local_ctrl_transport_t *esp_local_ctrl_get_transport_httpd(void);
#define ESP_LOCAL_CTRL_TRANSPORT_BLE esp_local_ctrl_get_transport_ble()
#define ESP_LOCAL_CTRL_TRANSPORT_HTTPD esp_local_ctrl_get_transport_httpd()
/**
* @brief Configuration for transport mode BLE
*
* This is a forward declaration for `protocomm_ble_config_t`.
* To use this, application must set CONFIG_BT_ENABLED
* and include `protocomm_ble.h`.
*/
typedef struct protocomm_ble_config esp_local_ctrl_transport_config_ble_t;
/**
* @brief Configuration for transport mode HTTPD
*
* This is a forward declaration for `httpd_ssl_config_t` (for HTTPS)
* or `httpd_config_t` (for HTTP)
*/
#ifdef CONFIG_ESP_HTTPS_SERVER_ENABLE
/* To use this, application must set CONFIG_ESP_HTTPS_SERVER_ENABLE
* and include `esp_https_server.h`
*/
typedef struct httpd_ssl_config esp_local_ctrl_transport_config_httpd_t;
#else
typedef struct httpd_config esp_local_ctrl_transport_config_httpd_t;
#endif
/**
* @brief Transport mode (BLE / HTTPD) configuration
*/
typedef union {
/**
* This is same as `protocomm_ble_config_t`. See `protocomm_ble.h` for
* available configuration parameters.
*/
esp_local_ctrl_transport_config_ble_t *ble;
/**
* This is same as `httpd_ssl_config_t`. See `esp_https_server.h` for
* available configuration parameters.
*/
esp_local_ctrl_transport_config_httpd_t *httpd;
} esp_local_ctrl_transport_config_t;
/**
* @brief Security types for esp_local_control
*/
typedef enum esp_local_ctrl_proto_sec {
PROTOCOM_SEC0 = 0,
PROTOCOM_SEC1,
PROTOCOM_SEC2,
PROTOCOM_SEC_CUSTOM,
} esp_local_ctrl_proto_sec_t;
typedef protocomm_security1_params_t esp_local_ctrl_security1_params_t;
typedef protocomm_security2_params_t esp_local_ctrl_security2_params_t;
/**
* Protocom security configs
*/
typedef struct esp_local_ctrl_proto_sec_cfg {
/**
* This sets protocom security version, sec0/sec1 or custom
* If custom, user must provide handle via `proto_sec_custom_handle` below
*/
esp_local_ctrl_proto_sec_t version;
/**
* Custom security handle if security is set custom via `proto_sec` above
* This handle must follow `protocomm_security_t` signature
*/
void *custom_handle;
/* Anonymous union */
union {
/**
* Proof of possession to be used for local control. Could be NULL.
*/
const void *pop __attribute__((deprecated("use sec_params field instead")));
/**
* Pointer to security params (NULL if not needed).
* This is not needed for protocomm security 0
* This pointer should hold the struct of type
* esp_local_ctrl_security1_params_t for protocomm security 1
* and esp_local_ctrl_security2_params_t for protocomm security 2 respectively. Could be NULL.
*/
const void *sec_params;
};
} esp_local_ctrl_proto_sec_cfg_t;
/**
* @brief Configuration structure to pass to `esp_local_ctrl_start()`
*/
typedef struct esp_local_ctrl_config {
/**
* Transport layer over which service will be provided
*/
const esp_local_ctrl_transport_t *transport;
/**
* Transport layer over which service will be provided
*/
esp_local_ctrl_transport_config_t transport_config;
/**
* Security version and POP
*/
esp_local_ctrl_proto_sec_cfg_t proto_sec;
/**
* Register handlers for responding to get/set requests on properties
*/
esp_local_ctrl_handlers_t handlers;
/**
* This limits the number of properties that are available at a time
*/
size_t max_properties;
} esp_local_ctrl_config_t;
/**
* @brief Start local control service
*
* @param[in] config Pointer to configuration structure
*
* @return
* - ESP_OK : Success
* - ESP_FAIL : Failure
*/
esp_err_t esp_local_ctrl_start(const esp_local_ctrl_config_t *config);
/**
* @brief Stop local control service
*/
esp_err_t esp_local_ctrl_stop(void);
/**
* @brief Add a new property
*
* This adds a new property and allocates internal resources for it.
* The total number of properties that could be added is limited by
* configuration option `max_properties`
*
* @param[in] prop Property description structure
*
* @return
* - ESP_OK : Success
* - ESP_FAIL : Failure
*/
esp_err_t esp_local_ctrl_add_property(const esp_local_ctrl_prop_t *prop);
/**
* @brief Remove a property
*
* This finds a property by name, and releases the internal resources
* which are associated with it.
*
* @param[in] name Name of the property to remove
*
* @return
* - ESP_OK : Success
* - ESP_ERR_NOT_FOUND : Failure
*/
esp_err_t esp_local_ctrl_remove_property(const char *name);
/**
* @brief Get property description structure by name
*
* This API may be used to get a property's context structure
* `esp_local_ctrl_prop_t` when its name is known
*
* @param[in] name Name of the property to find
*
* @return
* - Pointer to property
* - NULL if not found
*/
const esp_local_ctrl_prop_t *esp_local_ctrl_get_property(const char *name);
/**
* @brief Register protocomm handler for a custom endpoint
*
* This API can be called by the application to register a protocomm handler
* for an endpoint after the local control service has started.
*
* @note In case of BLE transport the names and uuids of all custom
* endpoints must be provided beforehand as a part of the `protocomm_ble_config_t`
* structure set in `esp_local_ctrl_config_t`, and passed to `esp_local_ctrl_start()`.
*
* @param[in] ep_name Name of the endpoint
* @param[in] handler Endpoint handler function
* @param[in] user_ctx User data
*
* @return
* - ESP_OK : Success
* - ESP_FAIL : Failure
*/
esp_err_t esp_local_ctrl_set_handler(const char *ep_name,
protocomm_req_handler_t handler,
void *user_ctx);
#ifdef __cplusplus
}
#endif
Details ![]()
Show: from Types: Columns: ![]( "Show Project Names")
![]( "Show Locations")
![]( "Show Referring Symbols")
![]( "Show Scope")
This file uses the notable symbols shown below. Click anywhere in the file to view more details.