Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

features/FEATURE_BLE/ble/pal/AttClient.h@1:9db0e321a9f4, 2019-12-31 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 31 06:02:27 2019 +0000
Revision:
1:9db0e321a9f4
Parent:
0:5b88d5760320 
updated based on mbed-os5.15.0

Who changed what in which revision?

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