86e9acc2c9
New APIs: * protocomm_open_session() * protocomm_close_session() This allows external applications using protocomm to manually create and close sessions. These internally call the new_transport_session() and close_transport_session() APIs implemented by the security scheme in use. Updated unit tests with usage of new APIs
269 lines
9.8 KiB
C
269 lines
9.8 KiB
C
// Copyright 2018 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
|
|
|
|
#include <protocomm_security.h>
|
|
#include <esp_err.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Function prototype for protocomm endpoint handler
|
|
*/
|
|
typedef esp_err_t (*protocomm_req_handler_t)(
|
|
uint32_t session_id, /*!< Session ID for identifying protocomm client */
|
|
const uint8_t *inbuf, /*!< Pointer to user provided input data buffer */
|
|
ssize_t inlen, /*!< Length o the input buffer */
|
|
uint8_t **outbuf, /*!< Pointer to output buffer allocated by handler */
|
|
ssize_t *outlen, /*!< Length of the allocated output buffer */
|
|
void *priv_data /*!< Private data passed to the handler (NULL if not used) */
|
|
);
|
|
|
|
/**
|
|
* @brief This structure corresponds to a unique instance of protocomm
|
|
* returned when the API `protocomm_new()` is called. The remaining
|
|
* Protocomm APIs require this object as the first parameter.
|
|
*
|
|
* @note Structure of the protocomm object is kept private
|
|
*/
|
|
typedef struct protocomm protocomm_t;
|
|
|
|
/**
|
|
* @brief Create a new protocomm instance
|
|
*
|
|
* This API will return a new dynamically allocated protocomm instance
|
|
* with all elements of the protocomm_t structure initialized to NULL.
|
|
*
|
|
* @return
|
|
* - protocomm_t* : On success
|
|
* - NULL : No memory for allocating new instance
|
|
*/
|
|
protocomm_t *protocomm_new();
|
|
|
|
/**
|
|
* @brief Delete a protocomm instance
|
|
*
|
|
* This API will deallocate a protocomm instance that was created
|
|
* using `protocomm_new()`.
|
|
*
|
|
* @param[in] pc Pointer to the protocomm instance to be deleted
|
|
*/
|
|
void protocomm_delete(protocomm_t *pc);
|
|
|
|
/**
|
|
* @brief Add endpoint request handler for a protocomm instance
|
|
*
|
|
* This API will bind an endpoint handler function to the specified
|
|
* endpoint name, along with any private data that needs to be pass to
|
|
* the handler at the time of call.
|
|
*
|
|
* @note
|
|
* - An endpoint must be bound to a valid protocomm instance,
|
|
* created using `protocomm_new()`.
|
|
* - This function internally calls the registered `add_endpoint()`
|
|
* function of the selected transport which is a member of the
|
|
* protocomm_t instance structure.
|
|
*
|
|
* @param[in] pc Pointer to the protocomm instance
|
|
* @param[in] ep_name Endpoint identifier(name) string
|
|
* @param[in] h Endpoint handler function
|
|
* @param[in] priv_data Pointer to private data to be passed as a
|
|
* parameter to the handler function on call.
|
|
* Pass NULL if not needed.
|
|
*
|
|
* @return
|
|
* - ESP_OK : Success
|
|
* - ESP_FAIL : Error adding endpoint / Endpoint with this name already exists
|
|
* - ESP_ERR_NO_MEM : Error allocating endpoint resource
|
|
* - ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
|
|
*/
|
|
esp_err_t protocomm_add_endpoint(protocomm_t *pc, const char *ep_name,
|
|
protocomm_req_handler_t h, void *priv_data);
|
|
|
|
/**
|
|
* @brief Remove endpoint request handler for a protocomm instance
|
|
*
|
|
* This API will remove a registered endpoint handler identified by
|
|
* an endpoint name.
|
|
*
|
|
* @note
|
|
* - This function internally calls the registered `remove_endpoint()`
|
|
* function which is a member of the protocomm_t instance structure.
|
|
*
|
|
* @param[in] pc Pointer to the protocomm instance
|
|
* @param[in] ep_name Endpoint identifier(name) string
|
|
*
|
|
* @return
|
|
* - ESP_OK : Success
|
|
* - ESP_ERR_NOT_FOUND : Endpoint with specified name doesn't exist
|
|
* - ESP_ERR_INVALID_ARG : Null instance/name arguments
|
|
*/
|
|
esp_err_t protocomm_remove_endpoint(protocomm_t *pc, const char *ep_name);
|
|
|
|
/**
|
|
* @brief Allocates internal resources for new transport session
|
|
*
|
|
* @note
|
|
* - An endpoint must be bound to a valid protocomm instance,
|
|
* created using `protocomm_new()`.
|
|
*
|
|
* @param[in] pc Pointer to the protocomm instance
|
|
* @param[in] session_id Unique ID for a communication session
|
|
*
|
|
* @return
|
|
* - ESP_OK : Request handled successfully
|
|
* - ESP_ERR_NO_MEM : Error allocating internal resource
|
|
* - ESP_ERR_INVALID_ARG : Null instance/name arguments
|
|
*/
|
|
esp_err_t protocomm_open_session(protocomm_t *pc, uint32_t session_id);
|
|
|
|
/**
|
|
* @brief Frees internal resources used by a transport session
|
|
*
|
|
* @note
|
|
* - An endpoint must be bound to a valid protocomm instance,
|
|
* created using `protocomm_new()`.
|
|
*
|
|
* @param[in] pc Pointer to the protocomm instance
|
|
* @param[in] session_id Unique ID for a communication session
|
|
*
|
|
* @return
|
|
* - ESP_OK : Request handled successfully
|
|
* - ESP_ERR_INVALID_ARG : Null instance/name arguments
|
|
*/
|
|
esp_err_t protocomm_close_session(protocomm_t *pc, uint32_t session_id);
|
|
|
|
/**
|
|
* @brief Calls the registered handler of an endpoint session
|
|
* for processing incoming data and generating the response
|
|
*
|
|
* @note
|
|
* - An endpoint must be bound to a valid protocomm instance,
|
|
* created using `protocomm_new()`.
|
|
* - Resulting output buffer must be deallocated by the caller.
|
|
*
|
|
* @param[in] pc Pointer to the protocomm instance
|
|
* @param[in] ep_name Endpoint identifier(name) string
|
|
* @param[in] session_id Unique ID for a communication session
|
|
* @param[in] inbuf Input buffer contains input request data which is to be
|
|
* processed by the registered handler
|
|
* @param[in] inlen Length of the input buffer
|
|
* @param[out] outbuf Pointer to internally allocated output buffer,
|
|
* where the resulting response data output from
|
|
* the registered handler is to be stored
|
|
* @param[out] outlen Buffer length of the allocated output buffer
|
|
*
|
|
* @return
|
|
* - ESP_OK : Request handled successfully
|
|
* - ESP_FAIL : Internal error in execution of registered handler
|
|
* - ESP_ERR_NO_MEM : Error allocating internal resource
|
|
* - ESP_ERR_NOT_FOUND : Endpoint with specified name doesn't exist
|
|
* - ESP_ERR_INVALID_ARG : Null instance/name arguments
|
|
*/
|
|
esp_err_t protocomm_req_handle(protocomm_t *pc, const char *ep_name, uint32_t session_id,
|
|
const uint8_t *inbuf, ssize_t inlen,
|
|
uint8_t **outbuf, ssize_t *outlen);
|
|
|
|
/**
|
|
* @brief Add endpoint security for a protocomm instance
|
|
*
|
|
* This API will bind a security session establisher to the specified
|
|
* endpoint name, along with any proof of possession that may be required
|
|
* for authenticating a session client.
|
|
*
|
|
* @note
|
|
* - An endpoint must be bound to a valid protocomm instance,
|
|
* created using `protocomm_new()`.
|
|
* - The choice of security can be any `protocomm_security_t` instance.
|
|
* Choices `protocomm_security0` and `protocomm_security1` are readily available.
|
|
*
|
|
* @param[in] pc Pointer to the protocomm instance
|
|
* @param[in] ep_name Endpoint identifier(name) string
|
|
* @param[in] sec Pointer to endpoint security instance
|
|
* @param[in] pop Pointer to proof of possession for authenticating a client
|
|
*
|
|
* @return
|
|
* - ESP_OK : Success
|
|
* - ESP_FAIL : Error adding endpoint / Endpoint with this name already exists
|
|
* - ESP_ERR_INVALID_STATE : Security endpoint already set
|
|
* - ESP_ERR_NO_MEM : Error allocating endpoint resource
|
|
* - ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
|
|
*/
|
|
esp_err_t protocomm_set_security(protocomm_t *pc, const char *ep_name,
|
|
const protocomm_security_t *sec,
|
|
const protocomm_security_pop_t *pop);
|
|
|
|
/**
|
|
* @brief Remove endpoint security for a protocomm instance
|
|
*
|
|
* This API will remove a registered security endpoint identified by
|
|
* an endpoint name.
|
|
*
|
|
* @param[in] pc Pointer to the protocomm instance
|
|
* @param[in] ep_name Endpoint identifier(name) string
|
|
*
|
|
* @return
|
|
* - ESP_OK : Success
|
|
* - ESP_ERR_NOT_FOUND : Endpoint with specified name doesn't exist
|
|
* - ESP_ERR_INVALID_ARG : Null instance/name arguments
|
|
*/
|
|
esp_err_t protocomm_unset_security(protocomm_t *pc, const char *ep_name);
|
|
|
|
/**
|
|
* @brief Set endpoint for version verification
|
|
*
|
|
* This API can be used for setting an application specific protocol
|
|
* version which can be verified by clients through the endpoint.
|
|
*
|
|
* @note
|
|
* - An endpoint must be bound to a valid protocomm instance,
|
|
* created using `protocomm_new()`.
|
|
|
|
* @param[in] pc Pointer to the protocomm instance
|
|
* @param[in] ep_name Endpoint identifier(name) string
|
|
* @param[in] version Version identifier(name) string
|
|
*
|
|
* @return
|
|
* - ESP_OK : Success
|
|
* - ESP_FAIL : Error adding endpoint / Endpoint with this name already exists
|
|
* - ESP_ERR_INVALID_STATE : Version endpoint already set
|
|
* - ESP_ERR_NO_MEM : Error allocating endpoint resource
|
|
* - ESP_ERR_INVALID_ARG : Null instance/name/handler arguments
|
|
*/
|
|
esp_err_t protocomm_set_version(protocomm_t *pc, const char *ep_name,
|
|
const char *version);
|
|
|
|
/**
|
|
* @brief Remove version verification endpoint from a protocomm instance
|
|
*
|
|
* This API will remove a registered version endpoint identified by
|
|
* an endpoint name.
|
|
*
|
|
* @param[in] pc Pointer to the protocomm instance
|
|
* @param[in] ep_name Endpoint identifier(name) string
|
|
*
|
|
* @return
|
|
* - ESP_OK : Success
|
|
* - ESP_ERR_NOT_FOUND : Endpoint with specified name doesn't exist
|
|
* - ESP_ERR_INVALID_ARG : Null instance/name arguments
|
|
*/
|
|
esp_err_t protocomm_unset_version(protocomm_t *pc, const char *ep_name);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|