1 // Copyright 2019 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include <esp_err.h> 22 #include <protocomm.h> 23 #include <esp_local_ctrl.h> 24 25 /** 26 * @brief `esp_local_ctrl` transport specific structure 27 * 28 * Every supported transport layer should have the following functions 29 * implemented for starting, stopping and configuring a protocomm service 30 */ 31 struct esp_local_ctrl_transport { 32 /** 33 * Handler for starting a protocomm service as per specified configuration 34 */ 35 esp_err_t (*start_service) (protocomm_t *pc, 36 const esp_local_ctrl_transport_config_t *config); 37 38 /** 39 * Handler for stopping a protocomm service 40 */ 41 void (*stop_service) (protocomm_t *pc); 42 43 /** 44 * Handler for creating a copy of the transport specific configuration 45 */ 46 esp_err_t (*copy_config) (esp_local_ctrl_transport_config_t *dest_config, 47 const esp_local_ctrl_transport_config_t *src_config); 48 49 /** 50 * Handler for allocating resources corresponding to a protocomm endpoint. 51 * Usually when adding a new endpoint `protocomm_endpoint_add()` API is used, 52 * but the transport layer may need to perform resource allocation for 53 * each endpoint, prior to starting the protocomm instance. This handler 54 * is useful in that case, as it is called before `start_service()`. 55 */ 56 esp_err_t (*declare_ep) (esp_local_ctrl_transport_config_t *config, 57 const char *ep_name, uint16_t ep_uuid); 58 59 /** 60 * Handler for freeing a transport specific configuration 61 */ 62 void (*free_config) (esp_local_ctrl_transport_config_t *config); 63 }; 64 65 /** 66 * @brief Protocomm handler for `esp_local_ctrl` 67 * 68 * This is the handler which is responsible for processing incoming requests 69 * over a protocomm channel, then invokes one of the following functions 70 * depending upon the request type: 71 * - `esp_local_ctrl_get_prop_count()` 72 * - `esp_local_ctrl_get_prop_values()` 73 * -` esp_local_ctrl_set_prop_values()` 74 * The output of the above functions are used to form the response messages 75 * corresponding to request types. The formed response messages are packed and 76 * sent back via the protocomm channel. 77 * 78 * @param[in] session_id A number to identify an ongoing session between 79 * device and client 80 * @param[in] inbuf Buffer which holds serialized / packed request data 81 * @param[in] inlen Length of input buffer 82 * @param[out] outbuf Buffer which holds serialized / packed response data 83 * @param[out] outlen Length of output buffer 84 * @param[in] priv_data Private data associated with `esp_local_ctrl` endpoint 85 * 86 * @return 87 * - ESP_OK : Success 88 * - ESP_FAIL : Failure 89 */ 90 esp_err_t esp_local_ctrl_data_handler(uint32_t session_id, const uint8_t *inbuf, ssize_t inlen, 91 uint8_t **outbuf, ssize_t *outlen, void *priv_data); 92 93 /** 94 * @brief Use this for obtaining total number of properties registered 95 * with `esp_local_ctrl` service 96 * 97 * @param[out] count Pointer to variable where the result is to be stored 98 * 99 * @return 100 * - ESP_OK : Success 101 * - ESP_FAIL : Failure 102 */ 103 esp_err_t esp_local_ctrl_get_prop_count(size_t *count); 104 105 /** 106 * @brief Get descriptions and values of multiple properties at the same time. 107 * The properties are requested by indices. This internally calls the 108 * `get_prop_values` handler specified in the `esp_local_ctrl_handlers_t` 109 * structure. Since `get_prop_values` accepts property structure, the 110 * indices are first converted to the corresponding `esp_local_ctrl_prop_t` 111 * internally. 112 * 113 * @param[in] total_indices The number of elements in the `indices` array argument 114 * @param[in] indices An array of indices, that specify which properties to get 115 * @param[out] props A pre-allocated array of empty property structures, elements of 116 * which are to be populated with names, types and flags of those 117 * properties which correspond to the provided indices 118 * @param[out] values A pre-allocated array of empty value structures, elements of 119 * which are to be populated with values and sizes of those 120 * properties which correspond to the provided indices 121 * 122 * @return 123 * - ESP_OK : Success 124 * - ESP_FAIL : Failure 125 */ 126 esp_err_t esp_local_ctrl_get_prop_values(size_t total_indices, uint32_t *indices, 127 esp_local_ctrl_prop_t *props, 128 esp_local_ctrl_prop_val_t *values); 129 130 /** 131 * @brief Set values of multiple properties at the same time. The properties to 132 * set are specified by indices. This internally calls the `set_prop_values` 133 * handler specified in the `esp_local_ctrl_handlers_t` structure. Since 134 * `set_prop_values` accepts property structures, the indices are first 135 * converted to the corresponding `esp_local_ctrl_prop_t` internally. 136 * 137 * @param[in] total_indices The number of elements in the `indices` array argument 138 * @param[in] indices An array of indices, that specify which properties to set 139 * @param[in] values A array of values. Every value should have the correct 140 * size, if it is for setting a fixed size property, else 141 * error will be generated and none of the properties will 142 * be set to any of the given values 143 * 144 * @return 145 * - ESP_OK : Success 146 * - ESP_FAIL : Failure 147 */ 148 esp_err_t esp_local_ctrl_set_prop_values(size_t total_indices, uint32_t *indices, 149 const esp_local_ctrl_prop_val_t *values); 150 151 #ifdef __cplusplus 152 } 153 #endif 154
