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.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
AttClient.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2017-2017 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef BLE_PAL_ATTCLIENT_H_ 00018 #define BLE_PAL_ATTCLIENT_H_ 00019 00020 #include "ble/common/StaticInterface.h" 00021 #include "ble/UUID.h " 00022 #include "ble/BLETypes.h" 00023 #include "ble/blecommon.h" 00024 #include "platform/Callback.h" 00025 #include "AttServerMessage.h" 00026 00027 namespace ble { 00028 namespace pal { 00029 00030 /** 00031 * Send attribute protocol requests to an ATT server. It also handle reception 00032 * of ATT response and server indication/notification. 00033 * 00034 * Every request send and response or response event received is for a specified 00035 * connection. 00036 * 00037 * @warning This class should not be used outside mbed BLE, availability is not 00038 * guaranteed for all ports. 00039 * 00040 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F 00041 */ 00042 template<class Impl> 00043 struct AttClient : public StaticInterface<Impl, AttClient> { 00044 private: 00045 00046 using StaticInterface<Impl, ble::pal::AttClient>::impl; 00047 00048 public: 00049 00050 00051 /** 00052 * Initialization of the instance. An implementation can use this function 00053 * to initialise the subsystems needed to realize the ATT operations of this 00054 * interface. 00055 * 00056 * This function has to be called before any other operations. 00057 * 00058 * @return BLE_ERROR_NONE if the request has been successfully sent or the 00059 * appropriate error otherwise. 00060 */ 00061 ble_error_t initialize() { 00062 return impl ()->initialize_(); 00063 } 00064 00065 /** 00066 * Termination of the instance. An implementation can use this function 00067 * to release the subsystems initialised to realise the ATT operations of 00068 * this interface. 00069 * 00070 * After a call to this function, initialise should be called again to 00071 * allow usage of the interface. 00072 * 00073 * @return BLE_ERROR_NONE if the request has been successfully sent or the 00074 * appropriate error otherwise. 00075 */ 00076 ble_error_t terminate() { 00077 return impl ()->terminate_(); 00078 } 00079 00080 /** 00081 * Send an exchange MTU request which negotiate the size of the MTU used by 00082 * the connection. 00083 * 00084 * First the client send to the server the maximum rx mtu that it can receive 00085 * then the client reply with the maximum rx mtu it can receive. 00086 * 00087 * The mtu choosen for the connection is the minimum of the client Rx mtu 00088 * and server Rx mtu values. 00089 * 00090 * If an error occured then the mtu used remains the default value. 00091 * 00092 * @param connection The handle of the connection to send this request to. 00093 * 00094 * @return BLE_ERROR_NONE if the request has been succesfully sent or the 00095 * appropriate error otherwise. 00096 * 00097 * @see ble::pal::AttExchangeMTUResponse The type of response received from 00098 * the server 00099 * @see ble::pal::AttErrorResponse::REQUEST_NOT_SUPPORTED The error code 00100 * returned by the server in case of error. 00101 * 00102 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.2.1 00103 */ 00104 ble_error_t exchange_mtu_request(connection_handle_t connection) { 00105 return impl ()->exchange_mtu_request_(connection); 00106 } 00107 00108 /** 00109 * Acquire the size of the mtu for a given connection. 00110 * 00111 * @param connection The handle of the connection for which the the MTU size 00112 * should be acquired. 00113 * 00114 * @param mtu_size Output parameter which will contain the MTU size. 00115 * 00116 * @return BLE_ERROR_NONE if the MTU size has been acquired or the 00117 * appropriate error otherwise. 00118 */ 00119 ble_error_t get_mtu_size( 00120 connection_handle_t connection_handle, 00121 uint16_t& mtu_size 00122 ) { 00123 return impl ()->get_mtu_size_(connection_handle, mtu_size); 00124 } 00125 00126 /** 00127 * Send a find information request to a server in order to obtain the 00128 * mapping of attribute handles with their associated types. 00129 * 00130 * The server will reply with a ble::pal::AttFindInformationResponse 00131 * containing at least one [attribute handle, attribute type] pair. If the 00132 * last handle in the response is not equal to the end handle of the finding 00133 * range then this request can be issued again with an updated range (begin 00134 * equal to last handle received + 1) to discover the remaining attributes. 00135 * 00136 * To discover the whole ATT server, the first find information request 00137 * should have a discovery range of [0x0001 - 0xFFFF]. 00138 * 00139 * The server can send a ble::pal::AttErrorResponse with the code 00140 * ble::pal::AttErrorResponse::ATTRIBUTE_NOT_FOUND if no attributes have 00141 * been found in the range specified. The attribute handle in the response 00142 * is then equal to the first handle of the discovery range. 00143 * 00144 * If the range is malformed the server will reply a 00145 * ble::pal::AttErrorResponse with the error code ble::pal::INVALID_HANDLE. 00146 * 00147 * @param connection_handle The handle of the connection to send this 00148 * request to. 00149 * @param discovery_range The attribute range where handle-type informations 00150 * should be discovered. 00151 * 00152 * @return BLE_ERROR_NONE if the request has been successfully sent or the 00153 * appropriate error otherwise. 00154 * 00155 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.3.1 00156 */ 00157 ble_error_t find_information_request( 00158 connection_handle_t connection_handle, 00159 attribute_handle_range_t discovery_range 00160 ) { 00161 return impl ()->find_information_request_(connection_handle, discovery_range); 00162 } 00163 00164 /** 00165 * Send a Find By Type Value Request which retrieve the handles of attributes 00166 * that have known 16-bit UUID attribute type and known attribute value. 00167 * 00168 * The server should reply with a ble::pal::AttFindByTypeValueResponse 00169 * containing the handle (or handle range in case of grouping attributes) of 00170 * the attribute found. 00171 * 00172 * If not all attributes can be contained in the response it is necessary to 00173 * send again this request with an updated range to continue the discovery. 00174 * 00175 * The server can send a ble::pal::AttErrorResponse with the code 00176 * ble::pal::AttErrorResponse::ATTRIBUTE_NOT_FOUND if no attributes have 00177 * been found in the range specified. The attribute handle in the response 00178 * is then equal to the first handle of the discovery range. 00179 * 00180 * If the range is malformed the server will reply a 00181 * ble::pal::AttErrorResponse with the error code ble::pal::INVALID_HANDLE. 00182 * 00183 * @param connection_handle The handle of the connection to send this 00184 * request to. 00185 * @param discovery_range The handle range where attributes with type and 00186 * value are searched. 00187 * @param type The type of attribute to find (it is a 16 bit UUID). 00188 * @param value The value of the attributes to found. 00189 * 00190 * @return BLE_ERROR_NONE if the request has been successfully sent or the 00191 * appropriate error otherwise. 00192 * 00193 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.3.3 00194 */ 00195 ble_error_t find_by_type_value_request( 00196 connection_handle_t connection_handle, 00197 attribute_handle_range_t discovery_range, 00198 uint16_t type, 00199 const Span<const uint8_t>& value 00200 ) { 00201 return impl ()->find_by_type_value_request_( 00202 connection_handle, 00203 discovery_range, 00204 type, 00205 value 00206 ); 00207 } 00208 00209 /** 00210 * Send a Read By Type Request used to obtain the values of attributes where 00211 * the attribute type is known but the handle is not known. 00212 * 00213 * If attributes with the type requested are present in the range, the server 00214 * should reply with a ble::pal::AttReadByTypeResponse. If the response does 00215 * not cover the full range, the request should be sent again with an updated 00216 * range. 00217 * 00218 * In case of error, the server will send a ble::pal::AttErrorResponse. The 00219 * error code depends on the situation: 00220 * - ble::pal::AttErrorResponse::ATTRIBUTE_NOT_FOUND: If there is no 00221 * attributes matching type in the range. 00222 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the range is 00223 * invalid. 00224 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client 00225 * security is not sufficient. 00226 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client 00227 * authorization is not sufficient. 00228 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the 00229 * client has an insufficient encryption key size. 00230 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client 00231 * has not enabled encryption. 00232 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If the attribute 00233 * value cannot be read. 00234 * 00235 * @param connection_handle The handle of the connection to send this 00236 * request to. 00237 * @param read_range The handle range where attributes with the given type 00238 * should be read. 00239 * @param type The type of attributes to read. 00240 * 00241 * @return BLE_ERROR_NONE if the request has been successfully sent or the 00242 * appropriate error otherwise. 00243 * 00244 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.1 00245 */ 00246 ble_error_t read_by_type_request( 00247 connection_handle_t connection_handle, 00248 attribute_handle_range_t read_range, 00249 const UUID& type 00250 ) { 00251 return impl ()->read_by_type_request_(connection_handle, read_range, type); 00252 } 00253 00254 /** 00255 * Send a Read Request to read the value of an attribute in the server. 00256 * 00257 * In case of success, the server will reply with a ble::pal::AttReadResponse. 00258 * containing the value of the attribute. If the length of the value in the 00259 * response is equal to (mtu - 1) then the remaining part of the value can 00260 * be obtained by a read_blob_request. 00261 * 00262 * In case of error, the server will send a ble::pal::AttErrorResponse. The 00263 * error code depends on the situation: 00264 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the attribute handle 00265 * is invalid. 00266 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client 00267 * security is not sufficient. 00268 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client 00269 * authorization is not sufficient. 00270 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the 00271 * client has an insufficient encryption key size. 00272 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client 00273 * has not enabled encryption. 00274 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If the attribute 00275 * value cannot be read. 00276 * Higher layer can also set an application error code (0x80 - 0x9F). 00277 * 00278 * @param connection_handle The handle of the connection to send this 00279 * request to. 00280 * @param attribute_handle The handle of the attribute to read. 00281 * 00282 * @return BLE_ERROR_NONE if the request has been successfully sent or the 00283 * appropriate error otherwise. 00284 * 00285 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.3 00286 */ 00287 ble_error_t read_request( 00288 connection_handle_t connection_handle, 00289 attribute_handle_t attribute_handle 00290 ) { 00291 return impl ()->read_request_(connection_handle, attribute_handle); 00292 } 00293 00294 /** 00295 * Send a read blob request to a server to read a part of the value of an 00296 * attribute at a given offset. 00297 * 00298 * In case of success, the server will reply with a ble::pal::AttReadBlobResponse 00299 * containing the value read. If the value of the attribute starting at the 00300 * offset requested is longer than (mtu - 1) octets then only the first 00301 * (mtu - 1) octets will be present in the response. 00302 * The remaining octets can be acquired by another Read Blob Request with an 00303 * updated index. 00304 * 00305 * In case of error, the server will send a ble::pal::AttErrorResponse. The 00306 * error code depends on the situation: 00307 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the attribute handle 00308 * is invalid. 00309 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client 00310 * security is not sufficient. 00311 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client 00312 * authorization is not sufficient. 00313 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the 00314 * client has an insufficient encryption key size. 00315 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client 00316 * has not enabled encryption. 00317 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If the attribute 00318 * value cannot be read. 00319 * - ble::pal::AttErrorResponse::INVALID_OFFSET: If the offset is greater 00320 * than the attribute length. 00321 * - ble::pal::AttErrorResponse::ATTRIBUTE_NOT_LONG: If the attribute 00322 * value has a length that is less than or equal to (mtu - 1). 00323 * Higher layer can also set an application error code (0x80 - 0x9F). 00324 * 00325 * @param connection_handle The handle of the connection to send this 00326 * request to. 00327 * @param attribute_handle The handle of the attribute to read. 00328 * @param offset The offset of the first octet to read. 00329 * 00330 * @return BLE_ERROR_NONE if the request has been successfully sent or an 00331 * appropriate error otherwise. 00332 * 00333 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.5 00334 */ 00335 ble_error_t read_blob_request( 00336 connection_handle_t connection_handle, 00337 attribute_handle_t attribute_handle, 00338 uint16_t offset 00339 ) { 00340 return impl ()->read_blob_request_(connection_handle, attribute_handle, offset); 00341 } 00342 00343 /** 00344 * Send a read multiple request to the server. It is used to read two or more 00345 * attributes values at once. 00346 * 00347 * In case of success, the server will reply with a 00348 * ble::pal::AttReadMultipleResponse containing the concatenation of the 00349 * values read. Given that values are concatained, all attributes values 00350 * should be of fixed size except for the last one. The concatained value 00351 * is also truncated to (mtu - 1) if it doesn't fit in the response. 00352 * 00353 * In case of error, the server will send a ble::pal::AttErrorResponse. The 00354 * error code depends on the situation: 00355 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If any of the attribute 00356 * handle is invalid. 00357 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client 00358 * security is not sufficient to read any of the attribute. 00359 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client 00360 * authorization is not sufficient to read any of the attribute. 00361 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the 00362 * client has an insufficient encryption key size to read any of the 00363 * attributes. 00364 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client 00365 * has not enabled encryption required to read any of the attributes. 00366 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If any of the 00367 * attributes value cannot be read. 00368 * The first attribute causing the error is reporter in the handle_in_error 00369 * field in the error response. 00370 * Higher layer can also set an application error code (0x80 - 0x9F). 00371 * 00372 * @param connection_handle The handle of the connection to send this 00373 * request to. 00374 * @param attribute_handles Set of attribute handles to read. 00375 * 00376 * @return BLE_ERROR_NONE if the request has been successfully sent or an 00377 * appropriate error otherwise. 00378 * 00379 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.7 00380 */ 00381 ble_error_t read_multiple_request( 00382 connection_handle_t connection_handle, 00383 const Span<const attribute_handle_t>& attribute_handles 00384 ) { 00385 return impl ()->read_multiple_request_(connection_handle, attribute_handles); 00386 } 00387 00388 /** 00389 * Send a read by group type request to the server. It is used to get 00390 * informations about grouping attribute of a given type on a server. 00391 * 00392 * The server will reply with a ble::pal::ReadByGroupTypeResponse containing 00393 * informations about the grouping attribute found. Informations are: 00394 * - handle of the grouping attribute. 00395 * - last handle of the group . 00396 * - attribute value. 00397 * 00398 * If the last handle received is not the last handle of the discovery range 00399 * then it is necessary to send another request with a discovery range 00400 * updated to: [last handle + 1 : end]. 00401 * 00402 * In case of error, the server will send a ble::pal::AttErrorResponse. The 00403 * error code depends on the situation: 00404 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the range of handle 00405 * provided is invalid. 00406 * - ble::pal::AttErrorResponse::UNSUPPORTED_GROUP_TYPE: if the group type 00407 * is not a supported grouping attribute. 00408 * - ble::pal::AttErrorResponse::ATTRIBUTE_NOT_FOUND: If no attribute with 00409 * the given type exists within the range provided. 00410 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client 00411 * security is not sufficient to read the requested attribute. 00412 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client 00413 * authorization is not sufficient to read the requested attribute. 00414 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the 00415 * client has an insufficient encryption key size to read the requested 00416 * attributes. 00417 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client 00418 * has not enabled encryption required to read the requested attributes. 00419 * - ble::pal::AttErrorResponse::READ_NOT_PERMITTED: If any of the 00420 * attributes value cannot be read. 00421 * Higher layer can also set an application error code (0x80 - 0x9F). 00422 * 00423 * @param connection_handle The handle of the connection to send this 00424 * request to. 00425 * @param read_range Range where this request apply. 00426 * @param group_type Type of the grouping attribute to find and read. 00427 * 00428 * @return BLE_ERROR_NONE if the request has been successfully sent or an 00429 * appropriate error otherwise. 00430 * 00431 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.4.9 00432 */ 00433 ble_error_t read_by_group_type_request( 00434 connection_handle_t connection_handle, 00435 attribute_handle_range_t read_range, 00436 const UUID& group_type 00437 ) { 00438 return impl ()->read_by_group_type_request_(connection_handle, read_range, group_type); 00439 } 00440 00441 /** 00442 * Send a write request to the server to write the value of an attribute. 00443 * 00444 * In case of success, the server will reply with a 00445 * ble::pal::AttWriteResponse to acknowledge that the write operation went 00446 * well. 00447 * 00448 * If the attribute value has a variable length, then the attribute value 00449 * shall be truncated or lengthened to match the length of the value in the 00450 * request. 00451 * 00452 * If the attribute value has a fixed length and the Attribute Value parameter length 00453 * is less than or equal to the length of the attribute value, the octets of the 00454 * attribute value parameter length shall be written; all other octets in this attribute 00455 * value shall be unchanged. 00456 * 00457 * In case of error, the server will send a ble::pal::AttErrorResponse. The 00458 * error code depends on the situation: 00459 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the handle to write is 00460 * invalid. 00461 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client 00462 * security is not sufficient to write the requested attribute. 00463 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client 00464 * authorization is not sufficient to write the requested attribute. 00465 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the 00466 * client has an insufficient encryption key size to write the requested 00467 * attributes. 00468 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client 00469 * has not enabled encryption required to write the requested attributes. 00470 * - ble::pal::AttErrorResponse::WRITE_NOT_PERMITTED: If the attribute 00471 * value cannot be written due to permission. 00472 * - ble::pal::AttErrorResponse::INVALID_ATTRIBUTE_VALUE_LENGTH: If the 00473 * value to write exceeds the maximum valid length or of the attribute 00474 * value; whether the attribute has a variable length value or a fixed 00475 * length value. 00476 * Higher layer can also set an application error code (0x80 - 0x9F). 00477 * 00478 * @param connection_handle The handle of the connection to send this 00479 * request to. 00480 * @param attribute_handle Handle of the attribute to write. 00481 * @param value Value to write. It can't be longer than (mtu - 3). 00482 * 00483 * @return BLE_ERROR_NONE if the request has been successfully sent or an 00484 * appropriate error otherwise. 00485 * 00486 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.5.1 00487 */ 00488 ble_error_t write_request( 00489 connection_handle_t connection_handle, 00490 attribute_handle_t attribute_handle, 00491 const Span<const uint8_t>& value 00492 ) { 00493 return impl ()->write_request_(connection_handle, attribute_handle, value); 00494 } 00495 00496 /** 00497 * Send a write command to the server. A write command is similar to a write 00498 * request except that it won't receive any response from the server 00499 * 00500 * @param connection_handle The handle of the connection to send this 00501 * request to. 00502 * @param attribute_handle Handle of the attribute to write. 00503 * @param value Value to write. It can't be longer than (mtu - 3). 00504 * 00505 * @return BLE_ERROR_NONE if the request has been successfully sent or an 00506 * appropriate error otherwise. 00507 * 00508 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.5.3 00509 */ 00510 ble_error_t write_command( 00511 connection_handle_t connection_handle, 00512 attribute_handle_t attribute_handle, 00513 const Span<const uint8_t>& value 00514 ) { 00515 return impl ()->write_command_(connection_handle, attribute_handle, value); 00516 } 00517 00518 /** 00519 * Send a signed write command to the server. Behaviour is similar to a write 00520 * command except that 12 bytes of the mtu are reserved for the authentication 00521 * signature. 00522 * 00523 * @param connection_handle The handle of the connection to send this 00524 * request to. 00525 * @param attribute_handle Handle of the attribute to write. 00526 * @param value Value to write. It can't be longer than (mtu - 15). 00527 * 00528 * @note the authentication signature to send with this request is 00529 * computed by the implementation following the rules defined in BLUETOOTH 00530 * SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.3.1. 00531 * 00532 * @return BLE_ERROR_NONE if the request has been successfully sent or an 00533 * appropriate error otherwise. 00534 * 00535 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.5.4 00536 */ 00537 ble_error_t signed_write_command( 00538 connection_handle_t connection_handle, 00539 attribute_handle_t attribute_handle, 00540 const Span<const uint8_t>& value 00541 ) { 00542 return impl ()->signed_write_command_(connection_handle, attribute_handle, value); 00543 } 00544 00545 /** 00546 * The Prepare Write Request is used to request the server to prepare to 00547 * write the value of an attribute. The client can send multiple prepare 00548 * write request which will be put in a queue until the client send an 00549 * Execute Write Request which will execute sequentially the write request 00550 * in the queue. 00551 * 00552 * In case of success the server will respond with a 00553 * ble::pal::AttPrepareWriteResponse containing the values (attribute handle, 00554 * offset and value) present in the write request. 00555 * 00556 * If a prepare write request is rejected by the server, the state queue of 00557 * the prepare write request queue remains unaltered. 00558 * 00559 * In case of error, the server will send a ble::pal::AttErrorResponse. The 00560 * error code depends on the situation: 00561 * - ble::pal::AttErrorResponse::INVALID_HANDLE: If the handle to write is 00562 * invalid. 00563 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHENTICATION: If the client 00564 * security is not sufficient to write the requested attribute. 00565 * - ble::pal::AttErrorResponse::INSUFFICIENT_AUTHORIZATION: If the client 00566 * authorization is not sufficient to write the requested attribute. 00567 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION_KEY_SIZE: If the 00568 * client has an insufficient encryption key size to write the requested 00569 * attributes. 00570 * - ble::pal::AttErrorResponse::INSUFFICIENT_ENCRYPTION: If the client 00571 * has not enabled encryption required to write the requested attributes. 00572 * - ble::pal::AttErrorResponse::WRITE_NOT_PERMITTED: If the attribute 00573 * value cannot be written due to permission. 00574 * - ble::pal::PREPARE_QUEUE_FULL: If the queue of prepare write request 00575 * is full. 00576 * Higher layer can also set an application error code (0x80 - 0x9F). 00577 * 00578 * @param connection_handle The handle of the connection to send this 00579 * request to. 00580 * @param attribute_handle The handle of the attribute to be written. 00581 * @param offset The offset of the first octet to be written. 00582 * @param value The value of the attribute to be written. It can't be longer 00583 * than (mtu - 5). 00584 * 00585 * @return BLE_ERROR_NONE if the request has been successfully sent or an 00586 * appropriate error otherwise. 00587 * 00588 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.6.1 00589 * 00590 */ 00591 ble_error_t prepare_write_request( 00592 connection_handle_t connection_handle, 00593 attribute_handle_t attribute_handle, 00594 uint16_t offset, 00595 const Span<const uint8_t>& value 00596 ) { 00597 return impl ()->prepare_write_request_( 00598 connection_handle, 00599 attribute_handle, 00600 offset, 00601 value 00602 ); 00603 } 00604 00605 /** 00606 * Send an Execute Write Request to the server. This request will instruct 00607 * the server to execute or cancel the prepare write requests currently held 00608 * in the prepare queue from this client. 00609 * 00610 * If the execute parameter is set to true, the server should execute the 00611 * request held in the queue. If the parameter is equal to false then the 00612 * server should cancel the requests in the queue. 00613 * 00614 * In case of success, the server will respond with a 00615 * ble::pal::AttExecuteWriteResponse indicating that the request was correctly 00616 * handled. 00617 * 00618 * In case of error, the server will send a ble::pal::AttErrorResponse. The 00619 * error code depends on the situation: 00620 * - ble::pal::AttErrorResponse::INVALID_OFFSET: If the value offset is 00621 * greater than the current length of the attribute to write. 00622 * - ble::pal::AttErrorResponse::INVALID_ATTRIBUTE_VALUE_LENGTH: If the 00623 * length of the value write exceeds the length of the attribute value 00624 * about to be written. 00625 * Higher layer can also set an application error code (0x80 - 0x9F). 00626 * 00627 * The error response will contains the attribute handle which as caused the 00628 * error and the remaining of the prepare queue is discarded. The state of 00629 * the attributes that were to be written from the prepare queue is not 00630 * defined in this case. 00631 * 00632 * @param connection_handle The handle of the connection to send this 00633 * request to. 00634 * @param execute Boolean indicating if the prepare queue should be executed 00635 * or cleared. 00636 * 00637 * @return BLE_ERROR_NONE if the request has been successfully sent or an 00638 * appropriate error otherwise. 00639 * 00640 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.4.6.3 00641 */ 00642 ble_error_t execute_write_request( 00643 connection_handle_t connection_handle, 00644 bool execute 00645 ) { 00646 return impl ()->execute_write_request_(connection_handle, execute); 00647 } 00648 00649 /** 00650 * Register a callback which will handle messages from the server. 00651 * 00652 * @param cb The callback object which will handle messages from the server. 00653 * It accept two parameters in input: The handle of the connection where the 00654 * message was received and the message received. Real type of the message 00655 * can be obtained from its opcode. 00656 */ 00657 void when_server_message_received( 00658 mbed::Callback<void(connection_handle_t, const AttServerMessage&)> cb 00659 ) { 00660 _server_message_cb = cb; 00661 } 00662 00663 /** 00664 * Register a callback handling transaction timeout. 00665 * 00666 * @param cb The callback handling timeout of a transaction. It accepts as 00667 * a parameter the connection handle involved in the timeout. 00668 * 00669 * @note No more attribute protocol requests, commands, indication or 00670 * notification shall be sent over a connection implied in a transaction 00671 * timeout. To send a new ATT message, the conenction should be 00672 * reestablished. 00673 */ 00674 void when_transaction_timeout( 00675 mbed::Callback<void(connection_handle_t)> cb 00676 ) { 00677 _transaction_timeout_cb = cb; 00678 } 00679 00680 protected: 00681 AttClient() { } 00682 00683 ~AttClient() { } 00684 00685 /** 00686 * Upon server message reception an implementation shall call this function. 00687 * 00688 * @param connection_handle The handle of the connection which has received 00689 * the server message. 00690 * @param server_message The message received from the server. 00691 */ 00692 void on_server_event( 00693 connection_handle_t connection_handle, 00694 const AttServerMessage& server_message 00695 ) { 00696 if (_server_message_cb) { 00697 _server_message_cb(connection_handle, server_message); 00698 } 00699 } 00700 00701 /** 00702 * Upon transaction timeout an implementation shall call this function. 00703 * 00704 * @param connection_handle The handle of the connection of the transaction 00705 * which has times out. 00706 * 00707 * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.3.3 00708 */ 00709 void on_transaction_timeout( 00710 connection_handle_t connection_handle 00711 ) { 00712 if (_transaction_timeout_cb) { 00713 _transaction_timeout_cb(connection_handle); 00714 } 00715 } 00716 00717 private: 00718 /** 00719 * Callback called when the client receive a message from the server. 00720 */ 00721 mbed::Callback<void(connection_handle_t, const AttServerMessage&)> _server_message_cb; 00722 00723 /** 00724 * Callback called when a transaction times out. 00725 */ 00726 mbed::Callback<void(connection_handle_t)> _transaction_timeout_cb; 00727 00728 // Disallow copy construction and copy assignment. 00729 AttClient(const AttClient&); 00730 AttClient& operator=(const AttClient&); 00731 }; 00732 00733 00734 } // namespace pal 00735 } // namespace ble 00736 00737 #endif /* BLE_PAL_ATTCLIENT_H_ */
Generated on Tue Jul 12 2022 13:54:02 by
