PalGattClient.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_GATT_CLIENT_H_
00018 #define BLE_PAL_GATT_CLIENT_H_
00019 
00020 #include "ble/common/StaticInterface.h"
00021 #include "ble/UUID.h "
00022 #include "ble/BLETypes.h"
00023 #include "ble/blecommon.h"
00024 
00025 #include "platform/Callback.h"
00026 
00027 #include "AttServerMessage.h"
00028 
00029 namespace ble {
00030 namespace pal {
00031 
00032 /**
00033  * Definition of the general handler of GattClient related events.
00034  */
00035 template<class Impl>
00036 struct GattClientEventHandler : StaticInterface<Impl, GattClientEventHandler> {
00037 
00038     using StaticInterface<Impl, ble::pal::GattClientEventHandler>::impl;
00039 
00040     /**
00041      * Function invoked when the connections changes the ATT_MTU which controls
00042      * the maximum size of an attribute that can be read in a single L2CAP packet
00043      * which might be fragmented across multiple packets.
00044      *
00045      * @param connectionHandle The handle of the connection that changed the size.
00046      * @param attMtuSize
00047      */
00048     void on_att_mtu_change(
00049         ble::connection_handle_t connection_handle,
00050         uint16_t att_mtu_size
00051     ) { 
00052         impl ()->on_att_mtu_change_(connection_handle, att_mtu_size);
00053     }
00054 
00055     /**
00056      * Function invoked when a write command has been sent out of the stack
00057      * (either to the controller or over the air).
00058      *
00059      * @param connection_handle Connection targeted by the write command
00060      * @param attribute_handle Attribute written
00061      * @param status HCI status of the operation.
00062      */
00063     void on_write_command_sent(
00064         ble::connection_handle_t connection_handle,
00065         ble::attribute_handle_t attribute_handle,
00066         uint8_t status
00067     ) {
00068         impl ()->on_write_command_sent_(
00069             connection_handle,
00070             attribute_handle,
00071             status
00072         );
00073     }
00074 };
00075 
00076 
00077 /**
00078  * Adaptation layer for a GATT client.
00079  *
00080  * Define the primitive necessary to implement a proper GATT client. These
00081  * primitives are sometime GATT procedure, ATT procedure or a bit of both.
00082  *
00083  * In general, discovery procedures follow strictly GATT formulation while
00084  * attribute manipulation procedures (read/write) follow the ATT formulation
00085  * to avoid multiple identical implementation for characteristic values and
00086  * characteristic descriptors value, it also fill a hole leave by the
00087  * specification which doesn't define any GATT procedure to get the UUID of an
00088  * included service with a 128 bit UUID.
00089  *
00090  * Complementary informations around ATT procedures can be found in the Section
00091  * 3.4 of the Vol3, Part F of the Bluetooth specification while more informations
00092  * around the GATT procedures can be found in the  Section 4 of the Vol 3, Part
00093  * G of the Bluetooth specification.
00094  *
00095  * Complete and compliant Gatt Client used by developer is realized at an higher
00096  * level using the primitives defined in this adaptation layer.
00097  *
00098  * If a stack expose the complete ATT layer then it is possible to provide an
00099  * implementation for GattClient by subclassing the AttClient class and use
00100  * the class AttClientToGattClientAdapter
00101  */
00102 template<class Impl, class EventHandler>
00103 class GattClient {
00104 
00105     Impl* self() {
00106         return static_cast<Impl*>(this);
00107     }
00108 
00109 public:
00110 
00111     /**
00112      * Initialisation of the instance. An implementation can use this function
00113      * to initialise the subsystems needed to realize the operations of this
00114      * interface.
00115      *
00116      * This function has to be called before any other operations.
00117      *
00118      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00119      * appropriate error otherwise.
00120      */
00121     ble_error_t initialize() {
00122         return self()->initialize_();
00123     }
00124 
00125     /**
00126      * Termination of the instance. An implementation can use this function
00127      * to release the subsystems initialised to realise the operations of
00128      * this interface.
00129      *
00130      * After a call to this function, initialise should be called again to
00131      * allow usage of the interface.
00132      *
00133      * @return BLE_ERROR_NONE if the request has been successfully sent or the
00134      * appropriate error otherwise.
00135      */
00136     ble_error_t terminate() {
00137         return self()->terminate_();
00138     }
00139 
00140     /**
00141      * Negotiate the mtu to use by this connection.
00142      * First the client send to the server the maximum rx mtu that it can receive
00143      * then the client reply with the maximum rx mtu it can receive.
00144      * The mtu chosen for the connection is the minimum of the client Rx mtu
00145      * and server Rx mtu values.
00146      *
00147      * If an error occurred then the mtu used remains the default value.
00148      *
00149      * The server will reply to this request with an AttExchangeMTUResponse in
00150      * case of success or AttErrorResponse in case of failure.
00151      *
00152      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.3.1
00153      *
00154      * @param connection The handle of the connection to send this request to.
00155      * @return BLE_ERROR_NONE or an appropriate error.
00156      */
00157     ble_error_t exchange_mtu(connection_handle_t connection) {
00158         return self()->exchange_mtu_(connection);
00159     }
00160 
00161     /**
00162      * Acquire the size of the mtu for a given connection.
00163      *
00164      * @param connection The handle of the connection for which the the MTU size
00165      * should be acquired.
00166      *
00167      * @param mtu_size Output parameter which will contain the MTU size.
00168      *
00169      * @return BLE_ERROR_NONE if the MTU size has been acquired or the
00170      * appropriate error otherwise.
00171      */
00172     ble_error_t get_mtu_size(
00173         connection_handle_t connection_handle,
00174         uint16_t& mtu_size
00175     ) {
00176         return self()->get_mtu_size_(connection_handle, mtu_size);
00177     }
00178 
00179     /**
00180      * Discover primary services in the range [begin - 0xFFFF].
00181      *
00182      * If services exists in the range provided, the server will reply with a
00183      * ReadByGoupType response where for each attribute_data exposed:
00184      *   - attribute_handle is the service attribute handle
00185      *   - end_group_handle is the last handle of the service
00186      *   - attribute_value is the UUID of the service.
00187      *
00188      * If the end of the range is not reached, this procedure can be relaunched
00189      * with the last handle of the last service discovered plus one as the
00190      * beginning of the discovery range.
00191      *
00192      * If there is not services left to discover in the range, the server can
00193      * either:
00194      *   * Reply with an ErrorResponse with the Error code set to ATTRIBUTE_NOT_FOUND
00195      *   * Set the end handle of the last service to 0xFFFF.
00196      *
00197      * @note This function realize a partial implementation of the Discover All
00198      * Primary Services procedure. The complete implementation of the procedure
00199      * is realized at an higher level.
00200      * @note This function issue a  Read By Group Type ATT request where the
00201      * type parameter is equal to Primary Service and the Ending Handle parameter
00202      * is equal to 0xFFFF.
00203      * @note BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.4.1
00204      *
00205      * @param connection The handle of the connection to send this request to.
00206      * @param begin The beginning of the discovery range.
00207      *
00208      * @return BLE_ERROR_NONE or an appropriate error.
00209      */
00210     ble_error_t discover_primary_service(
00211         connection_handle_t connection,
00212         attribute_handle_t discovery_range_begining
00213     ) {
00214         return self()->discover_primary_service_(
00215             connection,
00216             discovery_range_begining
00217         );
00218     }
00219 
00220     /**
00221      * Discover primary services by UUID in the range [discovery_range_begining - 0xFFFF].
00222      *
00223      * If services exists in the range provided, the server will reply with a
00224      * FindByTypeValueResponse containing the attribute range of each service
00225      * discovered.
00226      *
00227      * If the end of the range is not reached, this procedure can be relaunched
00228      * with the last handle of the last service  discovered plus one as the
00229      * beginning of the discovery range.
00230      *
00231      * If there is not services left to discover in the range, the server can
00232      * either:
00233      *   * Reply with an ErrorResponse with the Error code set to ATTRIBUTE_NOT_FOUND
00234      *   * Set the end handle of the last service to 0xFFFF.
00235      *
00236      * @note This function realize a partial implementation of the Discover
00237      * Primary Service by Service UUID procedure. The complete implementation of
00238      * the procedure is realized at an higher level.
00239      * @note This function issue a  Find By Type Value ATT request where the
00240      * type parameter is equal to Primary Service and the Ending Handle
00241      * parameter is equal to 0xFFFF.
00242      * @note BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.4.2
00243      *
00244      * @param connection The handle of the connection to send this request to.
00245      * @param begin The beginning of the discovery range.
00246      * @param uuid The UUID of the service to discover.
00247      *
00248      * @return BLE_ERROR_NONE or an appropriate error.
00249      */
00250     ble_error_t discover_primary_service_by_service_uuid(
00251         connection_handle_t connection_handle,
00252         attribute_handle_t discovery_range_beginning,
00253         const UUID& uuid
00254     ) {
00255         return self()->discover_primary_service_by_service_uuid_(
00256             connection_handle,
00257             discovery_range_beginning,
00258             uuid
00259         );
00260     }
00261 
00262     /**
00263      * Find included services within a service.
00264      *
00265      * If services are included in the service range then the server will reply
00266      * with a ReadByTypeResponse where for each attribute record:
00267      *   - attribute_handle The handle where the service is included within the
00268      *     service definition.
00269      *   - attribute_data Contains two handles defining the range of the included.
00270      *     If the service found have a 16 bit uuid then its UUID is also included
00271      *     in the attribute data.
00272      *
00273      * If the end of the service range is not reached, this procedure can be
00274      * relaunched with the handle of the last included service discovered plus
00275      * one as the beginning of the new discovery range.
00276      *
00277      * The procedure is complete when either:
00278      *   - The server reply with an ErrorResponse with the Error code set to
00279      *     ATTRIBUTE_NOT_FOUND
00280      *   - An included service handle returned is equal to the end of the range.
00281      *
00282      * If the service UUID is a 128 bits one then it is necessary to issue a read
00283      * attribute request on the first handle of the service discovered to get it.
00284      *
00285      * @note This function realize a partial implementation of the Find Included
00286      * Services procedure. The complete implementation of the procedure is
00287      * realized at an higher level.
00288      * @note This function issue a  Read By Type ATT request where the
00289      * type parameter is equal to Include.
00290      * @note BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.5.1
00291      *
00292      * @param connection The handle of the connection to send this request to.
00293      * @param service_range The range of the service where service inclusion has
00294      * to be discovered.
00295      *
00296      * @return BLE_ERROR_NONE or an appropriate error.
00297      */
00298     ble_error_t find_included_service(
00299         connection_handle_t connection_handle,
00300         attribute_handle_range_t service_range
00301     ) {
00302         return self()->find_included_service_(
00303             connection_handle,
00304             service_range
00305         );
00306     }
00307 
00308     /**
00309      * Find characteristic declarations within a service definition.
00310      *
00311      * If characteristic declarations are found within the range then the server
00312      * should reply with a ReadByTypeResponse where for each attribute record:
00313      *   - attribute_handle is the handle of the characteristic definition
00314      *   - attribute_data contains the the following values attached to the
00315      *     characteristic :
00316      *      + properties: the properties of the characteristic.
00317      *      + value handle: the handle of the value of the characteristic.
00318      *      + uuid: the UUID of the characteristic.
00319      *
00320      * The procedure is considered complete when the server send an ErrorResponse
00321      * with the ErrorCode set to ATTRIBUTE_NOT_FOUND or a ReadByType response
00322      * has an attribute_handle set to the end of the discovery range.
00323      *
00324      * If the procedure is not complete after a server response, it should be
00325      * relaunched with an updated range starting at the last attribute_handle
00326      * discovered plus one.
00327      *
00328      * @note This function realize a partial implementation of the Discover All
00329      * Characteristics of a Service procedure. The complete implementation of
00330      * the procedure is realized at an higher level.
00331      * @note This function issue a  Read By Type ATT request where the type
00332      * parameter is equal to Characteristic.
00333      * @note BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.6.1
00334      *
00335      * @note The GATT procedure Discover Characteristics by UUID is implemented
00336      * at a higher level using this function as a base.
00337      *
00338      * @param connection The handle of the connection to send this request to.
00339      * @param discovery_range The range of attributes where the characteristics
00340      * are discovered. It should be contained within a service.
00341      *
00342      * @return BLE_ERROR_NONE or an appropriate error.
00343      */
00344     ble_error_t discover_characteristics_of_a_service(
00345         connection_handle_t connection_handle,
00346         attribute_handle_range_t discovery_range
00347     ) {
00348         return self()->discover_characteristics_of_a_service_(
00349             connection_handle,
00350             discovery_range
00351         );
00352     }
00353 
00354     /**
00355      * Discover characteristic descriptors of a characteristic.
00356      *
00357      * If descriptors are found within the range provided then the server should
00358      * reply with a FindInformationResponse containing a list of
00359      * attribute_handle_t, UUID pairs where the attribute handle is the
00360      * descriptor handle and UUID is the UUID of the descriptor.
00361      *
00362      * The procedure is complete when the server send an ErrorResponse with the
00363      * error code ATTRIBUTE_NOT_FOUND or the FindInformationResponse has an
00364      * attribute handle that is equal to the end handle of the discovery range.
00365      *
00366      * @note This function realize a partial implementation of the Discover All
00367      * Characteristics Descriptors procedure. The complete implementation of
00368      * the procedure is realized at an higher level.
00369      * @note This function issue a Find Information ATT request..
00370      * @note BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.7.1
00371      *
00372      * @note It should be possible to use this function to issue a regular
00373      * ATT Find Information Request.
00374      *
00375      * @param connection The handle of the connection to send this request to.
00376      * @param descriptors_discovery_range The range of attributes where the
00377      * descriptors are discovered. The first handle shall be no less than the
00378      * characteristic value handle plus one and the last handle shall be no more
00379      * than the last handle of the characteristic.
00380      *
00381      * @return BLE_ERROR_NONE or an appropriate error.
00382      */
00383     ble_error_t discover_characteristics_descriptors(
00384         connection_handle_t connection_handle,
00385         attribute_handle_range_t descriptors_discovery_range
00386     ) {
00387         return self()->discover_characteristics_descriptors_(
00388             connection_handle,
00389             descriptors_discovery_range
00390         );
00391     }
00392 
00393     /**
00394      * Read the value of an attribute.
00395      *
00396      * The server will reply with an AttReadResponse. In case of error, the
00397      * server will reply with an AttErrorResponse.
00398      *
00399      * @note This function issue an ATT Read Request.
00400      *
00401      * @note: This function is the base function for the read Characteristic
00402      * Value and Read Characteristic Descriptor GATT procedures. It can also
00403      * be used to read the 128 bit UUID of a service discovered with
00404      * find_included_service.
00405      *
00406      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.8.1
00407      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.12.1
00408      *
00409      * @param connection The handle of the connection to send this request to.
00410      * @param attribute_handle Handle of the attribute to read.
00411      *
00412      * @return BLE_ERROR_NONE or an appropriate error.
00413      */
00414     ble_error_t read_attribute_value(
00415         connection_handle_t connection_handle,
00416         attribute_handle_t attribute_handle
00417     ) {
00418         return self()->read_attribute_value_(connection_handle, attribute_handle);
00419     }
00420 
00421     /**
00422      * Read a characteristic value using its UUID (type).
00423      *
00424      * The server will respond a ReadByTypeResponse containing a sequence of
00425      * attribute handle and attribute value pairs.
00426      * To read remaining attributes, the client should launch a new request
00427      * with an updated range.
00428      *
00429      * The procedure is considered complete when the server respond with an
00430      * ErrorResponse containing the ErrorCode ATTRIBUTE_NOT_FOUND or when an
00431      * handle in the ReadByTypeResponse is equal to the end of the discovered
00432      * range.
00433      *
00434      * @note This function realize a partial implementation of the Read Using
00435      * Characteristics Characteristic procedure. The complete implementation of
00436      * the procedure is realized at an higher level.
00437      * @note This function issue a Read By Type ATT request.
00438      * @note BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.8.2
00439      *
00440      * @note It should be possible to use this function to issue a regular
00441      * ATT Read By Type Request.
00442      *
00443      * @param connection The handle of the connection to send this request to.
00444      * @param attribute_range Range of the handle where an attribute with
00445      * uuid as type is present.
00446      * @param uuid UUID of the characteristic(s) to read.
00447      *
00448      * @return BLE_ERROR_NONE or an appropriate error.
00449      */
00450     ble_error_t read_using_characteristic_uuid(
00451         connection_handle_t connection_handle,
00452         attribute_handle_range_t read_range,
00453         const UUID& uuid
00454     ) {
00455         return self()->read_using_characteristic_uuid_(
00456             connection_handle,
00457             read_range,
00458             uuid
00459         );
00460     }
00461 
00462     /**
00463      * Read a partial value of an attribute.
00464      *
00465      * The server will respond with a ReadBlobResponse containing the data read
00466      * or an ErrorResponse in case of error.
00467      *
00468      * The procedure is not complete as long as the value in response have the
00469      * same size as the mtu minus one. If the procedure is not complete, it can
00470      * be launch again with an updated offset to read the remaining part of the
00471      * attribute value.
00472      *
00473      * @note This function issue an ATT Read Blob Request.
00474      *
00475      * @note: This function is the base function for the Read Long
00476      * Characteristic Value and Read Long Characteristic Descriptor GATT
00477      * procedures.
00478      *
00479      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.8.3
00480      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.12.2
00481      *
00482      * @param connection_handle The handle of the connection to send this request to.
00483      * @param attribute_handle Handle of the attribute to read.
00484      * @param offset Beginning offset for the read operation.
00485      *
00486      * @return BLE_ERROR_NONE or an appropriate error.
00487      */
00488     ble_error_t read_attribute_blob(
00489         connection_handle_t connection_handle,
00490         attribute_handle_t attribute_handle,
00491         uint16_t offset
00492     ) {
00493         return self()->read_attribute_blob_(connection_handle, attribute_handle, offset);
00494     }
00495 
00496     /**
00497      * Read atomically multiple characteristics values.
00498      *
00499      * The server will respond with a ReadMultiple response containing the
00500      * concatenation of the values of the characteristics.
00501      *
00502      * @note values might be truncated
00503      *
00504      * In case of error, the server should respond a with an ErrorResponse.
00505      *
00506      * @note This function issue an ATT Read Multiple Request.
00507      *
00508      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.8.4
00509      *
00510      * @param connection_handle The handle of the connection to send this request to.
00511      * @param characteristic_value_handles Handle of the characteristic values
00512      * to read.
00513      *
00514      * @return BLE_ERROR_NONE or an appropriate error.
00515      */
00516     ble_error_t read_multiple_characteristic_values(
00517         connection_handle_t connection_handle,
00518         const Span<const attribute_handle_t>& characteristic_value_handles
00519     ) {
00520         return self()->read_multiple_characteristic_values_(
00521             connection_handle,
00522             characteristic_value_handles
00523         );
00524     }
00525 
00526     /**
00527      * Send a write command to the server.
00528      *
00529      * @note This function issue an ATT Write Command.
00530      *
00531      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.1
00532      *
00533      * @param connection_handle The handle of the connection to send this request to.
00534      * @param attribute_handle Handle of the attribute to write.
00535      * @param value The value to write.
00536      *
00537      * @return BLE_ERROR_NONE or an appropriate error.
00538      */
00539     ble_error_t write_without_response(
00540         connection_handle_t connection_handle,
00541         attribute_handle_t characteristic_value_handle,
00542         const Span<const uint8_t>& value
00543     ) {
00544         return self()->write_without_response_(
00545             connection_handle,
00546             characteristic_value_handle,
00547             value
00548         );
00549     }
00550 
00551     /**
00552      * Send a Signed Write without Response command to the server.
00553      *
00554      * @note This function issue an ATT Write Command with the signed flag and
00555      * the signature.
00556      *
00557      * @note signature is calculated by the stack.
00558      *
00559      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.2
00560      *
00561      * @param connection_handle The handle of the connection to send this request to.
00562      * @param attribute_handle Handle of the attribute to write.
00563      * @param value The value to write.
00564      *
00565      * @return BLE_ERROR_NONE or an appropriate error.
00566      */
00567     ble_error_t signed_write_without_response(
00568         connection_handle_t connection_handle,
00569         attribute_handle_t characteristic_value_handle,
00570         const Span<const uint8_t>& value
00571     ) {
00572         return self()->signed_write_without_response_(
00573             connection_handle,
00574             characteristic_value_handle,
00575             value
00576         );
00577     }
00578 
00579     /**
00580      * Send a write request to the server.
00581      *
00582      * The server should respond with a WriteResponse in case of success or an
00583      * ErrorResponse in case of error.
00584      *
00585      * @note This function issue an ATT Write Request.
00586      *
00587      * @note: This function is the base function for the Write Characteristic
00588      * Value and Write Characteristic Descriptors GATT procedures.
00589      *
00590      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.3
00591      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.12.3
00592      *
00593      * @param connection_handle The handle of the connection to send this request to.
00594      * @param attribute_handle Handle of the attribute to write.
00595      * @param value The value to write.
00596      *
00597      * @return BLE_ERROR_NONE or an appropriate error.
00598      */
00599     ble_error_t write_attribute(
00600         connection_handle_t connection_handle,
00601         attribute_handle_t attribute_handle,
00602         const Span<const uint8_t>& value
00603     ) {
00604         return self()->write_attribute_(connection_handle, attribute_handle, value);
00605     }
00606 
00607     /**
00608      * Send a prepare write request to the server.
00609      *
00610      * The write request will go into a queue until the client execute or cancel
00611      * the request with an execute write request which will write all the values
00612      * in the queue atomically.
00613      *
00614      * The server should respond with a PrepareWriteResponse containing the
00615      * content of the request in case of success and an ErrorResponse in case of
00616      * error.
00617      *
00618      * If an ErrorResponse is received it doesn't invalidate what is already in
00619      * the queue.
00620      *
00621      * @note This function issue an ATT Prepare Write Request.
00622      *
00623      * @note: This function is one of the base function for the Write Long
00624      * Characteristic Value and Reliable Writes GATT procedures.
00625      *
00626      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.4
00627      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.5
00628      *
00629      * @param connection_handle The handle of the connection to send this request to.
00630      * @param attribute_handle Handle of the attribute to write.
00631      * @param value The value to write.
00632      * @param offset offset where the value should be written.
00633      *
00634      * @return BLE_ERROR_NONE or an appropriate error.
00635      */
00636     ble_error_t queue_prepare_write(
00637         connection_handle_t connection_handle,
00638         attribute_handle_t characteristic_value_handle,
00639         const Span<const uint8_t>& value,
00640         uint16_t offset
00641     ) {
00642         return self()->queue_prepare_write_(
00643             connection_handle,
00644             characteristic_value_handle,
00645             value,
00646             offset
00647         );
00648     }
00649 
00650     /**
00651      * Send a request to the server to execute the queue of prepared write
00652      * requests.
00653      *
00654      * The server should respond with an ExecuteWriteResponse in case of success
00655      * and an Error response in case of failure.
00656      *
00657      * @note This function issue an ATT Execute Write Request.
00658      *
00659      * @note: This function is one of the base function for the Write Long
00660      * Characteristic Value and Reliable Writes GATT procedures.
00661      *
00662      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.4
00663      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.5
00664      *
00665      * @param connection_handle The handle of the connection to send this request to.
00666      * @param execute If true, execute the write request queue otherwise cancel it.
00667      *
00668      * @return BLE_ERROR_NONE or an appropriate error.
00669      */
00670     ble_error_t execute_write_queue(
00671         connection_handle_t connection_handle,
00672         bool execute
00673     ) {
00674         return self()->execute_write_queue_(connection_handle, execute);
00675     }
00676 
00677     /**
00678      * Register a callback which will handle messages from the server.
00679      *
00680      * @param cb The callback object which will handle messages from the server.
00681      * It accept two parameters in input: The handle of the connection where the
00682      * message was received and the message received. Real type of the message
00683      * can be obtained from its opcode.
00684      */
00685     void when_server_message_received(
00686         mbed::Callback<void(connection_handle_t, const AttServerMessage&)> cb
00687     ) {
00688         _server_message_cb = cb;
00689     }
00690 
00691     /**
00692      * Register a callback handling transaction timeout.
00693      *
00694      * @param cb The callback handling timeout of a transaction. It accepts as
00695      * a parameter the connection handle involved in the timeout.
00696      *
00697      * @note No more attribute protocol requests, commands, indication or
00698      * notification shall be sent over a connection implied in a transaction
00699      * timeout. To send a new ATT message, the conenction should be
00700      * reestablished.
00701      */
00702      void when_transaction_timeout(
00703          mbed::Callback<void(connection_handle_t)> cb
00704      ) {
00705          _transaction_timeout_cb = cb;
00706      }
00707 
00708      /**
00709       * Sets the event handler that us called by the PAL porters to notify the stack of events
00710       * which will in turn be passed onto the user application when appropriate.
00711       *
00712       * @param event_handler The new event handler interface implementation.
00713       */
00714      void set_event_handler(EventHandler* event_handler) {
00715          _event_handler = event_handler;
00716      }
00717 
00718      /**
00719       * Get the currently registered event handler.
00720       *
00721       * @return Currently registered event handler. NULL if no event handler is present.
00722       */
00723      EventHandler* get_event_handler() {
00724          return _event_handler;
00725      }
00726 
00727 protected:
00728     GattClient() : _event_handler(NULL) { }
00729 
00730     ~GattClient() { }
00731 
00732     /**
00733      * Upon server message reception an implementation shall call this function.
00734      *
00735      * @param connection_handle The handle of the connection which has received
00736      * the server message.
00737      * @param server_message The message received from the server.
00738      */
00739     void on_server_event(
00740         connection_handle_t connection_handle,
00741         const AttServerMessage& server_message
00742     ) {
00743         if (_server_message_cb) {
00744             _server_message_cb(connection_handle, server_message);
00745         }
00746     }
00747 
00748     /**
00749      * Upon transaction timeout an implementation shall call this function.
00750      *
00751      * @param connection_handle The handle of the connection of the transaction
00752      * which has times out.
00753      *
00754      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.3.3
00755      * @note see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.4.14
00756      */
00757     void on_transaction_timeout(
00758         connection_handle_t connection_handle
00759     ) {
00760         if (_transaction_timeout_cb) {
00761             _transaction_timeout_cb(connection_handle);
00762         }
00763     }
00764 
00765 private:
00766     EventHandler* _event_handler;
00767 
00768     /**
00769      * Callback called when the client receive a message from the server.
00770      */
00771     mbed::Callback<void(connection_handle_t, const AttServerMessage&)> _server_message_cb;
00772 
00773     /**
00774      * Callback called when a transaction times out.
00775      */
00776     mbed::Callback<void(connection_handle_t)> _transaction_timeout_cb;
00777 
00778     // Disallow copy construction and copy assignment.
00779     GattClient(const GattClient&);
00780     GattClient& operator=(const GattClient&);
00781 };
00782 
00783 } // namespace pal
00784 } // namespace ble
00785 
00786 #endif /* BLE_PAL_GATT_CLIENT_H_ */