diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/components/ble/ble_services/experimental_nrf_ble_ots_c/nrf_ble_ots_c.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/components/ble/ble_services/experimental_nrf_ble_ots_c/nrf_ble_ots_c.h | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/components/ble/ble_services/experimental_nrf_ble_ots_c/nrf_ble_ots_c.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/ble/ble_services/experimental_nrf_ble_ots_c/nrf_ble_ots_c.h new file mode 100644 index 0000000..01e13ba --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/ble/ble_services/experimental_nrf_ble_ots_c/nrf_ble_ots_c.h @@ -0,0 +1,320 @@ +/** + * Copyright (c) 2017 - 2018, Nordic Semiconductor ASA + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modification, + * are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form, except as embedded into a Nordic + * Semiconductor ASA integrated circuit in a product or a software update for + * such product, must reproduce the above copyright notice, this list of + * conditions and the following disclaimer in the documentation and/or other + * materials provided with the distribution. + * + * 3. Neither the name of Nordic Semiconductor ASA nor the names of its + * contributors may be used to endorse or promote products derived from this + * software without specific prior written permission. + * + * 4. This software, with or without modification, must only be used with a + * Nordic Semiconductor ASA integrated circuit. + * + * 5. Any software provided in binary form under this license must not be reverse + * engineered, decompiled, modified and/or disassembled. + * + * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS + * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE + * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ + + /**@file + * + * @defgroup nrf_ble_ots_c Object Transfer Service Client + * @{ + * @ingroup ble_sdk_srv + * @brief Object Transfer Service client module + * + * @details This is the main module of the Object Transfer Service (OTS) client. + */ + +#ifndef NRF_BLE_OTS_C_H__ +#define NRF_BLE_OTS_C_H__ + +#include <stdint.h> +#include "ble_gattc.h" +#include "ble.h" +#include "nrf_error.h" +#include "ble_srv_common.h" +#include "ble_db_discovery.h" +#include "sdk_errors.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/**@brief Macro for defining a ble_ots instance. + * + * @param _name Name of the instance. + * @hideinitializer + */ +#define NRF_BLE_OTS_C_DEF(_name) \ +static nrf_ble_ots_c_t _name; \ +NRF_SDH_BLE_OBSERVER(_name ## _ble_obs, \ + BLE_OTS_C_BLE_OBSERVER_PRIO, \ + nrf_ble_ots_c_on_ble_evt, &_name) \ + +/** @brief Macro for defining multiple ble_ots instances. + * + * @param _name Name of the array of instances. + * @param _cnt Number of instances to define. + * @hideinitializer + */ +#define NRF_BLE_OTS_C_ARRAY_DEF(_name, _cnt) \ +static nrf_ble_ots_c_t _name[_cnt]; \ +NRF_SDH_BLE_OBSERVERS(_name ## _ble_obs, \ + BLE_OTS_C_BLE_OBSERVER_PRIO, \ + nrf_ble_ots_c_on_ble_evt, &_name, _cnt) + + +/** @brief Types of Object Action Control Point Procedures. */ +typedef enum +{ + NRF_BLE_OTS_C_OACP_PROC_CREATE = 0x01, //!< Create object. + NRF_BLE_OTS_C_OACP_PROC_DELETE = 0x02, //!< Delete object. + NRF_BLE_OTS_C_OACP_PROC_CALC_CHKSUM = 0x03, //!< Calculate Checksum. + NRF_BLE_OTS_C_OACP_PROC_EXECUTE = 0x04, //!< Execute Object. + NRF_BLE_OTS_C_OACP_PROC_READ = 0x05, //!< Read object. + NRF_BLE_OTS_C_OACP_PROC_WRITE = 0x06, //!< Write object. + NRF_BLE_OTS_C_OACP_PROC_ABORT = 0x07, //!< Abort object. + NRF_BLE_OTS_C_OACP_PROC_RESP = 0x60 //!< Procedure response. +} ble_ots_c_oacp_proc_type_t; + +/** @brief Object Action Control Point return codes. */ +typedef enum +{ + NRF_BLE_OTS_C_OACP_RES_SUCCESS = 0x01, //!< Success. + NRF_BLE_OTS_C_OACP_RES_OPCODE_NOT_SUP = 0x02, //!< Not supported + NRF_BLE_OTS_C_OACP_RES_INV_PARAM = 0x03, //!< Invalid parameter + NRF_BLE_OTS_C_OACP_RES_INSUFF_RES = 0x04, //!< Insufficient resources. + NRF_BLE_OTS_C_OACP_RES_INV_OBJ = 0x05, //!< Invalid object. + NRF_BLE_OTS_C_OACP_RES_CHAN_UNAVAIL = 0x06, //!< Channel unavailable. + NRF_BLE_OTS_C_OACP_RES_UNSUP_TYPE = 0x07, //!< Unsupported procedure. + NRF_BLE_OTS_C_OACP_RES_NOT_PERMITTED = 0x08, //!< Procedure not permitted. + NRF_BLE_OTS_C_OACP_RES_OBJ_LOCKED = 0x09, //!< Object locked. + NRF_BLE_OTS_C_OACP_RES_OPER_FAILED = 0x0A //!< Operation Failed. +} ble_ots_c_oacp_res_code_t; + +/**@brief Type of the Object Transfer Service client event. + */ +typedef enum +{ + NRF_BLE_OTS_C_EVT_DISCOVERY_FAILED, //!< Event indicating that the Object Transfer Service has not been found on the peer. + NRF_BLE_OTS_C_EVT_DISCOVERY_COMPLETE, //!< Event indicating that the Object Transfer Service is present on the peer device. + NRF_BLE_OTS_C_EVT_DISCONN_COMPLETE, //!< Event indicating that the Object Transfer Service client module has finished processing the BLE_GAP_EVT_DISCONNECTED event. The event can be used by the application to do clean up related to the Object Transfer Service client. + NRF_BLE_OTS_C_EVT_FEATURE_READ_RESP, //!< Event indicating that the feature characteristic was read, The available features of the peer will be provided in the event. + NRF_BLE_OTS_C_EVT_OACP_RESP, //!< Event indicating that a response was received (result of a write to the OACP). + NRF_BLE_OTS_C_EVT_OBJ_READ, //!< Event indicating that the Object Transfer Service client finished reading object from the peer + NRF_BLE_OTS_C_EVT_CHANNEL_RELEASED, //!< Event indicating that the L2CAP Connection Oriented Channel has been disconnected + NRF_BLE_OTS_C_EVT_SIZE_READ_RESP //!< Event indicating that the object size characteristic was read. +} nrf_ble_ots_c_evt_type_t; + +/** @brief Structure to hold the features of a server */ +typedef struct +{ + uint8_t oacp_create : 1; + uint8_t oacp_delete : 1; + uint8_t oacp_crc : 1; + uint8_t oacp_execute : 1; + uint8_t oacp_read : 1; + uint8_t oacp_write : 1; + uint8_t oacp_append : 1; + uint8_t oacp_truncate : 1; + uint8_t oacp_patch : 1; + uint8_t oacp_abort : 1; + uint8_t olcp_goto : 1; + uint8_t olcp_order : 1; + uint8_t olcp_req_num : 1; + uint8_t olcp_clear : 1; +} nrf_ble_ots_c_feature_t; + +/**@brief Structure used for holding the Apple Notification Center Service found during the + discovery process. + */ +typedef struct +{ + ble_gattc_service_t service; //!< The Object Transfer Service holding the discovered Object Transfer Service. (0x1825). + ble_gattc_char_t ots_feature_char; //!< OTS Feature (0x2ABD) + ble_gattc_char_t object_name_char; //!< Object Name (0x2ABE) + ble_gattc_char_t object_type_char; //!< Object Type (0x2ABF) + ble_gattc_char_t object_size_char; //!< Object Size (0x2AC0) + ble_gattc_char_t object_prop_char; //!< Object Properties (0x2AC4) + ble_gattc_char_t object_action_cp_char; //!< Object Action Control Point (0x2AC5) + ble_gattc_desc_t object_action_cp_cccd; //!< Object Action Control Point Descriptor. Enables or disables Object Transfer notifications. +} nrf_ble_ots_c_service_t; + + +typedef struct +{ + ble_ots_c_oacp_proc_type_t request_op_code; + ble_ots_c_oacp_res_code_t result_code; +} nrf_ble_ots_c_oacp_response_t; + +typedef struct +{ + uint32_t current_size; + uint32_t allocated_size; +} nrf_ble_ots_c_obj_size; + +/**@brief Structure containing the event from the Object Transfer client module to the application. + */ +typedef struct +{ + nrf_ble_ots_c_evt_type_t evt_type; /**< Type of event. See @ref nrf_ble_ots_c_evt_type_t. */ + uint16_t conn_handle; /**< Handle of the connection for which this event has occurred. */ + union + { + nrf_ble_ots_c_feature_t feature; /**< Will be provided if the event type is @ref NRF_BLE_OTS_C_EVT_FEATURE_READ_RESP.*/ + nrf_ble_ots_c_service_t handles; /**< Handles that the Object Transfer service occupies in the peer device. Will be filled if the event type is @ref NRF_BLE_OTS_C_EVT_DISCOVERY_COMPLETE.*/ + nrf_ble_ots_c_oacp_response_t response; /**< Will be provided if the event type is @ref NRF_BLE_OTS_C_EVT_OACP_RESP. */ + ble_data_t object; /**< Will be provided if the event type is @ref NRF_BLE_OTS_C_EVT_OBJ_READ. */ + nrf_ble_ots_c_obj_size size; /**< Will be provided if the event type is @ref NRF_BLE_OTS_C_EVT_SIZE_READ_RESP. */ + } params; +} nrf_ble_ots_c_evt_t; + + +/**@brief Object Transfer handler type. */ +typedef void (* nrf_ble_ots_c_evt_handler_t)(nrf_ble_ots_c_evt_t * p_evt); + + +/**@brief Structure for holding the information related to the Object Transfer Service. + + @warning This structure must be zero-initialized. +*/ +typedef struct +{ + bool initialized; /**< Boolean telling whether the context has been initialized or not. */ + uint16_t conn_handle; /**< Active connection handle */ + nrf_ble_ots_c_service_t service; /**< Structure to store the different handles and UUIDs related to the service. */ + nrf_ble_ots_c_evt_handler_t evt_handler; /**< Pointer to event handler function. */ + ble_srv_error_handler_t err_handler; /**< Pointer to error handler function. */ + uint16_t local_cid; + ble_l2cap_evt_ch_setup_t ch_setup; /**< L2CAP Channel Setup Completed Event Parameters. */ + uint32_t current_credits; + uint32_t remaining_bytes; + uint32_t transmitted_bytes; + uint32_t received_bytes; + ble_data_t * current_obj; +} nrf_ble_ots_c_t; + + +/**@brief Initialization parameters, these must be supplied when calling @ref nrf_ble_ots_c_init. */ +typedef struct +{ + nrf_ble_ots_c_evt_handler_t evt_handler; /**< The event handler that is called by the Object Transfer client module when any related event occurs. */ + ble_srv_error_handler_t err_handler; /**< the error handler that is called by the Object Transfer client module if any error occurs. */ +} nrf_ble_ots_c_init_t; + +/**@brief Function for initializing the Object Transfer client module. + + @param[in,out] p_ots_c Pointer to the Object Transfer Service client structure instance. + @param[in] p_ots_c_init Init parameters contraining the event handler that is called by + the Object Transfer client module when any related event occurs. + + @retval NRF_SUCCESS If the service was initialized successfully. + @retval NRF_ERROR_NULL If any of the input parameters are NULL. + @return If functions from other modules return errors to this function, + the @ref nrf_error are propagated. +*/ +ret_code_t nrf_ble_ots_c_init(nrf_ble_ots_c_t * p_ots_c, + nrf_ble_ots_c_init_t * p_ots_c_init); + + +/**@brief Function for handling events from the database discovery module. + + @details This function will handle an event from the database discovery module, and determine + if it relates to the discovery of Object Transfer Service at the peer. If so, + it will call the application's event handler indicating that Object Transfer Service + has been discovered at the peer. + + @param[in,out] p_ots_c Pointer to the Object Transfer Service client structure instance. + @param[in] p_evt Pointer to the event received from the database discovery module. +*/ +void nrf_ble_ots_c_on_db_disc_evt(nrf_ble_ots_c_t const * const p_ots_c, + ble_db_discovery_evt_t * const p_evt); + + +/**@brief Function for reading the features characteristic (@ref BLE_UUID_OTS_FEATURES) on the server. + + @param[in,out] p_ots_c Pointer to Object Transfer client structure. + + @retval NRF_SUCCESS Operation success. + @return If functions from other modules return errors to this function, + the @ref nrf_error are propagated. +*/ +ret_code_t nrf_ble_ots_c_feature_read(nrf_ble_ots_c_t * const p_ots_c); + + +/**@brief Function for reading the Object Size characteristic (@ref BLE_UUID_OTS_FEATURES) on the server. + + @param[in,out] p_ots_c Pointer to Object Transfer client structure. + + @retval NRF_SUCCESS Operation success. + @return NRF_ERROR_INVALID_STATE if the Object Size characteristic has not been discovered. If functions from other modules return errors to this function, + the @ref nrf_error are propagated. +*/ +ret_code_t nrf_ble_ots_c_obj_size_read(nrf_ble_ots_c_t * const p_ots_c); + + +/**@brief Function for handling the Application's BLE Stack events. + + @param[in] p_ble_evt Pointer to the BLE event received. + @param[in,out] p_context Pointer to the Object Transfer Service client structure instance. +*/ +void nrf_ble_ots_c_on_ble_evt(const ble_evt_t * const p_ble_evt, + void * p_context); + + +ret_code_t nrf_ble_ots_c_obj_name_read(nrf_ble_ots_c_t * const p_ots_c, ble_data_t * p_obj); +ret_code_t nrf_ble_ots_c_obj_name_write(nrf_ble_ots_c_t * const p_ots_c, ble_data_t * p_obj); +ret_code_t nrf_ble_ots_c_obj_type_read(nrf_ble_ots_c_t * const p_ots_c); +ret_code_t nrf_ble_ots_c_obj_size_read(nrf_ble_ots_c_t * const p_ots_c); +ret_code_t nrf_ble_ots_c_obj_properties_read(nrf_ble_ots_c_t * const p_ots_c); + + +/**@brief Function for assigning handles to a Object Transfer Service client instance. + + @details Call this function when a link has been established with a peer to + associate this link to an instance of the module. This makes it + possible to handle several link and associate each link to a particular + instance of the Object Transfer Service client module. The connection handle and + attribute handles will be provided from the discovery event + @ref NRF_BLE_OTS_C_EVT_DISCOVERY_COMPLETE. + + @param[in,out] p_ots_c Pointer to the Object Transfer Service client structure instance to associate + with the handles. + @param[in] conn_handle Connection handle to be associated with the given Object Transfer Service client + Instance. + @param[in] p_peer_handles Attribute handles on the Object Transfer Service server that you want this + Object Transfer Service client to interact with. + + @retval NRF_SUCCESS If the connection handle was successfully stored in the Object Transfer Service instance. + @retval NRF_ERROR_NULL If any of the input parameters are NULL. +*/ +ret_code_t nrf_ble_ots_c_handles_assign(nrf_ble_ots_c_t * const p_ots_c, + uint16_t const conn_handle, + nrf_ble_ots_c_service_t const * const p_peer_handles); + +#endif // NRF_BLE_OTS_C_H__ + +/** @} */ |