Marco Zecchini / Mbed OS Example_RTOS

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

mbed-os/features/FEATURE_BLE/ble/pal/AttClient.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
marcozecchini 0:9fca2b23d0ba 1 /* mbed Microcontroller Library
marcozecchini 0:9fca2b23d0ba 2 * Copyright (c) 2017-2017 ARM Limited
marcozecchini 0:9fca2b23d0ba 3 *
marcozecchini 0:9fca2b23d0ba 4 * Licensed under the Apache License, Version 2.0 (the "License");
marcozecchini 0:9fca2b23d0ba 5 * you may not use this file except in compliance with the License.
marcozecchini 0:9fca2b23d0ba 6 * You may obtain a copy of the License at
marcozecchini 0:9fca2b23d0ba 7 *
marcozecchini 0:9fca2b23d0ba 8 * http://www.apache.org/licenses/LICENSE-2.0
marcozecchini 0:9fca2b23d0ba 9 *
marcozecchini 0:9fca2b23d0ba 10 * Unless required by applicable law or agreed to in writing, software
marcozecchini 0:9fca2b23d0ba 11 * distributed under the License is distributed on an "AS IS" BASIS,
marcozecchini 0:9fca2b23d0ba 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
marcozecchini 0:9fca2b23d0ba 13 * See the License for the specific language governing permissions and
marcozecchini 0:9fca2b23d0ba 14 * limitations under the License.
marcozecchini 0:9fca2b23d0ba 15 */
marcozecchini 0:9fca2b23d0ba 16
marcozecchini 0:9fca2b23d0ba 17 #ifndef BLE_PAL_ATTCLIENT_H_
marcozecchini 0:9fca2b23d0ba 18 #define BLE_PAL_ATTCLIENT_H_
marcozecchini 0:9fca2b23d0ba 19
marcozecchini 0:9fca2b23d0ba 20 #include "ble/UUID.h"
marcozecchini 0:9fca2b23d0ba 21 #include "ble/BLETypes.h"
marcozecchini 0:9fca2b23d0ba 22 #include "ble/ArrayView.h"
marcozecchini 0:9fca2b23d0ba 23 #include "ble/blecommon.h"
marcozecchini 0:9fca2b23d0ba 24 #include "platform/Callback.h"
marcozecchini 0:9fca2b23d0ba 25 #include "AttServerMessage.h"
marcozecchini 0:9fca2b23d0ba 26
marcozecchini 0:9fca2b23d0ba 27 namespace ble {
marcozecchini 0:9fca2b23d0ba 28 namespace pal {
marcozecchini 0:9fca2b23d0ba 29
marcozecchini 0:9fca2b23d0ba 30 /**
marcozecchini 0:9fca2b23d0ba 31 * Send attribute protocol requests to an ATT server. It also handle reception
marcozecchini 0:9fca2b23d0ba 32 * of ATT response and server indication/notification.
marcozecchini 0:9fca2b23d0ba 33 *
marcozecchini 0:9fca2b23d0ba 34 * Every request send and response or response event received is for a specified
marcozecchini 0:9fca2b23d0ba 35 * connection.
marcozecchini 0:9fca2b23d0ba 36 *
marcozecchini 0:9fca2b23d0ba 37 * @warning This class should not be used outside mbed BLE, availability is not
marcozecchini 0:9fca2b23d0ba 38 * guaranteed for all ports.
marcozecchini 0:9fca2b23d0ba 39 *
marcozecchini 0:9fca2b23d0ba 40 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F
marcozecchini 0:9fca2b23d0ba 41 */
marcozecchini 0:9fca2b23d0ba 42 struct AttClient {
marcozecchini 0:9fca2b23d0ba 43 /**
marcozecchini 0:9fca2b23d0ba 44 * Initialization of the instance. An implementation can use this function
marcozecchini 0:9fca2b23d0ba 45 * to initialise the subsystems needed to realize the ATT operations of this
marcozecchini 0:9fca2b23d0ba 46 * interface.
marcozecchini 0:9fca2b23d0ba 47 *
marcozecchini 0:9fca2b23d0ba 48 * This function has to be called before any other operations.
marcozecchini 0:9fca2b23d0ba 49 *
marcozecchini 0:9fca2b23d0ba 50 * @return BLE_ERROR_NONE if the request has been successfully sent or the
marcozecchini 0:9fca2b23d0ba 51 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 52 */
marcozecchini 0:9fca2b23d0ba 53 virtual ble_error_t initialize() = 0;
marcozecchini 0:9fca2b23d0ba 54
marcozecchini 0:9fca2b23d0ba 55 /**
marcozecchini 0:9fca2b23d0ba 56 * Termination of the instance. An implementation can use this function
marcozecchini 0:9fca2b23d0ba 57 * to release the subsystems initialised to realise the ATT operations of
marcozecchini 0:9fca2b23d0ba 58 * this interface.
marcozecchini 0:9fca2b23d0ba 59 *
marcozecchini 0:9fca2b23d0ba 60 * After a call to this function, initialise should be called again to
marcozecchini 0:9fca2b23d0ba 61 * allow usage of the interface.
marcozecchini 0:9fca2b23d0ba 62 *
marcozecchini 0:9fca2b23d0ba 63 * @return BLE_ERROR_NONE if the request has been successfully sent or the
marcozecchini 0:9fca2b23d0ba 64 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 65 */
marcozecchini 0:9fca2b23d0ba 66 virtual ble_error_t terminate() = 0;
marcozecchini 0:9fca2b23d0ba 67
marcozecchini 0:9fca2b23d0ba 68 /**
marcozecchini 0:9fca2b23d0ba 69 * Send an exchange MTU request which negotiate the size of the MTU used by
marcozecchini 0:9fca2b23d0ba 70 * the connection.
marcozecchini 0:9fca2b23d0ba 71 *
marcozecchini 0:9fca2b23d0ba 72 * First the client send to the server the maximum rx mtu that it can receive
marcozecchini 0:9fca2b23d0ba 73 * then the client reply with the maximum rx mtu it can receive.
marcozecchini 0:9fca2b23d0ba 74 *
marcozecchini 0:9fca2b23d0ba 75 * The mtu choosen for the connection is the minimum of the client Rx mtu
marcozecchini 0:9fca2b23d0ba 76 * and server Rx mtu values.
marcozecchini 0:9fca2b23d0ba 77 *
marcozecchini 0:9fca2b23d0ba 78 * If an error occured then the mtu used remains the default value.
marcozecchini 0:9fca2b23d0ba 79 *
marcozecchini 0:9fca2b23d0ba 80 * @param connection The handle of the connection to send this request to.
marcozecchini 0:9fca2b23d0ba 81 *
marcozecchini 0:9fca2b23d0ba 82 * @return BLE_ERROR_NONE if the request has been succesfully sent or the
marcozecchini 0:9fca2b23d0ba 83 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 84 *
marcozecchini 0:9fca2b23d0ba 85 * @see ble::pal::AttExchangeMTUResponse The type of response received from
marcozecchini 0:9fca2b23d0ba 86 * the server
marcozecchini 0:9fca2b23d0ba 87 * @see ble::pal::AttErrorResponse::REQUEST_NOT_SUPPORTED The error code
marcozecchini 0:9fca2b23d0ba 88 * returned by the server in case of error.
marcozecchini 0:9fca2b23d0ba 89 *
marcozecchini 0:9fca2b23d0ba 90 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.2.1
marcozecchini 0:9fca2b23d0ba 91 */
marcozecchini 0:9fca2b23d0ba 92 virtual ble_error_t exchange_mtu_request(connection_handle_t connection) = 0;
marcozecchini 0:9fca2b23d0ba 93
marcozecchini 0:9fca2b23d0ba 94 /**
marcozecchini 0:9fca2b23d0ba 95 * Acquire the size of the mtu for a given connection.
marcozecchini 0:9fca2b23d0ba 96 *
marcozecchini 0:9fca2b23d0ba 97 * @param connection The handle of the connection for which the the MTU size
marcozecchini 0:9fca2b23d0ba 98 * should be acquired.
marcozecchini 0:9fca2b23d0ba 99 *
marcozecchini 0:9fca2b23d0ba 100 * @param mtu_size Output parameter which will contain the MTU size.
marcozecchini 0:9fca2b23d0ba 101 *
marcozecchini 0:9fca2b23d0ba 102 * @return BLE_ERROR_NONE if the MTU size has been acquired or the
marcozecchini 0:9fca2b23d0ba 103 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 104 */
marcozecchini 0:9fca2b23d0ba 105 virtual ble_error_t get_mtu_size(
marcozecchini 0:9fca2b23d0ba 106 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 107 uint16_t& mtu_size
marcozecchini 0:9fca2b23d0ba 108 ) = 0;
marcozecchini 0:9fca2b23d0ba 109
marcozecchini 0:9fca2b23d0ba 110 /**
marcozecchini 0:9fca2b23d0ba 111 * Send a find information request to a server in order to obtain the
marcozecchini 0:9fca2b23d0ba 112 * mapping of attribute handles with their associated types.
marcozecchini 0:9fca2b23d0ba 113 *
marcozecchini 0:9fca2b23d0ba 114 * The server will reply with a ble::pal::AttFindInformationResponse
marcozecchini 0:9fca2b23d0ba 115 * containing at least one [attribute handle, attribute type] pair. If the
marcozecchini 0:9fca2b23d0ba 116 * last handle in the response is not equal to the end handle of the finding
marcozecchini 0:9fca2b23d0ba 117 * range then this request can be issued again with an updated range (begin
marcozecchini 0:9fca2b23d0ba 118 * equal to last handle received + 1) to discover the remaining attributes.
marcozecchini 0:9fca2b23d0ba 119 *
marcozecchini 0:9fca2b23d0ba 120 * To discover the whole ATT server, the first find information request
marcozecchini 0:9fca2b23d0ba 121 * should have a discovery range of [0x0001 - 0xFFFF].
marcozecchini 0:9fca2b23d0ba 122 *
marcozecchini 0:9fca2b23d0ba 123 * The server can send a ble::pal::AttErrorResponse with the code
marcozecchini 0:9fca2b23d0ba 124 * ble::pal::AttErrorResponse::ATTRIBUTE_NOT_FOUND if no attributes have
marcozecchini 0:9fca2b23d0ba 125 * been found in the range specified. The attribute handle in the response
marcozecchini 0:9fca2b23d0ba 126 * is then equal to the first handle of the discovery range.
marcozecchini 0:9fca2b23d0ba 127 *
marcozecchini 0:9fca2b23d0ba 128 * If the range is malformed the server will reply a
marcozecchini 0:9fca2b23d0ba 129 * ble::pal::AttErrorResponse with the error code ble::pal::INVALID_HANDLE.
marcozecchini 0:9fca2b23d0ba 130 *
marcozecchini 0:9fca2b23d0ba 131 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 132 * request to.
marcozecchini 0:9fca2b23d0ba 133 * @param discovery_range The attribute range where handle-type informations
marcozecchini 0:9fca2b23d0ba 134 * should be discovered.
marcozecchini 0:9fca2b23d0ba 135 *
marcozecchini 0:9fca2b23d0ba 136 * @return BLE_ERROR_NONE if the request has been successfully sent or the
marcozecchini 0:9fca2b23d0ba 137 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 138 *
marcozecchini 0:9fca2b23d0ba 139 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.3.1
marcozecchini 0:9fca2b23d0ba 140 */
marcozecchini 0:9fca2b23d0ba 141 virtual ble_error_t find_information_request(
marcozecchini 0:9fca2b23d0ba 142 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 143 attribute_handle_range_t discovery_range
marcozecchini 0:9fca2b23d0ba 144 ) = 0;
marcozecchini 0:9fca2b23d0ba 145
marcozecchini 0:9fca2b23d0ba 146 /**
marcozecchini 0:9fca2b23d0ba 147 * Send a Find By Type Value Request which retrieve the handles of attributes
marcozecchini 0:9fca2b23d0ba 148 * that have known 16-bit UUID attribute type and known attribute value.
marcozecchini 0:9fca2b23d0ba 149 *
marcozecchini 0:9fca2b23d0ba 150 * The server should reply with a ble::pal::AttFindByTypeValueResponse
marcozecchini 0:9fca2b23d0ba 151 * containing the handle (or handle range in case of grouping attributes) of
marcozecchini 0:9fca2b23d0ba 152 * the attribute found.
marcozecchini 0:9fca2b23d0ba 153 *
marcozecchini 0:9fca2b23d0ba 154 * If not all attributes can be contained in the response it is necessary to
marcozecchini 0:9fca2b23d0ba 155 * send again this request with an updated range to continue the discovery.
marcozecchini 0:9fca2b23d0ba 156 *
marcozecchini 0:9fca2b23d0ba 157 * The server can send a ble::pal::AttErrorResponse with the code
marcozecchini 0:9fca2b23d0ba 158 * ble::pal::AttErrorResponse::ATTRIBUTE_NOT_FOUND if no attributes have
marcozecchini 0:9fca2b23d0ba 159 * been found in the range specified. The attribute handle in the response
marcozecchini 0:9fca2b23d0ba 160 * is then equal to the first handle of the discovery range.
marcozecchini 0:9fca2b23d0ba 161 *
marcozecchini 0:9fca2b23d0ba 162 * If the range is malformed the server will reply a
marcozecchini 0:9fca2b23d0ba 163 * ble::pal::AttErrorResponse with the error code ble::pal::INVALID_HANDLE.
marcozecchini 0:9fca2b23d0ba 164 *
marcozecchini 0:9fca2b23d0ba 165 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 166 * request to.
marcozecchini 0:9fca2b23d0ba 167 * @param discovery_range The handle range where attributes with type and
marcozecchini 0:9fca2b23d0ba 168 * value are searched.
marcozecchini 0:9fca2b23d0ba 169 * @param type The type of attribute to find (it is a 16 bit UUID).
marcozecchini 0:9fca2b23d0ba 170 * @param value The value of the attributes to found.
marcozecchini 0:9fca2b23d0ba 171 *
marcozecchini 0:9fca2b23d0ba 172 * @return BLE_ERROR_NONE if the request has been successfully sent or the
marcozecchini 0:9fca2b23d0ba 173 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 174 *
marcozecchini 0:9fca2b23d0ba 175 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.3.3
marcozecchini 0:9fca2b23d0ba 176 */
marcozecchini 0:9fca2b23d0ba 177 virtual ble_error_t find_by_type_value_request(
marcozecchini 0:9fca2b23d0ba 178 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 179 attribute_handle_range_t discovery_range,
marcozecchini 0:9fca2b23d0ba 180 uint16_t type,
marcozecchini 0:9fca2b23d0ba 181 const ArrayView<const uint8_t>& value
marcozecchini 0:9fca2b23d0ba 182 ) = 0;
marcozecchini 0:9fca2b23d0ba 183
marcozecchini 0:9fca2b23d0ba 184 /**
marcozecchini 0:9fca2b23d0ba 185 * Send a Read By Type Request used to obtain the values of attributes where
marcozecchini 0:9fca2b23d0ba 186 * the attribute type is known but the handle is not known.
marcozecchini 0:9fca2b23d0ba 187 *
marcozecchini 0:9fca2b23d0ba 188 * If attributes with the type requested are present in the range, the server
marcozecchini 0:9fca2b23d0ba 189 * should reply with a ble::pal::AttReadByTypeResponse. If the response does
marcozecchini 0:9fca2b23d0ba 190 * not cover the full range, the request should be sent again with an updated
marcozecchini 0:9fca2b23d0ba 191 * range.
marcozecchini 0:9fca2b23d0ba 192 *
marcozecchini 0:9fca2b23d0ba 193 * In case of error, the server will send a ble::pal::AttErrorResponse. The
marcozecchini 0:9fca2b23d0ba 194 * error code depends on the situation:
marcozecchini 0:9fca2b23d0ba 195 * - ble::pal::AttErrorResponse::ATTRIBUTE_NOT_FOUND: If there is no
marcozecchini 0:9fca2b23d0ba 196 * attributes matching type in the range.
marcozecchini 0:9fca2b23d0ba 197 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the range is
marcozecchini 0:9fca2b23d0ba 198 * invalid.
marcozecchini 0:9fca2b23d0ba 199 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client
marcozecchini 0:9fca2b23d0ba 200 * security is not sufficient.
marcozecchini 0:9fca2b23d0ba 201 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client
marcozecchini 0:9fca2b23d0ba 202 * authorization is not sufficient.
marcozecchini 0:9fca2b23d0ba 203 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the
marcozecchini 0:9fca2b23d0ba 204 * client has an insufficient encryption key size.
marcozecchini 0:9fca2b23d0ba 205 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client
marcozecchini 0:9fca2b23d0ba 206 * has not enabled encryption.
marcozecchini 0:9fca2b23d0ba 207 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If the attribute
marcozecchini 0:9fca2b23d0ba 208 * value cannot be read.
marcozecchini 0:9fca2b23d0ba 209 *
marcozecchini 0:9fca2b23d0ba 210 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 211 * request to.
marcozecchini 0:9fca2b23d0ba 212 * @param read_range The handle range where attributes with the given type
marcozecchini 0:9fca2b23d0ba 213 * should be read.
marcozecchini 0:9fca2b23d0ba 214 * @param type The type of attributes to read.
marcozecchini 0:9fca2b23d0ba 215 *
marcozecchini 0:9fca2b23d0ba 216 * @return BLE_ERROR_NONE if the request has been successfully sent or the
marcozecchini 0:9fca2b23d0ba 217 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 218 *
marcozecchini 0:9fca2b23d0ba 219 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.1
marcozecchini 0:9fca2b23d0ba 220 */
marcozecchini 0:9fca2b23d0ba 221 virtual ble_error_t read_by_type_request(
marcozecchini 0:9fca2b23d0ba 222 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 223 attribute_handle_range_t read_range,
marcozecchini 0:9fca2b23d0ba 224 const UUID& type
marcozecchini 0:9fca2b23d0ba 225 ) = 0;
marcozecchini 0:9fca2b23d0ba 226
marcozecchini 0:9fca2b23d0ba 227 /**
marcozecchini 0:9fca2b23d0ba 228 * Send a Read Request to read the value of an attribute in the server.
marcozecchini 0:9fca2b23d0ba 229 *
marcozecchini 0:9fca2b23d0ba 230 * In case of success, the server will reply with a ble::pal::AttReadResponse.
marcozecchini 0:9fca2b23d0ba 231 * containing the value of the attribute. If the length of the value in the
marcozecchini 0:9fca2b23d0ba 232 * response is equal to (mtu - 1) then the remaining part of the value can
marcozecchini 0:9fca2b23d0ba 233 * be obtained by a read_blob_request.
marcozecchini 0:9fca2b23d0ba 234 *
marcozecchini 0:9fca2b23d0ba 235 * In case of error, the server will send a ble::pal::AttErrorResponse. The
marcozecchini 0:9fca2b23d0ba 236 * error code depends on the situation:
marcozecchini 0:9fca2b23d0ba 237 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the attribute handle
marcozecchini 0:9fca2b23d0ba 238 * is invalid.
marcozecchini 0:9fca2b23d0ba 239 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client
marcozecchini 0:9fca2b23d0ba 240 * security is not sufficient.
marcozecchini 0:9fca2b23d0ba 241 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client
marcozecchini 0:9fca2b23d0ba 242 * authorization is not sufficient.
marcozecchini 0:9fca2b23d0ba 243 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the
marcozecchini 0:9fca2b23d0ba 244 * client has an insufficient encryption key size.
marcozecchini 0:9fca2b23d0ba 245 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client
marcozecchini 0:9fca2b23d0ba 246 * has not enabled encryption.
marcozecchini 0:9fca2b23d0ba 247 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If the attribute
marcozecchini 0:9fca2b23d0ba 248 * value cannot be read.
marcozecchini 0:9fca2b23d0ba 249 * Higher layer can also set an application error code (0x80 - 0x9F).
marcozecchini 0:9fca2b23d0ba 250 *
marcozecchini 0:9fca2b23d0ba 251 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 252 * request to.
marcozecchini 0:9fca2b23d0ba 253 * @param attribute_handle The handle of the attribute to read.
marcozecchini 0:9fca2b23d0ba 254 *
marcozecchini 0:9fca2b23d0ba 255 * @return BLE_ERROR_NONE if the request has been successfully sent or the
marcozecchini 0:9fca2b23d0ba 256 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 257 *
marcozecchini 0:9fca2b23d0ba 258 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.3
marcozecchini 0:9fca2b23d0ba 259 */
marcozecchini 0:9fca2b23d0ba 260 virtual ble_error_t read_request(
marcozecchini 0:9fca2b23d0ba 261 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 262 attribute_handle_t attribute_handle
marcozecchini 0:9fca2b23d0ba 263 ) = 0;
marcozecchini 0:9fca2b23d0ba 264
marcozecchini 0:9fca2b23d0ba 265 /**
marcozecchini 0:9fca2b23d0ba 266 * Send a read blob request to a server to read a part of the value of an
marcozecchini 0:9fca2b23d0ba 267 * attribute at a given offset.
marcozecchini 0:9fca2b23d0ba 268 *
marcozecchini 0:9fca2b23d0ba 269 * In case of success, the server will reply with a ble::pal::AttReadBlobResponse
marcozecchini 0:9fca2b23d0ba 270 * containing the value read. If the value of the attribute starting at the
marcozecchini 0:9fca2b23d0ba 271 * offset requested is longer than (mtu - 1) octets then only the first
marcozecchini 0:9fca2b23d0ba 272 * (mtu - 1) octets will be present in the response.
marcozecchini 0:9fca2b23d0ba 273 * The remaining octets can be acquired by another Read Blob Request with an
marcozecchini 0:9fca2b23d0ba 274 * updated index.
marcozecchini 0:9fca2b23d0ba 275 *
marcozecchini 0:9fca2b23d0ba 276 * In case of error, the server will send a ble::pal::AttErrorResponse. The
marcozecchini 0:9fca2b23d0ba 277 * error code depends on the situation:
marcozecchini 0:9fca2b23d0ba 278 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the attribute handle
marcozecchini 0:9fca2b23d0ba 279 * is invalid.
marcozecchini 0:9fca2b23d0ba 280 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client
marcozecchini 0:9fca2b23d0ba 281 * security is not sufficient.
marcozecchini 0:9fca2b23d0ba 282 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client
marcozecchini 0:9fca2b23d0ba 283 * authorization is not sufficient.
marcozecchini 0:9fca2b23d0ba 284 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the
marcozecchini 0:9fca2b23d0ba 285 * client has an insufficient encryption key size.
marcozecchini 0:9fca2b23d0ba 286 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client
marcozecchini 0:9fca2b23d0ba 287 * has not enabled encryption.
marcozecchini 0:9fca2b23d0ba 288 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If the attribute
marcozecchini 0:9fca2b23d0ba 289 * value cannot be read.
marcozecchini 0:9fca2b23d0ba 290 * - ble::pal::AttErrorResponse::INVALID_OFFSET: If the offset is greater
marcozecchini 0:9fca2b23d0ba 291 * than the attribute length.
marcozecchini 0:9fca2b23d0ba 292 * - ble::pal::AttErrorResponse::ATTRIBUTE_NOT_LONG: If the attribute
marcozecchini 0:9fca2b23d0ba 293 * value has a length that is less than or equal to (mtu - 1).
marcozecchini 0:9fca2b23d0ba 294 * Higher layer can also set an application error code (0x80 - 0x9F).
marcozecchini 0:9fca2b23d0ba 295 *
marcozecchini 0:9fca2b23d0ba 296 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 297 * request to.
marcozecchini 0:9fca2b23d0ba 298 * @param attribute_handle The handle of the attribute to read.
marcozecchini 0:9fca2b23d0ba 299 * @param offset The offset of the first octet to read.
marcozecchini 0:9fca2b23d0ba 300 *
marcozecchini 0:9fca2b23d0ba 301 * @return BLE_ERROR_NONE if the request has been successfully sent or an
marcozecchini 0:9fca2b23d0ba 302 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 303 *
marcozecchini 0:9fca2b23d0ba 304 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.5
marcozecchini 0:9fca2b23d0ba 305 */
marcozecchini 0:9fca2b23d0ba 306 virtual ble_error_t read_blob_request(
marcozecchini 0:9fca2b23d0ba 307 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 308 attribute_handle_t attribute_handle,
marcozecchini 0:9fca2b23d0ba 309 uint16_t offset
marcozecchini 0:9fca2b23d0ba 310 ) = 0;
marcozecchini 0:9fca2b23d0ba 311
marcozecchini 0:9fca2b23d0ba 312 /**
marcozecchini 0:9fca2b23d0ba 313 * Send a read multiple request to the server. It is used to read two or more
marcozecchini 0:9fca2b23d0ba 314 * attributes values at once.
marcozecchini 0:9fca2b23d0ba 315 *
marcozecchini 0:9fca2b23d0ba 316 * In case of success, the server will reply with a
marcozecchini 0:9fca2b23d0ba 317 * ble::pal::AttReadMultipleResponse containing the concatenation of the
marcozecchini 0:9fca2b23d0ba 318 * values read. Given that values are concatained, all attributes values
marcozecchini 0:9fca2b23d0ba 319 * should be of fixed size except for the last one. The concatained value
marcozecchini 0:9fca2b23d0ba 320 * is also truncated to (mtu - 1) if it doesn't fit in the response.
marcozecchini 0:9fca2b23d0ba 321 *
marcozecchini 0:9fca2b23d0ba 322 * In case of error, the server will send a ble::pal::AttErrorResponse. The
marcozecchini 0:9fca2b23d0ba 323 * error code depends on the situation:
marcozecchini 0:9fca2b23d0ba 324 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If any of the attribute
marcozecchini 0:9fca2b23d0ba 325 * handle is invalid.
marcozecchini 0:9fca2b23d0ba 326 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client
marcozecchini 0:9fca2b23d0ba 327 * security is not sufficient to read any of the attribute.
marcozecchini 0:9fca2b23d0ba 328 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client
marcozecchini 0:9fca2b23d0ba 329 * authorization is not sufficient to read any of the attribute.
marcozecchini 0:9fca2b23d0ba 330 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the
marcozecchini 0:9fca2b23d0ba 331 * client has an insufficient encryption key size to read any of the
marcozecchini 0:9fca2b23d0ba 332 * attributes.
marcozecchini 0:9fca2b23d0ba 333 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client
marcozecchini 0:9fca2b23d0ba 334 * has not enabled encryption required to read any of the attributes.
marcozecchini 0:9fca2b23d0ba 335 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If any of the
marcozecchini 0:9fca2b23d0ba 336 * attributes value cannot be read.
marcozecchini 0:9fca2b23d0ba 337 * The first attribute causing the error is reporter in the handle_in_error
marcozecchini 0:9fca2b23d0ba 338 * field in the error response.
marcozecchini 0:9fca2b23d0ba 339 * Higher layer can also set an application error code (0x80 - 0x9F).
marcozecchini 0:9fca2b23d0ba 340 *
marcozecchini 0:9fca2b23d0ba 341 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 342 * request to.
marcozecchini 0:9fca2b23d0ba 343 * @param attribute_handles Set of attribute handles to read.
marcozecchini 0:9fca2b23d0ba 344 *
marcozecchini 0:9fca2b23d0ba 345 * @return BLE_ERROR_NONE if the request has been successfully sent or an
marcozecchini 0:9fca2b23d0ba 346 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 347 *
marcozecchini 0:9fca2b23d0ba 348 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.7
marcozecchini 0:9fca2b23d0ba 349 */
marcozecchini 0:9fca2b23d0ba 350 virtual ble_error_t read_multiple_request(
marcozecchini 0:9fca2b23d0ba 351 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 352 const ArrayView<const attribute_handle_t>& attribute_handles
marcozecchini 0:9fca2b23d0ba 353 ) = 0;
marcozecchini 0:9fca2b23d0ba 354
marcozecchini 0:9fca2b23d0ba 355 /**
marcozecchini 0:9fca2b23d0ba 356 * Send a read by group type request to the server. It is used to get
marcozecchini 0:9fca2b23d0ba 357 * informations about grouping attribute of a given type on a server.
marcozecchini 0:9fca2b23d0ba 358 *
marcozecchini 0:9fca2b23d0ba 359 * The server will reply with a ble::pal::ReadByGroupTypeResponse containing
marcozecchini 0:9fca2b23d0ba 360 * informations about the grouping attribute found. Informations are:
marcozecchini 0:9fca2b23d0ba 361 * - handle of the grouping attribute.
marcozecchini 0:9fca2b23d0ba 362 * - last handle of the group .
marcozecchini 0:9fca2b23d0ba 363 * - attribute value.
marcozecchini 0:9fca2b23d0ba 364 *
marcozecchini 0:9fca2b23d0ba 365 * If the last handle received is not the last handle of the discovery range
marcozecchini 0:9fca2b23d0ba 366 * then it is necessary to send another request with a discovery range
marcozecchini 0:9fca2b23d0ba 367 * updated to: [last handle + 1 : end].
marcozecchini 0:9fca2b23d0ba 368 *
marcozecchini 0:9fca2b23d0ba 369 * In case of error, the server will send a ble::pal::AttErrorResponse. The
marcozecchini 0:9fca2b23d0ba 370 * error code depends on the situation:
marcozecchini 0:9fca2b23d0ba 371 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the range of handle
marcozecchini 0:9fca2b23d0ba 372 * provided is invalid.
marcozecchini 0:9fca2b23d0ba 373 * - ble::pal::AttErrorResponse::UNSUPPORTED_GROUP_TYPE: if the group type
marcozecchini 0:9fca2b23d0ba 374 * is not a supported grouping attribute.
marcozecchini 0:9fca2b23d0ba 375 * - ble::pal::AttErrorResponse::ATTRIBUTE_NOT_FOUND: If no attribute with
marcozecchini 0:9fca2b23d0ba 376 * the given type exists within the range provided.
marcozecchini 0:9fca2b23d0ba 377 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client
marcozecchini 0:9fca2b23d0ba 378 * security is not sufficient to read the requested attribute.
marcozecchini 0:9fca2b23d0ba 379 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client
marcozecchini 0:9fca2b23d0ba 380 * authorization is not sufficient to read the requested attribute.
marcozecchini 0:9fca2b23d0ba 381 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the
marcozecchini 0:9fca2b23d0ba 382 * client has an insufficient encryption key size to read the requested
marcozecchini 0:9fca2b23d0ba 383 * attributes.
marcozecchini 0:9fca2b23d0ba 384 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client
marcozecchini 0:9fca2b23d0ba 385 * has not enabled encryption required to read the requested attributes.
marcozecchini 0:9fca2b23d0ba 386 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If any of the
marcozecchini 0:9fca2b23d0ba 387 * attributes value cannot be read.
marcozecchini 0:9fca2b23d0ba 388 * Higher layer can also set an application error code (0x80 - 0x9F).
marcozecchini 0:9fca2b23d0ba 389 *
marcozecchini 0:9fca2b23d0ba 390 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 391 * request to.
marcozecchini 0:9fca2b23d0ba 392 * @param read_range Range where this request apply.
marcozecchini 0:9fca2b23d0ba 393 * @param group_type Type of the grouping attribute to find and read.
marcozecchini 0:9fca2b23d0ba 394 *
marcozecchini 0:9fca2b23d0ba 395 * @return BLE_ERROR_NONE if the request has been successfully sent or an
marcozecchini 0:9fca2b23d0ba 396 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 397 *
marcozecchini 0:9fca2b23d0ba 398 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.9
marcozecchini 0:9fca2b23d0ba 399 */
marcozecchini 0:9fca2b23d0ba 400 virtual ble_error_t read_by_group_type_request(
marcozecchini 0:9fca2b23d0ba 401 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 402 attribute_handle_range_t read_range,
marcozecchini 0:9fca2b23d0ba 403 const UUID& group_type
marcozecchini 0:9fca2b23d0ba 404 ) = 0;
marcozecchini 0:9fca2b23d0ba 405
marcozecchini 0:9fca2b23d0ba 406 /**
marcozecchini 0:9fca2b23d0ba 407 * Send a write request to the server to write the value of an attribute.
marcozecchini 0:9fca2b23d0ba 408 *
marcozecchini 0:9fca2b23d0ba 409 * In case of success, the server will reply with a
marcozecchini 0:9fca2b23d0ba 410 * ble::pal::AttWriteResponse to acknowledge that the write operation went
marcozecchini 0:9fca2b23d0ba 411 * well.
marcozecchini 0:9fca2b23d0ba 412 *
marcozecchini 0:9fca2b23d0ba 413 * If the attribute value has a variable length, then the attribute value
marcozecchini 0:9fca2b23d0ba 414 * shall be truncated or lengthened to match the length of the value in the
marcozecchini 0:9fca2b23d0ba 415 * request.
marcozecchini 0:9fca2b23d0ba 416 *
marcozecchini 0:9fca2b23d0ba 417 * If the attribute value has a fixed length and the Attribute Value parameter length
marcozecchini 0:9fca2b23d0ba 418 * is less than or equal to the length of the attribute value, the octets of the
marcozecchini 0:9fca2b23d0ba 419 * attribute value parameter length shall be written; all other octets in this attribute
marcozecchini 0:9fca2b23d0ba 420 * value shall be unchanged.
marcozecchini 0:9fca2b23d0ba 421 *
marcozecchini 0:9fca2b23d0ba 422 * In case of error, the server will send a ble::pal::AttErrorResponse. The
marcozecchini 0:9fca2b23d0ba 423 * error code depends on the situation:
marcozecchini 0:9fca2b23d0ba 424 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the handle to write is
marcozecchini 0:9fca2b23d0ba 425 * invalid.
marcozecchini 0:9fca2b23d0ba 426 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client
marcozecchini 0:9fca2b23d0ba 427 * security is not sufficient to write the requested attribute.
marcozecchini 0:9fca2b23d0ba 428 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client
marcozecchini 0:9fca2b23d0ba 429 * authorization is not sufficient to write the requested attribute.
marcozecchini 0:9fca2b23d0ba 430 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the
marcozecchini 0:9fca2b23d0ba 431 * client has an insufficient encryption key size to write the requested
marcozecchini 0:9fca2b23d0ba 432 * attributes.
marcozecchini 0:9fca2b23d0ba 433 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client
marcozecchini 0:9fca2b23d0ba 434 * has not enabled encryption required to write the requested attributes.
marcozecchini 0:9fca2b23d0ba 435 * - ble::pal::AttErrorResponse::WRITE_NOT_PERMITTED: If the attribute
marcozecchini 0:9fca2b23d0ba 436 * value cannot be written due to permission.
marcozecchini 0:9fca2b23d0ba 437 * - ble::pal::AttErrorResponse::INVALID_ATTRIBUTE_VALUE_LENGTH: If the
marcozecchini 0:9fca2b23d0ba 438 * value to write exceeds the maximum valid length or of the attribute
marcozecchini 0:9fca2b23d0ba 439 * value; whether the attribute has a variable length value or a fixed
marcozecchini 0:9fca2b23d0ba 440 * length value.
marcozecchini 0:9fca2b23d0ba 441 * Higher layer can also set an application error code (0x80 - 0x9F).
marcozecchini 0:9fca2b23d0ba 442 *
marcozecchini 0:9fca2b23d0ba 443 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 444 * request to.
marcozecchini 0:9fca2b23d0ba 445 * @param attribute_handle Handle of the attribute to write.
marcozecchini 0:9fca2b23d0ba 446 * @param value Value to write. It can't be longer than (mtu - 3).
marcozecchini 0:9fca2b23d0ba 447 *
marcozecchini 0:9fca2b23d0ba 448 * @return BLE_ERROR_NONE if the request has been successfully sent or an
marcozecchini 0:9fca2b23d0ba 449 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 450 *
marcozecchini 0:9fca2b23d0ba 451 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.5.1
marcozecchini 0:9fca2b23d0ba 452 */
marcozecchini 0:9fca2b23d0ba 453 virtual ble_error_t write_request(
marcozecchini 0:9fca2b23d0ba 454 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 455 attribute_handle_t attribute_handle,
marcozecchini 0:9fca2b23d0ba 456 const ArrayView<const uint8_t>& value
marcozecchini 0:9fca2b23d0ba 457 ) = 0;
marcozecchini 0:9fca2b23d0ba 458
marcozecchini 0:9fca2b23d0ba 459 /**
marcozecchini 0:9fca2b23d0ba 460 * Send a write command to the server. A write command is similar to a write
marcozecchini 0:9fca2b23d0ba 461 * request except that it won't receive any response from the server
marcozecchini 0:9fca2b23d0ba 462 *
marcozecchini 0:9fca2b23d0ba 463 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 464 * request to.
marcozecchini 0:9fca2b23d0ba 465 * @param attribute_handle Handle of the attribute to write.
marcozecchini 0:9fca2b23d0ba 466 * @param value Value to write. It can't be longer than (mtu - 3).
marcozecchini 0:9fca2b23d0ba 467 *
marcozecchini 0:9fca2b23d0ba 468 * @return BLE_ERROR_NONE if the request has been successfully sent or an
marcozecchini 0:9fca2b23d0ba 469 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 470 *
marcozecchini 0:9fca2b23d0ba 471 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.5.3
marcozecchini 0:9fca2b23d0ba 472 */
marcozecchini 0:9fca2b23d0ba 473 virtual ble_error_t write_command(
marcozecchini 0:9fca2b23d0ba 474 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 475 attribute_handle_t attribute_handle,
marcozecchini 0:9fca2b23d0ba 476 const ArrayView<const uint8_t>& value
marcozecchini 0:9fca2b23d0ba 477 ) = 0;
marcozecchini 0:9fca2b23d0ba 478
marcozecchini 0:9fca2b23d0ba 479 /**
marcozecchini 0:9fca2b23d0ba 480 * Send a signed write command to the server. Behaviour is similar to a write
marcozecchini 0:9fca2b23d0ba 481 * command except that 12 bytes of the mtu are reserved for the authentication
marcozecchini 0:9fca2b23d0ba 482 * signature.
marcozecchini 0:9fca2b23d0ba 483 *
marcozecchini 0:9fca2b23d0ba 484 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 485 * request to.
marcozecchini 0:9fca2b23d0ba 486 * @param attribute_handle Handle of the attribute to write.
marcozecchini 0:9fca2b23d0ba 487 * @param value Value to write. It can't be longer than (mtu - 15).
marcozecchini 0:9fca2b23d0ba 488 *
marcozecchini 0:9fca2b23d0ba 489 * @note the authentication signature to send with this request is
marcozecchini 0:9fca2b23d0ba 490 * computed by the implementation following the rules defined in BLUETOOTH
marcozecchini 0:9fca2b23d0ba 491 * SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.3.1.
marcozecchini 0:9fca2b23d0ba 492 *
marcozecchini 0:9fca2b23d0ba 493 * @return BLE_ERROR_NONE if the request has been successfully sent or an
marcozecchini 0:9fca2b23d0ba 494 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 495 *
marcozecchini 0:9fca2b23d0ba 496 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.5.4
marcozecchini 0:9fca2b23d0ba 497 */
marcozecchini 0:9fca2b23d0ba 498 virtual ble_error_t signed_write_command(
marcozecchini 0:9fca2b23d0ba 499 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 500 attribute_handle_t attribute_handle,
marcozecchini 0:9fca2b23d0ba 501 const ArrayView<const uint8_t>& value
marcozecchini 0:9fca2b23d0ba 502 ) = 0;
marcozecchini 0:9fca2b23d0ba 503
marcozecchini 0:9fca2b23d0ba 504 /**
marcozecchini 0:9fca2b23d0ba 505 * The Prepare Write Request is used to request the server to prepare to
marcozecchini 0:9fca2b23d0ba 506 * write the value of an attribute. The client can send multiple prepare
marcozecchini 0:9fca2b23d0ba 507 * write request which will be put in a queue until the client send an
marcozecchini 0:9fca2b23d0ba 508 * Execute Write Request which will execute sequentially the write request
marcozecchini 0:9fca2b23d0ba 509 * in the queue.
marcozecchini 0:9fca2b23d0ba 510 *
marcozecchini 0:9fca2b23d0ba 511 * In case of success the server will respond with a
marcozecchini 0:9fca2b23d0ba 512 * ble::pal::AttPrepareWriteResponse containing the values (attribute handle,
marcozecchini 0:9fca2b23d0ba 513 * offset and value) present in the write request.
marcozecchini 0:9fca2b23d0ba 514 *
marcozecchini 0:9fca2b23d0ba 515 * If a prepare write request is rejected by the server, the state queue of
marcozecchini 0:9fca2b23d0ba 516 * the prepare write request queue remains unaltered.
marcozecchini 0:9fca2b23d0ba 517 *
marcozecchini 0:9fca2b23d0ba 518 * In case of error, the server will send a ble::pal::AttErrorResponse. The
marcozecchini 0:9fca2b23d0ba 519 * error code depends on the situation:
marcozecchini 0:9fca2b23d0ba 520 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the handle to write is
marcozecchini 0:9fca2b23d0ba 521 * invalid.
marcozecchini 0:9fca2b23d0ba 522 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client
marcozecchini 0:9fca2b23d0ba 523 * security is not sufficient to write the requested attribute.
marcozecchini 0:9fca2b23d0ba 524 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client
marcozecchini 0:9fca2b23d0ba 525 * authorization is not sufficient to write the requested attribute.
marcozecchini 0:9fca2b23d0ba 526 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the
marcozecchini 0:9fca2b23d0ba 527 * client has an insufficient encryption key size to write the requested
marcozecchini 0:9fca2b23d0ba 528 * attributes.
marcozecchini 0:9fca2b23d0ba 529 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client
marcozecchini 0:9fca2b23d0ba 530 * has not enabled encryption required to write the requested attributes.
marcozecchini 0:9fca2b23d0ba 531 * - ble::pal::AttErrorResponse::WRITE_NOT_PERMITTED: If the attribute
marcozecchini 0:9fca2b23d0ba 532 * value cannot be written due to permission.
marcozecchini 0:9fca2b23d0ba 533 * - ble::pal::PREPARE_QUEUE_FULL: If the queue of prepare write request
marcozecchini 0:9fca2b23d0ba 534 * is full.
marcozecchini 0:9fca2b23d0ba 535 * Higher layer can also set an application error code (0x80 - 0x9F).
marcozecchini 0:9fca2b23d0ba 536 *
marcozecchini 0:9fca2b23d0ba 537 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 538 * request to.
marcozecchini 0:9fca2b23d0ba 539 * @param attribute_handle The handle of the attribute to be written.
marcozecchini 0:9fca2b23d0ba 540 * @param offset The offset of the first octet to be written.
marcozecchini 0:9fca2b23d0ba 541 * @param value The value of the attribute to be written. It can't be longer
marcozecchini 0:9fca2b23d0ba 542 * than (mtu - 5).
marcozecchini 0:9fca2b23d0ba 543 *
marcozecchini 0:9fca2b23d0ba 544 * @return BLE_ERROR_NONE if the request has been successfully sent or an
marcozecchini 0:9fca2b23d0ba 545 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 546 *
marcozecchini 0:9fca2b23d0ba 547 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.6.1
marcozecchini 0:9fca2b23d0ba 548 *
marcozecchini 0:9fca2b23d0ba 549 */
marcozecchini 0:9fca2b23d0ba 550 virtual ble_error_t prepare_write_request(
marcozecchini 0:9fca2b23d0ba 551 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 552 attribute_handle_t attribute_handle,
marcozecchini 0:9fca2b23d0ba 553 uint16_t offset,
marcozecchini 0:9fca2b23d0ba 554 const ArrayView<const uint8_t>& value
marcozecchini 0:9fca2b23d0ba 555 ) = 0;
marcozecchini 0:9fca2b23d0ba 556
marcozecchini 0:9fca2b23d0ba 557 /**
marcozecchini 0:9fca2b23d0ba 558 * Send an Execute Write Request to the server. This request will instruct
marcozecchini 0:9fca2b23d0ba 559 * the server to execute or cancel the prepare write requests currently held
marcozecchini 0:9fca2b23d0ba 560 * in the prepare queue from this client.
marcozecchini 0:9fca2b23d0ba 561 *
marcozecchini 0:9fca2b23d0ba 562 * If the execute parameter is set to true, the server should execute the
marcozecchini 0:9fca2b23d0ba 563 * request held in the queue. If the parameter is equal to false then the
marcozecchini 0:9fca2b23d0ba 564 * server should cancel the requests in the queue.
marcozecchini 0:9fca2b23d0ba 565 *
marcozecchini 0:9fca2b23d0ba 566 * In case of success, the server will respond with a
marcozecchini 0:9fca2b23d0ba 567 * ble::pal::AttExecuteWriteResponse indicating that the request was correctly
marcozecchini 0:9fca2b23d0ba 568 * handled.
marcozecchini 0:9fca2b23d0ba 569 *
marcozecchini 0:9fca2b23d0ba 570 * In case of error, the server will send a ble::pal::AttErrorResponse. The
marcozecchini 0:9fca2b23d0ba 571 * error code depends on the situation:
marcozecchini 0:9fca2b23d0ba 572 * - ble::pal::AttErrorResponse::INVALID_OFFSET: If the value offset is
marcozecchini 0:9fca2b23d0ba 573 * greater than the current length of the attribute to write.
marcozecchini 0:9fca2b23d0ba 574 * - ble::pal::AttErrorResponse::INVALID_ATTRIBUTE_VALUE_LENGTH: If the
marcozecchini 0:9fca2b23d0ba 575 * length of the value write exceeds the length of the attribute value
marcozecchini 0:9fca2b23d0ba 576 * about to be written.
marcozecchini 0:9fca2b23d0ba 577 * Higher layer can also set an application error code (0x80 - 0x9F).
marcozecchini 0:9fca2b23d0ba 578 *
marcozecchini 0:9fca2b23d0ba 579 * The error response will contains the attribute handle which as caused the
marcozecchini 0:9fca2b23d0ba 580 * error and the remaining of the prepare queue is discarded. The state of
marcozecchini 0:9fca2b23d0ba 581 * the attributes that were to be written from the prepare queue is not
marcozecchini 0:9fca2b23d0ba 582 * defined in this case.
marcozecchini 0:9fca2b23d0ba 583 *
marcozecchini 0:9fca2b23d0ba 584 * @param connection_handle The handle of the connection to send this
marcozecchini 0:9fca2b23d0ba 585 * request to.
marcozecchini 0:9fca2b23d0ba 586 * @param execute Boolean indicating if the prepare queue should be executed
marcozecchini 0:9fca2b23d0ba 587 * or cleared.
marcozecchini 0:9fca2b23d0ba 588 *
marcozecchini 0:9fca2b23d0ba 589 * @return BLE_ERROR_NONE if the request has been successfully sent or an
marcozecchini 0:9fca2b23d0ba 590 * appropriate error otherwise.
marcozecchini 0:9fca2b23d0ba 591 *
marcozecchini 0:9fca2b23d0ba 592 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.6.3
marcozecchini 0:9fca2b23d0ba 593 */
marcozecchini 0:9fca2b23d0ba 594 virtual ble_error_t execute_write_request(
marcozecchini 0:9fca2b23d0ba 595 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 596 bool execute
marcozecchini 0:9fca2b23d0ba 597 ) = 0;
marcozecchini 0:9fca2b23d0ba 598
marcozecchini 0:9fca2b23d0ba 599 /**
marcozecchini 0:9fca2b23d0ba 600 * Register a callback which will handle messages from the server.
marcozecchini 0:9fca2b23d0ba 601 *
marcozecchini 0:9fca2b23d0ba 602 * @param cb The callback object which will handle messages from the server.
marcozecchini 0:9fca2b23d0ba 603 * It accept two parameters in input: The handle of the connection where the
marcozecchini 0:9fca2b23d0ba 604 * message was received and the message received. Real type of the message
marcozecchini 0:9fca2b23d0ba 605 * can be obtained from its opcode.
marcozecchini 0:9fca2b23d0ba 606 */
marcozecchini 0:9fca2b23d0ba 607 void when_server_message_received(
marcozecchini 0:9fca2b23d0ba 608 mbed::Callback<void(connection_handle_t, const AttServerMessage&)> cb
marcozecchini 0:9fca2b23d0ba 609 ) {
marcozecchini 0:9fca2b23d0ba 610 _server_message_cb = cb;
marcozecchini 0:9fca2b23d0ba 611 }
marcozecchini 0:9fca2b23d0ba 612
marcozecchini 0:9fca2b23d0ba 613 /**
marcozecchini 0:9fca2b23d0ba 614 * Register a callback handling transaction timeout.
marcozecchini 0:9fca2b23d0ba 615 *
marcozecchini 0:9fca2b23d0ba 616 * @param cb The callback handling timeout of a transaction. It accepts as
marcozecchini 0:9fca2b23d0ba 617 * a parameter the connection handle involved in the timeout.
marcozecchini 0:9fca2b23d0ba 618 *
marcozecchini 0:9fca2b23d0ba 619 * @note No more attribute protocol requests, commands, indication or
marcozecchini 0:9fca2b23d0ba 620 * notification shall be sent over a connection implied in a transaction
marcozecchini 0:9fca2b23d0ba 621 * timeout. To send a new ATT message, the conenction should be
marcozecchini 0:9fca2b23d0ba 622 * reestablished.
marcozecchini 0:9fca2b23d0ba 623 */
marcozecchini 0:9fca2b23d0ba 624 void when_transaction_timeout(
marcozecchini 0:9fca2b23d0ba 625 mbed::Callback<void(connection_handle_t)> cb
marcozecchini 0:9fca2b23d0ba 626 ) {
marcozecchini 0:9fca2b23d0ba 627 _transaction_timeout_cb = cb;
marcozecchini 0:9fca2b23d0ba 628 }
marcozecchini 0:9fca2b23d0ba 629
marcozecchini 0:9fca2b23d0ba 630 protected:
marcozecchini 0:9fca2b23d0ba 631 AttClient() { }
marcozecchini 0:9fca2b23d0ba 632
marcozecchini 0:9fca2b23d0ba 633 virtual ~AttClient() { }
marcozecchini 0:9fca2b23d0ba 634
marcozecchini 0:9fca2b23d0ba 635 /**
marcozecchini 0:9fca2b23d0ba 636 * Upon server message reception an implementation shall call this function.
marcozecchini 0:9fca2b23d0ba 637 *
marcozecchini 0:9fca2b23d0ba 638 * @param connection_handle The handle of the connection which has received
marcozecchini 0:9fca2b23d0ba 639 * the server message.
marcozecchini 0:9fca2b23d0ba 640 * @param server_message The message received from the server.
marcozecchini 0:9fca2b23d0ba 641 */
marcozecchini 0:9fca2b23d0ba 642 void on_server_event(
marcozecchini 0:9fca2b23d0ba 643 connection_handle_t connection_handle,
marcozecchini 0:9fca2b23d0ba 644 const AttServerMessage& server_message
marcozecchini 0:9fca2b23d0ba 645 ) {
marcozecchini 0:9fca2b23d0ba 646 if (_server_message_cb) {
marcozecchini 0:9fca2b23d0ba 647 _server_message_cb(connection_handle, server_message);
marcozecchini 0:9fca2b23d0ba 648 }
marcozecchini 0:9fca2b23d0ba 649 }
marcozecchini 0:9fca2b23d0ba 650
marcozecchini 0:9fca2b23d0ba 651 /**
marcozecchini 0:9fca2b23d0ba 652 * Upon transaction timeout an implementation shall call this function.
marcozecchini 0:9fca2b23d0ba 653 *
marcozecchini 0:9fca2b23d0ba 654 * @param connection_handle The handle of the connection of the transaction
marcozecchini 0:9fca2b23d0ba 655 * which has times out.
marcozecchini 0:9fca2b23d0ba 656 *
marcozecchini 0:9fca2b23d0ba 657 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.3.3
marcozecchini 0:9fca2b23d0ba 658 */
marcozecchini 0:9fca2b23d0ba 659 void on_transaction_timeout(
marcozecchini 0:9fca2b23d0ba 660 connection_handle_t connection_handle
marcozecchini 0:9fca2b23d0ba 661 ) {
marcozecchini 0:9fca2b23d0ba 662 if (_transaction_timeout_cb) {
marcozecchini 0:9fca2b23d0ba 663 _transaction_timeout_cb(connection_handle);
marcozecchini 0:9fca2b23d0ba 664 }
marcozecchini 0:9fca2b23d0ba 665 }
marcozecchini 0:9fca2b23d0ba 666
marcozecchini 0:9fca2b23d0ba 667 private:
marcozecchini 0:9fca2b23d0ba 668 /**
marcozecchini 0:9fca2b23d0ba 669 * Callback called when the client receive a message from the server.
marcozecchini 0:9fca2b23d0ba 670 */
marcozecchini 0:9fca2b23d0ba 671 mbed::Callback<void(connection_handle_t, const AttServerMessage&)> _server_message_cb;
marcozecchini 0:9fca2b23d0ba 672
marcozecchini 0:9fca2b23d0ba 673 /**
marcozecchini 0:9fca2b23d0ba 674 * Callback called when a transaction times out.
marcozecchini 0:9fca2b23d0ba 675 */
marcozecchini 0:9fca2b23d0ba 676 mbed::Callback<void(connection_handle_t)> _transaction_timeout_cb;
marcozecchini 0:9fca2b23d0ba 677
marcozecchini 0:9fca2b23d0ba 678 // Disallow copy construction and copy assignment.
marcozecchini 0:9fca2b23d0ba 679 AttClient(const AttClient&);
marcozecchini 0:9fca2b23d0ba 680 AttClient& operator=(const AttClient&);
marcozecchini 0:9fca2b23d0ba 681 };
marcozecchini 0:9fca2b23d0ba 682
marcozecchini 0:9fca2b23d0ba 683
marcozecchini 0:9fca2b23d0ba 684 } // namespace pal
marcozecchini 0:9fca2b23d0ba 685 } // namespace ble
marcozecchini 0:9fca2b23d0ba 686
marcozecchini 0:9fca2b23d0ba 687 #endif /* BLE_PAL_ATTCLIENT_H_ */