components/esp_local_ctrl/src/esp_local_ctrl_priv.h (ESP-IDF)

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

// 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 <esp_err.h> #include <protocomm.h> #include <esp_local_ctrl.h> /** * @brief `esp_local_ctrl` transport specific structure * * Every supported transport layer should have the following functions * implemented for starting, stopping and configuring a protocomm service */ struct esp_local_ctrl_transport { /** * Handler for starting a protocomm service as per specified configuration */ esp_err_t (*start_service) (protocomm_t *pc, const esp_local_ctrl_transport_config_t *config); /** * Handler for stopping a protocomm service */ void (*stop_service) (protocomm_t *pc); /** * Handler for creating a copy of the transport specific configuration */ esp_err_t (*copy_config) (esp_local_ctrl_transport_config_t *dest_config, const esp_local_ctrl_transport_config_t *src_config); /** * Handler for allocating resources corresponding to a protocomm endpoint. * Usually when adding a new endpoint `protocomm_endpoint_add()` API is used, * but the transport layer may need to perform resource allocation for * each endpoint, prior to starting the protocomm instance. This handler * is useful in that case, as it is called before `start_service()`. */ esp_err_t (*declare_ep) (esp_local_ctrl_transport_config_t *config, const char *ep_name, uint16_t ep_uuid); /** * Handler for freeing a transport specific configuration */ void (*free_config) (esp_local_ctrl_transport_config_t *config); }; /** * @brief Protocomm handler for `esp_local_ctrl` * * This is the handler which is responsible for processing incoming requests * over a protocomm channel, then invokes one of the following functions * depending upon the request type: * - `esp_local_ctrl_get_prop_count()` * - `esp_local_ctrl_get_prop_values()` * -` esp_local_ctrl_set_prop_values()` * The output of the above functions are used to form the response messages * corresponding to request types. The formed response messages are packed and * sent back via the protocomm channel. * * @param[in] session_id A number to identify an ongoing session between * device and client * @param[in] inbuf Buffer which holds serialized / packed request data * @param[in] inlen Length of input buffer * @param[out] outbuf Buffer which holds serialized / packed response data * @param[out] outlen Length of output buffer * @param[in] priv_data Private data associated with `esp_local_ctrl` endpoint * * @return * - ESP_OK : Success * - ESP_FAIL : Failure */ esp_err_t esp_local_ctrl_data_handler(uint32_t session_id, const uint8_t *inbuf, ssize_t inlen, uint8_t **outbuf, ssize_t *outlen, void *priv_data); /** * @brief Use this for obtaining total number of properties registered * with `esp_local_ctrl` service * * @param[out] count Pointer to variable where the result is to be stored * * @return * - ESP_OK : Success * - ESP_FAIL : Failure */ esp_err_t esp_local_ctrl_get_prop_count(size_t *count); /** * @brief Get descriptions and values of multiple properties at the same time. * The properties are requested by indices. This internally calls the * `get_prop_values` handler specified in the `esp_local_ctrl_handlers_t` * structure. Since `get_prop_values` accepts property structure, the * indices are first converted to the corresponding `esp_local_ctrl_prop_t` * internally. * * @param[in] total_indices The number of elements in the `indices` array argument * @param[in] indices An array of indices, that specify which properties to get * @param[out] props A pre-allocated array of empty property structures, elements of * which are to be populated with names, types and flags of those * properties which correspond to the provided indices * @param[out] values A pre-allocated array of empty value structures, elements of * which are to be populated with values and sizes of those * properties which correspond to the provided indices * * @return * - ESP_OK : Success * - ESP_FAIL : Failure */ esp_err_t esp_local_ctrl_get_prop_values(size_t total_indices, uint32_t *indices, esp_local_ctrl_prop_t *props, esp_local_ctrl_prop_val_t *values); /** * @brief Set values of multiple properties at the same time. The properties to * set are specified by indices. This internally calls the `set_prop_values` * handler specified in the `esp_local_ctrl_handlers_t` structure. Since * `set_prop_values` accepts property structures, the indices are first * converted to the corresponding `esp_local_ctrl_prop_t` internally. * * @param[in] total_indices The number of elements in the `indices` array argument * @param[in] indices An array of indices, that specify which properties to set * @param[in] values A array of values. Every value should have the correct * size, if it is for setting a fixed size property, else * error will be generated and none of the properties will * be set to any of the given values * * @return * - ESP_OK : Success * - ESP_FAIL : Failure */ esp_err_t esp_local_ctrl_set_prop_values(size_t total_indices, uint32_t *indices, const esp_local_ctrl_prop_val_t *values); #ifdef __cplusplus } #endif