bluenrg_gatt_aci.h

00001 /******************** (C) COPYRIGHT 2014 STMicroelectronics ********************
00002 * File Name          : bluenrg_gatt_aci.h
00003 * Author             : AMS - AAS
00004 * Version            : V1.0.0
00005 * Date               : 26-Jun-2014
00006 * Description        : Header file with GATT commands for BlueNRG FW6.3.
00007 ********************************************************************************
00008 * THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS
00009 * WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE TIME.
00010 * AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY DIRECT,
00011 * INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING FROM THE
00012 * CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE CODING
00013 * INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.
00014 *******************************************************************************/
00015 
00016 #ifndef __BLUENRG_GATT_ACI_H__
00017 #define __BLUENRG_GATT_ACI_H__
00018 
00019 #include "gatt_server.h"
00020 
00021 /**
00022  *@defgroup GATT_Functions GATT functions
00023  *@brief API for GATT layer.
00024  *@{
00025  */
00026 
00027 /**
00028   * @brief  Initialize the GATT layer for server and client roles.
00029   * @note   It adds also the GATT service with Service Changed Characteristic.
00030  *           Until this command is issued the GATT channel will not process any commands
00031   *          even if the connection is opened. This command has to be given
00032   *          before using any of the GAP features.
00033   * @return Value indicating success or error code.
00034   */
00035 tBleStatus aci_gatt_init(void);
00036 
00037 /**
00038  * @brief Add a service to the GATT Server. When a service is created in the server, the Host needs
00039  *        to reserve the handle ranges for this service using max_attr_records parameter. This
00040  *        parameter specifies the maximum number of attribute records that can be added to this
00041  *        service (including the service attribute, include attribute, characteristic attribute,
00042  *        characteristic value attribute and characteristic descriptor attribute). Handle of the
00043  *        created service is returned.
00044  * @param service_uuid_type Type of service UUID (16-bit or 128-bit). See @ref UUID_Types.
00045  * @param[in] service_uuid 16-bit or 128-bit UUID based on the UUID Type field
00046  * @param service_type Primary or secondary service. See @ref Service_type.
00047  * @param max_attr_records Maximum number of attribute records that can be added to this service
00048  * @param[out] serviceHandle Handle of the Service. When this service is added to the service,
00049  *                           a handle is allocated by the server to this service. Server also
00050  *                           allocates a range of handles for this service from serviceHandle to
00051  *                           <serviceHandle + max_attr_records>.
00052  * @return Value indicating success or error code.
00053  */
00054 tBleStatus aci_gatt_add_serv(uint8_t service_uuid_type,
00055                  const uint8_t* service_uuid,
00056                  uint8_t service_type,
00057                  uint8_t max_attr_records,
00058                  uint16_t *serviceHandle);
00059 
00060 /**
00061  * @brief Include a service given by included_start_handle and included_end_handle to another service
00062  *        given by service_handle. Attribute server creates an INCLUDE definition attribute and return
00063  *        the handle of this attribute in included_handle.
00064  * @param service_handle Handle of the service to which another service has to be included
00065  * @param included_start_handle Start Handle of the service which has to be included in service
00066  * @param included_end_handle End Handle of the service which has to be included in service
00067  * @param included_uuid_type Type of UUID for included service (16-bit or 128-bit). See @ref UUID_Types.
00068  * @param[in] included_uuid 16-bit or 128-bit UUID.
00069  * @param[out] included_handle Handle of the include declaration.
00070  * @return Value indicating success or error code.
00071  */
00072 tBleStatus aci_gatt_include_service(uint16_t service_handle, uint16_t included_start_handle,
00073                     uint16_t included_end_handle, uint8_t included_uuid_type,
00074                     const uint8_t* included_uuid, uint16_t *included_handle);
00075 
00076 /**
00077  * @brief Add a characteristic to a service.
00078  * @param serviceHandle Handle of the service to which the characteristic has to be added.
00079  * @param charUuidType Type of characteristic UUID (16-bit or 128-bit). See @ref UUID_Types.
00080  *         @arg @ref UUID_TYPE_16
00081  *         @arg @ref UUID_TYPE_128
00082  * @param charUuid 16-bit or 128-bit UUID.
00083  * @param charValueLen Maximum length of the characteristic value.
00084  * @param charProperties Bitwise OR values of Characteristic Properties (defined in Volume 3,
00085  *        Section 3.3.3.1 of Bluetooth Specification 4.0). See @ref Char_properties.
00086  * @param secPermissions Security permissions for the added characteristic. See @ref Security_permissions.
00087  *          @arg ATTR_PERMISSION_NONE
00088  *          @arg ATTR_PERMISSION_AUTHEN_READ
00089  *          @arg ATTR_PERMISSION_AUTHOR_READ
00090  *          @arg ATTR_PERMISSION_ENCRY_READ
00091  *          @arg ATTR_PERMISSION_AUTHEN_WRITE
00092  *          @arg ATTR_PERMISSION_AUTHOR_WRITE
00093  *          @arg ATTR_PERMISSION_ENCRY_WRITE
00094  * @param gattEvtMask Bit mask that enables events that will be sent to the application by the GATT server
00095  *                    on certain ATT requests. See @ref Gatt_Event_Mask.
00096  *         @arg GATT_DONT_NOTIFY_EVENTS
00097  *         @arg GATT_NOTIFY_ATTRIBUTE_WRITE
00098  *         @arg GATT_NOTIFY_WRITE_REQ_AND_WAIT_FOR_APPL_RESP
00099  *         @arg GATT_NOTIFY_READ_REQ_AND_WAIT_FOR_APPL_RESP
00100  * @param encryKeySize The minimum encryption key size requirement for this attribute. Valid Range: 7 to 16.
00101  * @param isVariable If the attribute has a variable length value field (1) or not (0).
00102  * @param charHandle Handle of the Characteristic that has been added. It is the handle of the characteristic declaration.
00103  *        The attribute that holds the characteristic value is allocated at the next handle, followed by the Client
00104  *        Characteristic Configuration descriptor if the characteristic has @ref CHAR_PROP_NOTIFY or @ref CHAR_PROP_INDICATE
00105  *        properties.
00106  * @return Value indicating success or error code.
00107  */
00108 tBleStatus aci_gatt_add_char(uint16_t serviceHandle,
00109                  uint8_t charUuidType,
00110                  const uint8_t* charUuid, 
00111                  uint8_t charValueLen, 
00112                  uint8_t charProperties,
00113                  uint8_t secPermissions,
00114                  uint8_t gattEvtMask,
00115                  uint8_t encryKeySize,
00116                  uint8_t isVariable,
00117                  uint16_t* charHandle);
00118 
00119 /**
00120  * Add a characteristic descriptor to a service.
00121  * @param serviceHandle Handle of the service to which the characteristic belongs
00122  * @param charHandle Handle of the characteristic to which description has to be added.
00123  * @param descUuidType 16-bit or 128-bit UUID. See @ref UUID_Types.
00124  *         @arg @ref UUID_TYPE_16
00125  *         @arg @ref UUID_TYPE_128
00126  * @param[in] uuid UUID of the Characteristic descriptor. It can be one of the UUID assigned by Bluetooth SIG
00127  *      (Well_known_UUIDs) or a user-defined one.
00128  * @param descValueMaxLen The maximum length of the descriptor value
00129  * @param descValueLen Current Length of the characteristic descriptor value
00130  * @param[in] descValue Value of the characteristic description
00131  * @param secPermissions Security permissions for the added descriptor. See @ref Security_permissions.
00132  *          @arg ATTR_PERMISSION_NONE
00133  *          @arg ATTR_PERMISSION_AUTHEN_READ
00134  *          @arg ATTR_PERMISSION_AUTHOR_READ
00135  *          @arg ATTR_PERMISSION_ENCRY_READ
00136  *          @arg ATTR_PERMISSION_AUTHEN_WRITE
00137  *          @arg ATTR_PERMISSION_AUTHOR_WRITE
00138  *          @arg ATTR_PERMISSION_ENCRY_WRITE
00139  * @param accPermissions Access permissions for the added descriptor. See @ref Access_permissions.
00140  *          @arg ATTR_NO_ACCESS
00141  *          @arg ATTR_ACCESS_READ_ONLY
00142  *          @arg ATTR_ACCESS_WRITE_REQ_ONLY
00143  *          @arg ATTR_ACCESS_READ_WRITE
00144  *          @arg ATTR_ACCESS_WRITE_WITHOUT_RESPONSE
00145  *          @arg ATTR_ACCESS_SIGNED_WRITE_ALLOWED
00146  * @param gattEvtMask Bit mask that enables events that will be sent to the application by the GATT server
00147  *                    on certain ATT requests. See @ref Gatt_Event_Mask.
00148  * @param encryKeySize The minimum encryption key size requirement for this attribute. Valid Range: 7 to 16.
00149  * @param isVariable If the attribute has a variable length value field (1) or not (0).
00150  * @param[out] descHandle Handle of the Characteristic Descriptor.
00151  * @return Value indicating success or error code.
00152  */
00153 tBleStatus aci_gatt_add_char_desc(uint16_t serviceHandle,
00154                                   uint16_t charHandle,
00155                                   uint8_t descUuidType,
00156                                   const uint8_t* uuid, 
00157                                   uint8_t descValueMaxLen,
00158                                   uint8_t descValueLen,
00159                                   const void* descValue, 
00160                                   uint8_t secPermissions,
00161                                   uint8_t accPermissions,
00162                                   uint8_t gattEvtMask,
00163                                   uint8_t encryKeySize,
00164                                   uint8_t isVariable,
00165                                   uint16_t* descHandle);
00166 
00167 /**
00168  * @brief Update a characteristic value in a service.
00169  * @note If notifications (or indications) are enabled on that characteristic, a notification (or indication)
00170  *       will be sent to the client after sending this command to the BlueNRG. The command is queued into the
00171  *       BlueNRG command queue. If the buffer is full, because previous commands could not be still processed,
00172  *       the function will return @ref BLE_STATUS_INSUFFICIENT_RESOURCES. This will happen if notifications (or
00173  *       indications) are enabled and the application calls aci_gatt_update_char_value() at an higher rate
00174  *       than what is allowed by the link. Throughput on BLE link depends on connection interval and
00175  *       connection length parameters (decided by the master, see aci_l2cap_connection_parameter_update_request()
00176  *       for more info on how to suggest new connection parameters from a slave). If the application does not
00177  *       want to lose notifications because BlueNRG buffer becomes full, it has to retry again till the function
00178  *       returns @ref BLE_STATUS_SUCCESS or any other error code.\n
00179  *       Example:\n
00180  *       Here if BlueNRG buffer become full because BlueNRG was not able to send packets for a while, some
00181  *       notifications will be lost.
00182  *       @code
00183  *       tBleStatus Free_Fall_Notify(void)
00184  *       {
00185  *          uint8_t val;
00186  *          tBleStatus ret;
00187  *
00188  *          val = 0x01;
00189  *          ret = aci_gatt_update_char_value(accServHandle, freeFallCharHandle, 0, 1, &val);
00190  *
00191  *          if (ret != BLE_STATUS_SUCCESS){
00192  *            PRINTF("Error while updating ACC characteristic.\n") ;
00193  *            return BLE_STATUS_ERROR ;
00194  *          }
00195  *          return BLE_STATUS_SUCCESS;
00196  *       }
00197  *       @endcode
00198  *       Here if BlueNRG buffer become full, the application try again to send the notification.
00199  *       @code
00200  *       struct timer t;
00201  *       Timer_Set(&t, CLOCK_SECOND*10);
00202  *       while(aci_gatt_update_char_value(chatServHandle,TXCharHandle,0,len,array_val)==BLE_STATUS_INSUFFICIENT_RESOURCES){
00203  *         // Radio is busy (buffer full).
00204  *         if(Timer_Expired(&t))
00205  *           break;
00206  *       }
00207  *       @endcode
00208  *
00209  * @param servHandle Handle of the service to which characteristic belongs
00210  * @param charHandle Handle of the characteristic
00211  * @param charValOffset The offset from which the attribute value has to be updated. If this is set to 0,
00212  *                      and the attribute value is of variable length, then the length of the attribute will
00213  *                      be set to the charValueLen. If the charValOffset is set to a value greater than 0,
00214  *                      then the length of the attribute will be set to the maximum length as specified for
00215  *                      the attribute while adding the characteristic.
00216  * @param charValueLen Length of the characteristic value in octets
00217  * @param[in] charValue Characteristic value
00218  * @return Value indicating success or error code.
00219  */
00220 tBleStatus aci_gatt_update_char_value(uint16_t servHandle, 
00221                       uint16_t charHandle,
00222                       uint8_t charValOffset,
00223                       uint8_t charValueLen,   
00224                       const uint8_t *charValue);
00225 /**
00226  * @brief Delete the specified characteristic from the service.
00227  * @param servHandle Handle of the service to which characteristic belongs
00228  * @param charHandle Handle of the characteristic to be deleted
00229  * @return Value indicating success or error code.
00230  */
00231 tBleStatus aci_gatt_del_char(uint16_t servHandle, uint16_t charHandle);
00232 
00233 /**
00234  * @brief Delete the specified service from the GATT server database.
00235  * @param servHandle Handle of the service to be deleted
00236  * @return Value indicating success or error code.
00237  */
00238 tBleStatus aci_gatt_del_service(uint16_t servHandle);
00239 
00240 /**
00241  * @brief Delete the Include definition from the service.
00242  * @param servHandle Handle of the service to which Include definition belongs
00243  * @param includeServHandle Handle of the Included definition to be deleted
00244  * @return Value indicating success or error code.
00245  */
00246 tBleStatus aci_gatt_del_include_service(uint16_t servHandle, uint16_t includeServHandle);
00247 
00248 /**
00249  * @brief Perform an ATT MTU exchange procedure.
00250  * @note  When the ATT MTU exchange procedure is completed, a @ref EVT_BLUE_ATT_EXCHANGE_MTU_RESP
00251  *        event is generated. A @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event is also generated
00252  *        to indicate the end of the procedure.
00253  * @param conn_handle Connection handle for which the command is given.
00254  * @return Value indicating success or error code.
00255  */
00256 tBleStatus aci_gatt_exchange_configuration(uint16_t conn_handle);
00257 
00258 /**
00259  * @brief Send a @a Find @a Information @a Request.
00260  * @note This command is used to obtain the mapping of attribute handles with their associated
00261  *       types. The responses of the procedure are given through the
00262  *       @ref EVT_BLUE_ATT_FIND_INFORMATION_RESP event. The end of the procedure is indicated by
00263  *       a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event.
00264  * @param conn_handle Connection handle for which the command is given
00265  * @param start_handle Starting handle of the range of attributes to be discovered on the server
00266  * @param end_handle Ending handle of the range of attributes to be discovered on the server
00267  * @return Value indicating success or error code.
00268  */
00269 tBleStatus aci_gatt_find_information_req(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle);
00270 
00271 /**
00272  * @brief This command will start the GATT client procedure to discover all primary services on the server.
00273  * @note  The responses of the procedure are given through the @ref EVT_BLUE_ATT_READ_BY_GROUP_TYPE_RESP event.
00274  *        The end of the procedure is indicated by a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event.
00275  * @param conn_handle Connection handle for which the command is given.
00276  * @return Value indicating success or error code.
00277  */
00278 tBleStatus aci_gatt_disc_all_prim_services(uint16_t conn_handle);
00279 
00280 /**
00281  * @brief Start the procedure to find all included services.
00282  * @note The responses of the procedure are given through the @ref EVT_BLUE_ATT_READ_BY_TYPE_RESP event.
00283  *       The end of the procedure is indicated by a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event.
00284  * @param conn_handle Connection handle for which the command is given.
00285  * @param start_handle Start handle of the service
00286  * @param end_handle End handle of the service
00287  * @return Value indicating success or error code.
00288  */
00289 tBleStatus aci_gatt_find_included_services(uint16_t conn_handle, uint16_t start_handle,
00290                        uint16_t end_handle);
00291 
00292 /**
00293  * @brief Start the procedure to discover all the characteristics of a given service.
00294  * @note When the procedure is completed, a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event is generated.
00295  *       Before procedure completion the response packets are given through @ref EVT_BLUE_ATT_READ_BY_TYPE_RESP event.
00296  * @param conn_handle Connection handle for which the command is given
00297  * @param start_attr_handle Start attribute handle of the service
00298  * @param end_attr_handle End attribute handle of the service
00299  * @return Value indicating success or error code.
00300  */
00301 tBleStatus aci_gatt_disc_all_charac_of_serv(uint16_t conn_handle, uint16_t start_attr_handle,
00302                         uint16_t end_attr_handle);
00303 
00304 /**
00305  * @brief Start the procedure to discover all the characteristics specified by a UUID.
00306  * @note  When the procedure is completed, a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event is generated.
00307  *        Before procedure completion the response packets are given through @ref EVT_BLUE_ATT_READ_BY_TYPE_RESP event.
00308  * @param conn_handle
00309  * @param start_handle
00310  * @param end_handle
00311  * @param charUuidType
00312  * @param charUuid
00313  * @return
00314  */
00315 tBleStatus aci_gatt_discovery_characteristic_by_uuid(uint16_t conn_handle, uint16_t start_handle,
00316                                      uint16_t end_handle, uint8_t charUuidType,
00317                                                      const uint8_t* charUuid);
00318 
00319 /**
00320  * @brief Start the procedure to discover all characteristic descriptors on the server.
00321  * @note When the procedure is completed, a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event is generated.
00322  *       Before procedure completion the response packets are given through @ref EVT_BLUE_ATT_FIND_INFORMATION_RESP event.
00323  * @param conn_handle Connection handle for which the command is given.
00324  * @param char_val_handle Starting handle of the characteristic
00325  * @param char_end_handle End handle of the characteristic
00326  * @return Value indicating success or error code.
00327  */
00328 tBleStatus aci_gatt_disc_all_charac_descriptors(uint16_t conn_handle, uint16_t char_val_handle,
00329                         uint16_t char_end_handle);
00330 
00331 /**
00332  * @brief Start the procedure to read the attribute value.
00333  * @note  When the procedure is completed, a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event is generated.
00334  *        Before procedure completion the response packet is given through @ref EVT_BLUE_ATT_READ_RESP event.
00335  * @param conn_handle Connection handle for which the command is given
00336  * @param attr_handle Handle of the characteristic to be read
00337  * @return Value indicating success or error code.\n
00338  *       It can be @ref BLE_STATUS_NOT_ALLOWED in the following cases:\n
00339  *      - If the exchange has already taken place\n
00340  *      - If GATT is expecting response for previous request\n
00341  *      - Already a request is in the queue to be sent\n
00342  *      - Channel not open\n
00343  *      - Already one GATT procedure is started
00344  */
00345 tBleStatus aci_gatt_read_charac_val(uint16_t conn_handle, uint16_t attr_handle);
00346 
00347 /**
00348  * @brief Start the procedure to read a long characteristic value.
00349  * @note When the procedure is completed, a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event is generated.
00350  *       Before procedure completion the response packets are given through @ref EVT_BLUE_ATT_READ_BLOB_RESP event.
00351  * @param conn_handle Connection handle for which the command is given
00352  * @param attr_handle Handle of the characteristic to be read
00353  * @param val_offset Offset from which the value needs to be read
00354  * @return Value indicating success or error code.\n
00355  *       It can be @ref BLE_STATUS_NOT_ALLOWED in the following cases:\n
00356  *      - If the exchange has already taken place\n
00357  *      - If GATT is expecting response for previous request\n
00358  *      - Already a request is in the queue to be sent\n
00359  *      - Channel not open\n
00360  *      - Already one GATT procedure is started
00361  */
00362 tBleStatus aci_gatt_read_long_charac_val(uint16_t conn_handle, uint16_t attr_handle,
00363                      uint16_t val_offset);
00364 
00365 /**
00366  * @brief Start the procedure to write a characteristic value.
00367  * @note When the procedure is completed, a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event is generated.
00368  * @param conn_handle Connection handle for which the command is given
00369  * @param attr_handle Handle of the characteristic to be written
00370  * @param value_len Length of the value to be written
00371  * @param[in] attr_value Value to be written
00372  * @return Value indicating success or error code.\n
00373  *       It can be @ref BLE_STATUS_NOT_ALLOWED in the following cases:\n
00374  *      - If the exchange has already taken place\n
00375  *      - If GATT is expecting response for previous request\n
00376  *      - Already a request is in the queue to be sent\n
00377  *      - Channel not open\n
00378  *      - Already one GATT procedure is started
00379  */
00380 tBleStatus aci_gatt_write_charac_value(uint16_t conn_handle, uint16_t attr_handle,
00381                        uint8_t value_len, uint8_t *attr_value);
00382 
00383 /**
00384  * @brief Start the procedure to write a characteristic descriptor.
00385  * @note When the procedure is completed, a @ref EVT_BLUE_GATT_PROCEDURE_COMPLETE event is generated.
00386  * @param conn_handle Connection handle for which the command is given
00387  * @param attr_handle Handle of the attribute to be written
00388  * @param value_len Length of the value to be written
00389  * @param[in] attr_value Value to be written
00390  * @return Value indicating success or error code.\n
00391  *       It can be @ref BLE_STATUS_NOT_ALLOWED in the following cases:\n
00392  *      - If the exchange has already taken place\n
00393  *      - If GATT is expecting response for previous request\n
00394  *      - Already a request is in the queue to be sent\n
00395  *      - Channel not open\n
00396  *      - Already one GATT procedure is started
00397  */
00398 tBleStatus aci_gatt_write_charac_descriptor(uint16_t conn_handle, uint16_t attr_handle,
00399                        uint8_t value_len, uint8_t *attr_value);
00400 
00401 /**
00402  * @brief Start the procedure to write a characteristic value without waiting for any response from the server.
00403  * @note No events are generated after this command is executed.
00404  * @param conn_handle Connection handle for which the command is given
00405  * @param attr_handle Handle of the attribute to be written
00406  * @param value_len Length of the value to be written
00407  * @param[in] attr_value Value to be written
00408  * @return Value indicating success or error code.\n
00409  *       It can be @ref BLE_STATUS_NOT_ALLOWED in the following cases:\n
00410  *      - If the exchange has already taken place\n
00411  *      - If GATT is expecting response for previous request\n
00412  *      - Already a request is in the queue to be sent\n
00413  *      - Channel not open\n
00414  *      - Already one GATT procedure is started
00415  */
00416 tBleStatus aci_gatt_write_without_response(uint16_t conn_handle, uint16_t attr_handle,
00417                        uint8_t value_len, uint8_t *attr_value);
00418 
00419 /**
00420  * @brief Confirm an indication
00421  * @note  This command has to be sent when the application receives the event @ref EVT_BLUE_GATT_INDICATION.
00422  * @param conn_handle Connection handle for which the command is given.
00423  * @return Value indicating success or error code.
00424  */
00425 tBleStatus aci_gatt_confirm_indication(uint16_t conn_handle);
00426 
00427 /**
00428  * @brief Allow or reject a write request from a client.
00429  * @note This command has to be sent by the application when it receives the @ref EVT_BLUE_GATT_WRITE_PERMIT_REQ.
00430  *       If the write is allowed, then the status and error code has to be set to 0. If the write is not allowed,
00431  *       then the status has to be set to 1 and the error code has to be set to the error code that has to be
00432  *       passed to the client.
00433  * @param conn_handle Connection handle for which the command is given
00434  * @param attr_handle Handle of the attribute that was passed in the event @ref EVT_BLUE_GATT_WRITE_PERMIT_REQ.
00435  * @param write_status 0x00: The value can be written to the attribute specified by attr_handle\n
00436  *                     0x01: The value cannot be written to the attribute specified by the attr_handle.
00437  * @param err_code  The error code that has to be passed to the client in case the write has to be rejected.
00438  * @param att_val_len Length of the value to be written as passed in the event @ref EVT_BLUE_GATT_WRITE_PERMIT_REQ.
00439  * @param att_val Value as passed in the event @ref EVT_BLUE_GATT_WRITE_PERMIT_REQ.
00440  * @return Value indicating success or error code.
00441  */
00442 tBleStatus aci_gatt_write_response(uint16_t conn_handle,
00443                                    uint16_t attr_handle,
00444                                    uint8_t write_status,
00445                                    uint8_t err_code,
00446                                    uint8_t att_val_len,
00447                                    uint8_t *att_val);
00448 
00449 /**
00450  * @brief Allow the GATT server to send a response to a read request from a client.
00451  * @note The application has to send this command when it receives the @ref EVT_BLUE_GATT_READ_PERMIT_REQ
00452  *       or @ref EVT_BLUE_GATT_READ_MULTI_PERMIT_REQ. This command indicates to the stack that the response
00453  *       can be sent to the client. So if the application wishes to update any of the attributes before
00454  *       they are read by the client, it has to update the characteristic values using the aci_gatt_update_char_value
00455  *       and then give this command. The application should perform the required operations within 30 seconds,
00456  *       otherwise the GATT procedure will go to timeout.
00457  * @param conn_handle Connection handle for which the command is given.
00458  * @return Value indicating success or error code.
00459  */
00460 tBleStatus aci_gatt_allow_read(uint16_t conn_handle);
00461 
00462 /**
00463  * @brief This command sets the value of the descriptor specified by charDescHandle.
00464  * @param servHandle Handle of the service which contains the descriptor.
00465  * @param charHandle Handle of the characteristic which contains the descriptor.
00466  * @param charDescHandle Handle of the descriptor whose value has to be set.
00467  * @param charDescValOffset Offset from which the descriptor value has to be updated.
00468  * @param charDescValueLen Length of the descriptor value
00469  * @param[in] charDescValue descriptor value
00470  * @return Value indicating success or error code.
00471  */
00472 tBleStatus aci_gatt_set_desc_value(uint16_t servHandle,
00473                    uint16_t charHandle,
00474                    uint16_t charDescHandle,
00475                    uint16_t charDescValOffset,
00476                    uint8_t charDescValueLen,
00477                    const uint8_t *charDescValue);
00478 
00479 /**
00480  * @brief Reads the value of the attribute handle specified from the local GATT database.
00481  * @param attr_handle Handle of the attribute to read
00482  * @param data_len Length of the data buffer.
00483  * @param[in] data_len_out_p Length of the read attribute.
00484  * @param[in] data Pointer to the buffer that will contain the read value.
00485  *              The buffer will be filled with the attribute value.
00486  *              The length will be the minimum between the provided data_len and the actual length of the
00487  *              attribute (in data_len_out_p).
00488  * @return Value indicating success or error code.
00489  */
00490 tBleStatus aci_gatt_read_handle_value(uint16_t attr_handle, uint16_t data_len, uint16_t *data_len_out_p, uint8_t *data);
00491 
00492 /**
00493  * @}
00494  */
00495 
00496 
00497 /**
00498  * @defgroup GATT_Events GATT events
00499  * The structures are the data field of @ref evt_blue_aci.
00500  * @{
00501  */
00502 
00503 /**
00504  * This event is raised to the application by the GATT server when a client modifies any attribute on the server,
00505  * if event is enabled (see Gatt_Event_Mask). See @ref evt_gatt_attr_modified.
00506  */
00507 #define EVT_BLUE_GATT_ATTRIBUTE_MODIFIED          (0x0C01)
00508 typedef __packed struct _evt_gatt_attr_modified{
00509   uint16_t conn_handle; /**< The connection handle which modified the attribute. */
00510   uint16_t attr_handle; /**< Handle of the attribute that was modified. */
00511   uint8_t  data_length; /**< The length of the data */
00512   uint8_t  att_data[VARIABLE_SIZE]; /**< The new value (length is data_length) */
00513 } PACKED evt_gatt_attr_modified;
00514 
00515 /**
00516  * This event is generated by the client/server to the application on a GATT timeout (30 seconds).
00517  */
00518 #define EVT_BLUE_GATT_PROCEDURE_TIMEOUT           (0x0C02)
00519 typedef __packed struct _evt_gatt_procedure_timeout{
00520     uint16_t conn_handle; /**< The connection handle handle on which the GATT procedure has timed out */
00521 } PACKED evt_gatt_procedure_timeout;
00522 
00523 /**
00524  * This event is generated in response to an Exchange MTU request. See aci_gatt_exchange_configuration().
00525  */
00526 #define EVT_BLUE_ATT_EXCHANGE_MTU_RESP        (0x0C03)
00527 typedef __packed struct _evt_att_exchange_mtu_resp{
00528   uint16_t conn_handle;
00529   uint8_t  event_data_length;
00530   uint16_t server_rx_mtu;
00531 } PACKED evt_att_exchange_mtu_resp;
00532 
00533 /**
00534  * This event is generated in response to a @a Find @a Information @a Request. See aci_gatt_find_information_req() and
00535  * Find Information Response in Bluetooth Core v4.0 spec.
00536  */
00537 #define EVT_BLUE_ATT_FIND_INFORMATION_RESP    (0x0C04)
00538 typedef __packed struct _evt_att_find_information_resp{
00539   uint16_t conn_handle;
00540   uint8_t  event_data_length;
00541   uint8_t  format;
00542   uint8_t  handle_uuid_pair[VARIABLE_SIZE];
00543 } PACKED evt_att_find_information_resp;
00544 
00545 /**
00546  * This event is generated in response to a @a Find @a By @a Type @a Value @a Request. See
00547  * Find By Type Value Response in Bluetooth Core v4.0 spec.
00548  */
00549 #define EVT_BLUE_ATT_FIND_BY_TYPE_VAL_RESP    (0x0C05)
00550 typedef __packed struct _evt_att_find_by_type_val_resp{
00551   uint16_t conn_handle;
00552   uint8_t  event_data_length;
00553   uint8_t  handles_info_list[VARIABLE_SIZE]; /**< Handles Information List as defined in Bluetooth Core v4.0 spec. */
00554 } PACKED evt_att_find_by_type_val_resp;
00555 
00556 /**
00557  * This event is generated in response to a @a Read @a By @a Type @a Request. See aci_gatt_find_included_services() and
00558  * aci_gatt_disc_all_charac_of_serv().
00559  * For more info see Read By Type Response in Bluetooth Core v4.0 spec.
00560  */
00561 #define EVT_BLUE_ATT_READ_BY_TYPE_RESP        (0x0C06)
00562 typedef __packed struct _evt_att_read_by_type_resp{
00563   uint16_t conn_handle;
00564   uint8_t  event_data_length;
00565   uint8_t  handle_value_pair_length;
00566   uint8_t  handle_value_pair[VARIABLE_SIZE];
00567 } PACKED evt_att_read_by_type_resp;
00568 
00569 /**
00570  * This event is generated in response to a @a Read @a Request. See aci_gatt_read_charac_val().
00571  * For more info see Read Response in Bluetooth Core v4.0 spec.
00572  */
00573 #define EVT_BLUE_ATT_READ_RESP            (0x0C07)
00574 typedef __packed struct _evt_att_read_resp{
00575   uint16_t conn_handle;
00576   uint8_t  event_data_length;
00577   uint8_t  attribute_value[VARIABLE_SIZE];
00578 } PACKED evt_att_read_resp;
00579 
00580 /**
00581  * This event is generated in response to a @a Read @a Blob @a Request. See aci_gatt_read_long_charac_val().
00582  * For more info see Read Blob Response in Bluetooth Core v4.0 spec.
00583  */
00584 #define EVT_BLUE_ATT_READ_BLOB_RESP       (0x0C08)
00585 typedef __packed struct _evt_att_read_blob_resp{
00586   uint16_t conn_handle;
00587   uint8_t  event_data_length;
00588   uint8_t  part_attribute_value[VARIABLE_SIZE];
00589 } PACKED evt_att_read_blob_resp;
00590 
00591 /**
00592  * This event is generated in response to a @a Read @a Multiple @a Request.
00593  * For more info see Read Multiple Response in Bluetooth Core v4.0 spec.
00594  */
00595 #define EVT_BLUE_ATT_READ_MULTIPLE_RESP       (0x0C09)
00596 typedef __packed struct _evt_att_read_mult_resp{
00597   uint16_t conn_handle;
00598   uint8_t  event_data_length;
00599   uint8_t  set_of_values[VARIABLE_SIZE];
00600 } PACKED evt_att_read_mult_resp;
00601 
00602 /**
00603  * This event is generated in response to a @a Read @a By @a Group @a Type @a Request. See aci_gatt_disc_all_prim_services().
00604  * For more info see Read By Group type Response in Bluetooth Core v4.0 spec.
00605  */
00606 #define EVT_BLUE_ATT_READ_BY_GROUP_TYPE_RESP           (0x0C0A)
00607 typedef __packed struct _evt_att_read_by_group_resp{
00608   uint16_t conn_handle;
00609   uint8_t  event_data_length;
00610   uint8_t  handle_value_pair_length;
00611   uint8_t  handle_value_pair[VARIABLE_SIZE];
00612 } PACKED evt_att_read_by_group_resp;
00613 
00614 /**
00615  * This event is generated in response to a @a Write @a Request. See aci_gatt_disc_all_prim_services().
00616  * For more info see Write Response in Bluetooth Core v4.0 spec. Not used in BlueNRG FW 6.3.
00617  */
00618 #define EVT_BLUE_ATT_WRITE_RESP           (0x0C0B)
00619 
00620 /**
00621  * This event is generated in response to a @a Prepare @a Write @a Request.
00622  * For more info see Prepare Write Response in Bluetooth Core v4.0 spec.
00623  */
00624 #define EVT_BLUE_ATT_PREPARE_WRITE_RESP       (0x0C0C)
00625 
00626 /**
00627  * This event is generated in response to an @a Execute @a Write @a Request.
00628  * For more info see Execute Write Response in Bluetooth Core v4.0 spec.
00629  */
00630 #define EVT_BLUE_ATT_EXEC_WRITE_RESP          (0x0C0D)
00631 
00632 /**
00633  * This event is generated when an indication is received from the server.
00634  * For more info see Handle Value Indication in Bluetooth Core v4.0 spec.
00635  */
00636 #define EVT_BLUE_GATT_INDICATION          (0x0C0E)
00637 typedef __packed struct _evt_gatt_indication{
00638   uint16_t conn_handle;
00639   uint8_t  data_length; /**< Lenght of attribute value + handle. */
00640   uint16_t attr_handle;
00641   uint8_t  attr_value[VARIABLE_SIZE];
00642 } PACKED evt_gatt_indication;
00643 
00644 /**
00645  * This event is generated when a notification is received from the server.
00646  * For more info see Handle Value Notification in Bluetooth Core v4.0 spec.
00647  */
00648 #define EVT_BLUE_GATT_NOTIFICATION        (0x0C0F)
00649 typedef __packed struct _evt_gatt_notification{
00650   uint16_t conn_handle;
00651   uint8_t  data_length; /**< Lenght of attribute value + handle. */
00652   uint16_t attr_handle;
00653   uint8_t  attr_value[VARIABLE_SIZE];
00654 } PACKED evt_gatt_attr_notification;
00655 
00656 /**
00657  * This event is generated when a GATT client procedure completes either with error or successfully. See @ref evt_gatt_procedure_complete.
00658  */
00659 #define EVT_BLUE_GATT_PROCEDURE_COMPLETE          (0x0C10)
00660 typedef __packed struct _evt_gatt_procedure_complete{
00661   uint16_t conn_handle; /**< The connection handle on which the GATT procedure has completed */
00662   uint8_t  data_length; /**< Length of error_code field (always 1). */
00663   /**
00664    * Indicates whether the procedure completed with error (BLE_STATUS_FAILED) or was successful (BLE_STATUS_SUCCESS).
00665    */
00666   uint8_t  error_code;
00667 } PACKED evt_gatt_procedure_complete;
00668 
00669 /**
00670  * This event is generated when an Error Response is received from the server. The error response can be given
00671  * by the server at the end of one of the GATT dicovery procedures. This does not mean that the procedure ended
00672  * with an error, but this error event is part of the procedure itself.
00673  */
00674 #define EVT_BLUE_GATT_ERROR_RESP                  (0x0C11)
00675 typedef __packed struct _evt_gatt_error_resp{
00676   uint16_t conn_handle;
00677   uint8_t  event_data_length;
00678   uint8_t  req_opcode;
00679   uint16_t attr_handle;
00680   uint8_t  error_code;
00681 } PACKED evt_gatt_error_resp;
00682 
00683 /**
00684  * This event can be generated during a "Discover Characteristics By UUID" procedure or a "Read using
00685  * Characteristic UUID" procedure.
00686  * The attribute value will be a service declaration as defined in Bluetooth Core v4.0 spec (vol.3, Part G, ch. 3.3.1),
00687  * when a "Discover Characteristics By UUID" has been started. It will be the value of the Characteristic if a
00688  * "Read using Characteristic UUID" has been performed.
00689  */
00690 #define EVT_BLUE_GATT_DISC_READ_CHAR_BY_UUID_RESP (0x0C12)
00691 typedef __packed struct _evt_gatt_disc_read_char_by_uuid_resp{
00692   uint16_t conn_handle;
00693   uint8_t  event_data_length;
00694   uint16_t attr_handle;
00695   uint8_t  attr_value[VARIABLE_SIZE];
00696 } PACKED evt_gatt_disc_read_char_by_uuid_resp;
00697 
00698 /**
00699  * This event is given to the application when a write request, write command or signed write command
00700  * is received by the server from the client. This event will be given to the application only if the
00701  * event bit for this event generation is set when the characteristic was added.
00702  * When this event is received, the application has to check whether the value being requested for write
00703  * is allowed to be written and respond with the command aci_gatt_write_response().
00704  * If the write is rejected by the application, then the value of the attribute will not be modified.
00705  * In case of a write request, an error response will be sent to the client, with the error code as specified by the application.
00706  * In case of write/signed write commands, no response is sent to the client but the attribute is not modified.
00707  * See @ref evt_gatt_write_permit_req.
00708  */
00709 #define EVT_BLUE_GATT_WRITE_PERMIT_REQ            (0x0C13)
00710 typedef __packed struct _evt_gatt_write_permit_req{
00711   uint16_t conn_handle; /**< Handle of the connection on which there was the request to write the attribute. */
00712   uint16_t attr_handle; /**< The handle of the attribute for which the write request has been made by the client */
00713   uint8_t  data_length; /**< Length of data field. */
00714   uint8_t  data[VARIABLE_SIZE]; /**< The data that the client has requested to write */
00715 } PACKED evt_gatt_write_permit_req;
00716 
00717 /**
00718  * This event is given to the application when a read request or read blob request is received by the server
00719  * from the client. This event will be given to the application only if the event bit for this event generation
00720  * is set when the characteristic was added.
00721  * On receiving this event, the application can update the value of the handle if it desires and when done
00722  * it has to use the aci_gatt_allow_read() command to indicate to the stack that it can send the response to the client.
00723  * See @ref evt_gatt_read_permit_req.
00724  *
00725  */
00726 #define EVT_BLUE_GATT_READ_PERMIT_REQ             (0x0C14)
00727 typedef __packed struct _evt_gatt_read_permit_req{
00728   uint16_t conn_handle; /**< Handle of the connection on which there was the request to read the attribute. */
00729   uint16_t attr_handle; /**< The handle of the attribute for which the read request has been made by the client */
00730   uint8_t  data_length; /**< Length of offset field. (always 1). */
00731   uint8_t  offset; /**< Contains the offset from which the read has been requested */
00732 } PACKED evt_gatt_read_permit_req;
00733 
00734 /**
00735  * This event is given to the application when a read multiple request or read by type request is received
00736  * by the server from the client. This event will be given to the application only if the event bit for this
00737  * event generation is set when the characteristic was added.
00738  * On receiving this event, the application can update the values of the handles if it desires and when done
00739  * it has to send the aci_gatt_allow_read command to indicate to the stack that it can send the response to the client.
00740  * See @ref evt_gatt_read_multi_permit_req.
00741  *
00742  */
00743 #define EVT_BLUE_GATT_READ_MULTI_PERMIT_REQ       (0x0C15)
00744 typedef __packed struct _evt_gatt_read_multi_permit_req{
00745   uint16_t conn_handle; /**< Handle of the connection on which there was the request to read the attribute. */
00746   uint8_t  data_length; /**< Length of data field. */
00747   uint8_t  data[VARIABLE_SIZE]; /**< The handles of the attributes that have been requested by the client for a read. */
00748 } PACKED evt_gatt_read_multi_permit_req;
00749 
00750 /**
00751  * @}
00752  */
00753 
00754 #endif /* __BLUENRG_GATT_ACI_H__ */
00755