/*
* SPDX-FileCopyrightText: 2019-2022 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_BLUEDROID_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