// Copyright 2019 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#pragma once
#ifdef __cplusplus
extern "C" {
#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`.
* 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;
/**
* @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 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;
/**
* 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