340 lines
11 KiB
C
340 lines
11 KiB
C
// 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
|