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_ */