Nordic stack and drivers for the mbed BLE API. Version to work around build bug.

Dependents:   microbit_rubber_ducky microbit_mouse_BLE microbit_mouse_BLE_daybreak_version microbit_presenter

Fork of nRF51822 by Nordic Semiconductor

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers ble_gatts.h Source File

ble_gatts.h

00001 /*
00002  * Copyright (c) Nordic Semiconductor ASA
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without modification,
00006  * are permitted provided that the following conditions are met:
00007  *
00008  *   1. Redistributions of source code must retain the above copyright notice, this
00009  *   list of conditions and the following disclaimer.
00010  *
00011  *   2. Redistributions in binary form must reproduce the above copyright notice, this
00012  *   list of conditions and the following disclaimer in the documentation and/or
00013  *   other materials provided with the distribution.
00014  *
00015  *   3. Neither the name of Nordic Semiconductor ASA nor the names of other
00016  *   contributors to this software may be used to endorse or promote products
00017  *   derived from this software without specific prior written permission.
00018  *
00019  *
00020  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00021  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00022  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00023  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00024  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00025  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00026  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00027  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00028  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  *
00031  */
00032 
00033 /**
00034   @addtogroup BLE_GATTS Generic Attribute Profile (GATT) Server
00035   @{
00036   @brief  Definitions and prototypes for the GATTS interface.
00037  */
00038 
00039 #ifndef BLE_GATTS_H__
00040 #define BLE_GATTS_H__
00041 
00042 #include "ble_types.h"
00043 #include "ble_ranges.h"
00044 #include "ble_l2cap.h"
00045 #include "ble_gap.h"
00046 #include "ble_gatt.h"
00047 #include "nrf_svc.h"
00048 
00049 /** @addtogroup BLE_GATTS_ENUMERATIONS Enumerations
00050  * @{ */
00051 
00052 /**
00053  * @brief GATTS API SVC numbers.
00054  */
00055 enum BLE_GATTS_SVCS
00056 {
00057   SD_BLE_GATTS_SERVICE_ADD = BLE_GATTS_SVC_BASE, /**< Add a service. */
00058   SD_BLE_GATTS_INCLUDE_ADD,                      /**< Add an included service. */
00059   SD_BLE_GATTS_CHARACTERISTIC_ADD,               /**< Add a characteristic. */
00060   SD_BLE_GATTS_DESCRIPTOR_ADD,                   /**< Add a generic attribute. */
00061   SD_BLE_GATTS_VALUE_SET,                        /**< Set an attribute value. */
00062   SD_BLE_GATTS_VALUE_GET,                        /**< Get an attribute value. */
00063   SD_BLE_GATTS_HVX,                              /**< Handle Value Notification or Indication. */
00064   SD_BLE_GATTS_SERVICE_CHANGED,                  /**< Perform a Service Changed Indication to one or more peers. */
00065   SD_BLE_GATTS_RW_AUTHORIZE_REPLY,               /**< Reply to an authorization request for a read or write operation on one or more attributes. */ 
00066   SD_BLE_GATTS_SYS_ATTR_SET,                     /**< Set the persistent system attributes for a connection. */  
00067   SD_BLE_GATTS_SYS_ATTR_GET,                     /**< Retrieve the persistent system attributes. */
00068 };
00069 
00070 /**
00071  * @brief GATT Server Event IDs.
00072  */
00073 enum BLE_GATTS_EVTS
00074 {
00075   BLE_GATTS_EVT_WRITE = BLE_GATTS_EVT_BASE,       /**< Write operation performed. @ref ble_gatts_evt_write_t */
00076   BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST,             /**< Read/Write Authorization request.@ref ble_gatts_evt_rw_authorize_request_t */
00077   BLE_GATTS_EVT_SYS_ATTR_MISSING,                 /**< A persistent system attribute access is pending, awaiting a sd_ble_gatts_sys_attr_set(). @ref ble_gatts_evt_sys_attr_missing_t */
00078   BLE_GATTS_EVT_HVC,                              /**< Handle Value Confirmation. @ref ble_gatts_evt_hvc_t */
00079   BLE_GATTS_EVT_SC_CONFIRM,                       /**< Service Changed Confirmation. No additional event structure applies. */
00080   BLE_GATTS_EVT_TIMEOUT                           /**< Timeout. @ref ble_gatts_evt_timeout_t */
00081 };
00082 /** @} */
00083 
00084 /** @addtogroup BLE_GATTS_DEFINES Defines
00085  * @{ */
00086 
00087 /** @defgroup BLE_ERRORS_GATTS SVC return values specific to GATTS
00088  * @{ */
00089 #define BLE_ERROR_GATTS_INVALID_ATTR_TYPE   (NRF_GATTS_ERR_BASE + 0x000) /**< Invalid attribute type. */
00090 #define BLE_ERROR_GATTS_SYS_ATTR_MISSING    (NRF_GATTS_ERR_BASE + 0x001) /**< System Attributes missing. */
00091 /** @} */
00092 
00093 /** @defgroup BLE_GATTS_ATTR_LENS_MAX Maximum attribute lengths
00094  * @{ */
00095 #define BLE_GATTS_FIX_ATTR_LEN_MAX (510)  /**< Maximum length for fixed length Attribute Values. */
00096 #define BLE_GATTS_VAR_ATTR_LEN_MAX (512)  /**< Maximum length for variable length Attribute Values. */ 
00097 /** @} */
00098 
00099 /** @defgroup BLE_GATTS_SRVC_TYPES GATT Server Service Types
00100  * @{ */
00101 #define BLE_GATTS_SRVC_TYPE_INVALID          0x00  /**< Invalid Service Type. */
00102 #define BLE_GATTS_SRVC_TYPE_PRIMARY          0x01  /**< Primary Service. */
00103 #define BLE_GATTS_SRVC_TYPE_SECONDARY        0x02  /**< Secondary Type. */
00104 /** @} */
00105 
00106 
00107 /** @defgroup BLE_GATTS_ATTR_TYPES GATT Server Attribute Types
00108  * @{ */
00109 #define BLE_GATTS_ATTR_TYPE_INVALID         0x00  /**< Invalid Attribute Type. */
00110 #define BLE_GATTS_ATTR_TYPE_PRIM_SRVC_DECL  0x01  /**< Primary Service Declaration. */
00111 #define BLE_GATTS_ATTR_TYPE_SEC_SRVC_DECL   0x02  /**< Secondary Service Declaration. */
00112 #define BLE_GATTS_ATTR_TYPE_INC_DECL        0x03  /**< Include Declaration. */
00113 #define BLE_GATTS_ATTR_TYPE_CHAR_DECL       0x04  /**< Characteristic Declaration. */
00114 #define BLE_GATTS_ATTR_TYPE_CHAR_VAL        0x05  /**< Characteristic Value. */
00115 #define BLE_GATTS_ATTR_TYPE_DESC            0x06  /**< Descriptor. */
00116 #define BLE_GATTS_ATTR_TYPE_OTHER           0x07  /**< Other, non-GATT specific type. */
00117 /** @} */
00118 
00119 
00120 /** @defgroup BLE_GATTS_OPS GATT Server Operations
00121  * @{ */
00122 #define BLE_GATTS_OP_INVALID                0x00  /**< Invalid Operation. */
00123 #define BLE_GATTS_OP_WRITE_REQ              0x01  /**< Write Request. */
00124 #define BLE_GATTS_OP_WRITE_CMD              0x02  /**< Write Command. */
00125 #define BLE_GATTS_OP_SIGN_WRITE_CMD         0x03  /**< Signed Write Command. */
00126 #define BLE_GATTS_OP_PREP_WRITE_REQ         0x04  /**< Prepare Write Request. */
00127 #define BLE_GATTS_OP_EXEC_WRITE_REQ_CANCEL  0x05  /**< Execute Write Request: Cancel all prepared writes. */
00128 #define BLE_GATTS_OP_EXEC_WRITE_REQ_NOW     0x06  /**< Execute Write Request: Immediately execute all prepared writes. */
00129 /** @} */
00130 
00131 /** @defgroup BLE_GATTS_VLOCS GATT Value Locations
00132  * @{ */
00133 #define BLE_GATTS_VLOC_INVALID       0x00  /**< Invalid Location. */
00134 #define BLE_GATTS_VLOC_STACK         0x01  /**< Attribute Value is located in stack memory, no user memory is required. */
00135 #define BLE_GATTS_VLOC_USER          0x02  /**< Attribute Value is located in user memory. This requires the user to maintain a valid buffer through the lifetime of the attribute, since the stack
00136                                                 will read and write directly to the memory using the pointer provided in the APIs. There are no alignment requirements for the buffer. */
00137 /** @} */
00138 
00139 /** @defgroup BLE_GATTS_AUTHORIZE_TYPES GATT Server Authorization Types
00140  * @{ */
00141 #define BLE_GATTS_AUTHORIZE_TYPE_INVALID    0x00  /**< Invalid Type. */
00142 #define BLE_GATTS_AUTHORIZE_TYPE_READ       0x01  /**< Authorize a Read Operation. */
00143 #define BLE_GATTS_AUTHORIZE_TYPE_WRITE      0x02  /**< Authorize a Write Request Operation. */
00144 /** @} */
00145 
00146 /** @defgroup BLE_GATTS_SYS_ATTR_FLAGS System Attribute Flags
00147  * @{ */
00148 #define BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS (1 << 0)  /**< Restrict system attributes to system services only. */
00149 #define BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS (1 << 1)  /**< Restrict system attributes to user services only. */
00150 /** @} */
00151 
00152 /** @defgroup BLE_GATTS_ATTR_TAB_SIZE Attribute Table size
00153  * @{
00154  */
00155 #define BLE_GATTS_ATTR_TAB_SIZE_MIN         216    /**< Minimum Attribute Table size */
00156 #define BLE_GATTS_ATTR_TAB_SIZE_DEFAULT     0x0000 /**< Default Attribute Table size (0x600 bytes for this version of the SoftDevice). */
00157 /** @} */
00158 
00159 /** @} */
00160 
00161 /** @addtogroup BLE_GATTS_STRUCTURES Structures
00162  * @{ */
00163 
00164 /**
00165  * @brief BLE GATTS init options
00166  */
00167 typedef struct
00168 {
00169   uint8_t   service_changed:1;             /**< Include the Service Changed characteristic in the Attribute Table. */
00170   uint32_t  attr_tab_size;                 /**< Attribute Table size in bytes. The size must be a multiple of 4. @ref BLE_GATTS_ATTR_TAB_SIZE_DEFAULT is used to set the default size. */
00171 } ble_gatts_enable_params_t;
00172 
00173 /**@brief Attribute metadata. */
00174 typedef struct
00175 {
00176   ble_gap_conn_sec_mode_t read_perm;       /**< Read permissions. */
00177   ble_gap_conn_sec_mode_t write_perm;      /**< Write permissions. */
00178   uint8_t                 vlen       :1;   /**< Variable length attribute. */
00179   uint8_t                 vloc       :2;   /**< Value location, see @ref BLE_GATTS_VLOCS.*/
00180   uint8_t                 rd_auth    :1;   /**< Read authorization and value will be requested from the application on every read operation. */ 
00181   uint8_t                 wr_auth    :1;   /**< Write authorization will be requested from the application on every Write Request operation (but not Write Command). */
00182 } ble_gatts_attr_md_t;
00183 
00184 
00185 /**@brief GATT Attribute. */
00186 typedef struct
00187 {
00188   ble_uuid_t          *p_uuid;          /**< Pointer to the attribute UUID. */
00189   ble_gatts_attr_md_t *p_attr_md;       /**< Pointer to the attribute metadata structure. */
00190   uint16_t             init_len;        /**< Initial attribute value length in bytes. */
00191   uint16_t             init_offs;       /**< Initial attribute value offset in bytes. If different from zero, the first init_offs bytes of the attribute value will be left uninitialized. */
00192   uint16_t             max_len;         /**< Maximum attribute value length in bytes, see @ref BLE_GATTS_ATTR_LENS_MAX for maximum values. */
00193   uint8_t*             p_value;         /**< Pointer to the attribute data. Please note that if the @ref BLE_GATTS_VLOC_USER value location is selected in the attribute metadata, this will have to point to a buffer
00194                                              that remains valid through the lifetime of the attribute. This excludes usage of automatic variables that may go out of scope or any other temporary location. 
00195                                              The stack may access that memory directly without the application's knowledge. For writable characteristics, this value must not be a location in flash memory.*/
00196 } ble_gatts_attr_t;
00197 
00198 /**@brief GATT Attribute Value. */
00199 typedef struct
00200 {
00201   uint16_t  len;        /**< Length in bytes to be written or read. Length in bytes written or read after successful return.*/
00202   uint16_t  offset;     /**< Attribute value offset. */
00203   uint8_t   *p_value;   /**< Pointer to where value is stored or will be stored. 
00204                              If value is stored in user memory, only the attribute length is updated when p_value == NULL.
00205                              Set to NULL when reading to obtain the complete length of the attribute value */
00206 } ble_gatts_value_t;
00207 
00208 
00209 /**@brief GATT Attribute Context. */
00210 typedef struct
00211 {
00212   ble_uuid_t           srvc_uuid;       /**< Service UUID. */
00213   ble_uuid_t           char_uuid;       /**< Characteristic UUID if applicable (BLE_UUID_TYPE_UNKNOWN otherwise). */
00214   ble_uuid_t           desc_uuid;       /**< Descriptor UUID if applicable (BLE_UUID_TYPE_UNKNOWN otherwise). */
00215   uint16_t             srvc_handle;     /**< Service Handle. */
00216   uint16_t             value_handle;    /**< Characteristic Value Handle if applicable (BLE_GATT_HANDLE_INVALID otherwise). */
00217   uint8_t              type;            /**< Attribute Type, see @ref BLE_GATTS_ATTR_TYPES. */
00218 } ble_gatts_attr_context_t;
00219 
00220 
00221 /**@brief GATT Characteristic Presentation Format. */
00222 typedef struct
00223 {
00224   uint8_t          format;      /**< Format of the value, see @ref BLE_GATT_CPF_FORMATS. */
00225   int8_t           exponent;    /**< Exponent for integer data types. */
00226   uint16_t         unit;        /**< Unit from Bluetooth Assigned Numbers. */
00227   uint8_t          name_space;  /**< Namespace from Bluetooth Assigned Numbers, see @ref BLE_GATT_CPF_NAMESPACES. */
00228   uint16_t         desc;        /**< Namespace description from Bluetooth Assigned Numbers, see @ref BLE_GATT_CPF_NAMESPACES. */
00229 } ble_gatts_char_pf_t;
00230 
00231 
00232 /**@brief GATT Characteristic metadata. */
00233 typedef struct
00234 {
00235   ble_gatt_char_props_t       char_props;               /**< Characteristic Properties. */
00236   ble_gatt_char_ext_props_t   char_ext_props;           /**< Characteristic Extended Properties. */
00237   uint8_t                    *p_char_user_desc;         /**< Pointer to a UTF-8 encoded string (non-NULL terminated), NULL if the descriptor is not required. */
00238   uint16_t                    char_user_desc_max_size;  /**< The maximum size in bytes of the user description descriptor. */
00239   uint16_t                    char_user_desc_size;      /**< The size of the user description, must be smaller or equal to char_user_desc_max_size. */ 
00240   ble_gatts_char_pf_t*        p_char_pf;                /**< Pointer to a presentation format structure or NULL if the CPF descriptor is not required. */
00241   ble_gatts_attr_md_t*        p_user_desc_md;           /**< Attribute metadata for the User Description descriptor, or NULL for default values. */
00242   ble_gatts_attr_md_t*        p_cccd_md;                /**< Attribute metadata for the Client Characteristic Configuration Descriptor, or NULL for default values. */
00243   ble_gatts_attr_md_t*        p_sccd_md;                /**< Attribute metadata for the Server Characteristic Configuration Descriptor, or NULL for default values. */
00244 } ble_gatts_char_md_t;
00245 
00246 
00247 /**@brief GATT Characteristic Definition Handles. */
00248 typedef struct
00249 {
00250   uint16_t          value_handle;       /**< Handle to the characteristic value. */
00251   uint16_t          user_desc_handle;   /**< Handle to the User Description descriptor, or @ref BLE_GATT_HANDLE_INVALID if not present. */
00252   uint16_t          cccd_handle;        /**< Handle to the Client Characteristic Configuration Descriptor, or @ref BLE_GATT_HANDLE_INVALID if not present. */
00253   uint16_t          sccd_handle;        /**< Handle to the Server Characteristic Configuration Descriptor, or @ref BLE_GATT_HANDLE_INVALID if not present. */
00254 } ble_gatts_char_handles_t;
00255 
00256 
00257 /**@brief GATT HVx parameters. */
00258 typedef struct
00259 {
00260   uint16_t          handle;             /**< Characteristic Value Handle. */
00261   uint8_t           type;               /**< Indication or Notification, see @ref BLE_GATT_HVX_TYPES. */
00262   uint16_t          offset;             /**< Offset within the attribute value. */
00263   uint16_t         *p_len;              /**< Length in bytes to be written, length in bytes written after successful return. */
00264   uint8_t          *p_data;             /**< Actual data content, use NULL to use the current attribute value. */
00265 } ble_gatts_hvx_params_t;
00266 
00267 /**@brief GATT Read Authorization parameters. */
00268 typedef struct
00269 {
00270   uint16_t          gatt_status;        /**< GATT status code for the operation, see @ref BLE_GATT_STATUS_CODES. */
00271   uint8_t           update : 1;         /**< If set, data supplied in p_data will be used in the ATT response. */
00272   uint16_t          offset;             /**< Offset of the attribute value being updated. */
00273   uint16_t          len;                /**< Length in bytes of the value in p_data pointer, see @ref BLE_GATTS_ATTR_LENS_MAX. */
00274   uint8_t          *p_data;             /**< Pointer to new value used to update the attribute value. */
00275 } ble_gatts_read_authorize_params_t;
00276 
00277 /**@brief GATT Write Authorization parameters. */
00278 typedef struct
00279 {
00280   uint16_t          gatt_status;        /**< GATT status code for the operation, see @ref BLE_GATT_STATUS_CODES. */
00281 } ble_gatts_write_authorize_params_t;
00282 
00283 /**@brief GATT Read or Write Authorize Reply parameters. */
00284 typedef struct
00285 {
00286   uint8_t                               type;   /**< Type of authorize operation, see @ref BLE_GATTS_AUTHORIZE_TYPES. */
00287   union {
00288     ble_gatts_read_authorize_params_t   read;   /**< Read authorization parameters. */
00289     ble_gatts_write_authorize_params_t  write;  /**< Write authorization parameters. */
00290   } params;                                     /**< Reply Parameters. */
00291 } ble_gatts_rw_authorize_reply_params_t;
00292 
00293 
00294 
00295 /**@brief Event structure for @ref BLE_GATTS_EVT_WRITE. */
00296 typedef struct
00297 {
00298   uint16_t                    handle;             /**< Attribute Handle. */
00299   uint8_t                     op;                 /**< Type of write operation, see @ref BLE_GATTS_OPS. */
00300   ble_gatts_attr_context_t    context;            /**< Attribute Context. */
00301   uint16_t                    offset;             /**< Offset for the write operation. */
00302   uint16_t                    len;                /**< Length of the received data. */
00303   uint8_t                     data[1];            /**< Received data, variable length. */
00304 } ble_gatts_evt_write_t;
00305 
00306 /**@brief Event substructure for authorized read requests, see @ref ble_gatts_evt_rw_authorize_request_t. */
00307 typedef struct
00308 {
00309   uint16_t                    handle;             /**< Attribute Handle. */
00310   ble_gatts_attr_context_t    context;            /**< Attribute Context. */
00311   uint16_t                    offset;             /**< Offset for the read operation. */
00312 } ble_gatts_evt_read_t;
00313 
00314 /**@brief Event structure for @ref BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST. */
00315 typedef struct
00316 {
00317   uint8_t                     type;             /**< Type of authorize operation, see @ref BLE_GATTS_AUTHORIZE_TYPES. */
00318   union {
00319     ble_gatts_evt_read_t      read;             /**< Attribute Read Parameters. */
00320     ble_gatts_evt_write_t     write;            /**< Attribute Write Parameters. */
00321   } request;                                    /**< Request Parameters. */
00322 } ble_gatts_evt_rw_authorize_request_t;
00323 
00324 /**@brief Event structure for @ref BLE_GATTS_EVT_SYS_ATTR_MISSING. */
00325 typedef struct
00326 {
00327   uint8_t hint;                                 /**< Hint (currently unused). */
00328 } ble_gatts_evt_sys_attr_missing_t;
00329 
00330 
00331 /**@brief Event structure for @ref BLE_GATTS_EVT_HVC. */
00332 typedef struct
00333 {
00334   uint16_t          handle;                       /**< Attribute Handle. */
00335 } ble_gatts_evt_hvc_t;
00336 
00337 /**@brief Event structure for @ref BLE_GATTS_EVT_TIMEOUT. */
00338 typedef struct
00339 {
00340   uint8_t          src;                       /**< Timeout source, see @ref BLE_GATT_TIMEOUT_SOURCES. */
00341 } ble_gatts_evt_timeout_t;
00342 
00343 
00344 /**@brief GATT Server event callback event structure. */
00345 typedef struct
00346 {
00347   uint16_t conn_handle;                                       /**< Connection Handle on which the event occurred. */
00348   union
00349   {
00350     ble_gatts_evt_write_t                 write;              /**< Write Event Parameters. */
00351     ble_gatts_evt_rw_authorize_request_t  authorize_request;  /**< Read or Write Authorize Request Parameters. */
00352     ble_gatts_evt_sys_attr_missing_t      sys_attr_missing;   /**< System attributes missing. */
00353     ble_gatts_evt_hvc_t                   hvc;                /**< Handle Value Confirmation Event Parameters. */
00354     ble_gatts_evt_timeout_t               timeout;            /**< Timeout Event. */
00355   } params;                                                   /**< Event Parameters. */
00356 } ble_gatts_evt_t;
00357 
00358 /** @} */
00359 
00360 /** @addtogroup BLE_GATTS_FUNCTIONS Functions
00361  * @{ */
00362 
00363 /**@brief Add a service declaration to the Attribute Table.
00364  *
00365  * @param[in] type      Toggles between primary and secondary services, see @ref BLE_GATTS_SRVC_TYPES.
00366  * @param[in] p_uuid    Pointer to service UUID.
00367  * @param[out] p_handle Pointer to a 16-bit word where the assigned handle will be stored.
00368  *
00369  * @note Secondary Services are only relevant in the context of the entity that references them, it is therefore forbidden to
00370  *       add a secondary service declaration that is not referenced by another service later in the Attribute Table.
00371  *
00372  * @retval ::NRF_SUCCESS Successfully added a service declaration.
00373  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00374  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, Vendor Specific UUIDs need to be present in the table.
00375  * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack.
00376  * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
00377  */
00378 SVCALL(SD_BLE_GATTS_SERVICE_ADD, uint32_t, sd_ble_gatts_service_add(uint8_t type, ble_uuid_t const *p_uuid, uint16_t *p_handle));
00379 
00380 
00381 /**@brief Add an include declaration to the Attribute Table.
00382  *
00383  * @note It is currently only possible to add an include declaration to the last added service (i.e. only sequential population is supported at this time). 
00384  *
00385  * @note The included service must already be present in the Attribute Table prior to this call.
00386  *
00387  * @param[in] service_handle    Handle of the service where the included service is to be placed, if @ref BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
00388  * @param[in] inc_srvc_handle   Handle of the included service.
00389  * @param[out] p_include_handle Pointer to a 16-bit word where the assigned handle will be stored.
00390  *
00391  * @retval ::NRF_SUCCESS Successfully added an include declaration.
00392  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00393  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, handle values need to match previously added services.
00394  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
00395  * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, self inclusions are not allowed.
00396  * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
00397  * @retval ::NRF_ERROR_NOT_FOUND Attribute not found.
00398  */
00399 SVCALL(SD_BLE_GATTS_INCLUDE_ADD, uint32_t, sd_ble_gatts_include_add(uint16_t service_handle, uint16_t inc_srvc_handle, uint16_t *p_include_handle));
00400 
00401 
00402 /**@brief Add a characteristic declaration, a characteristic value declaration and optional characteristic descriptor declarations to the Attribute Table.
00403  *
00404  * @note It is currently only possible to add a characteristic to the last added service (i.e. only sequential population is supported at this time). 
00405  *
00406  * @note Several restrictions apply to the parameters, such as matching permissions between the user description descriptor and the writeable auxiliaries bits,
00407  *       readable (no security) and writeable (selectable) CCCDs and SCCDs and valid presentation format values.
00408  *
00409  * @note If no metadata is provided for the optional descriptors, their permissions will be derived from the characteristic permissions.
00410  *
00411  * @param[in] service_handle    Handle of the service where the characteristic is to be placed, if @ref BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
00412  * @param[in] p_char_md         Characteristic metadata.
00413  * @param[in] p_attr_char_value Pointer to the attribute structure corresponding to the characteristic value.
00414  * @param[out] p_handles        Pointer to the structure where the assigned handles will be stored.
00415  *
00416  * @retval ::NRF_SUCCESS Successfully added a characteristic.
00417  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00418  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, service handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints.
00419  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation, a service context is required.
00420  * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack.
00421  * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
00422  * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX.
00423  */
00424 SVCALL(SD_BLE_GATTS_CHARACTERISTIC_ADD, uint32_t, sd_ble_gatts_characteristic_add(uint16_t service_handle, ble_gatts_char_md_t const *p_char_md, ble_gatts_attr_t const *p_attr_char_value, ble_gatts_char_handles_t *p_handles));
00425 
00426 
00427 /**@brief Add a descriptor to the Attribute Table.
00428  *
00429  * @note It is currently only possible to add a descriptor to the last added characteristic (i.e. only sequential population is supported at this time). 
00430  *
00431  * @param[in] char_handle   Handle of the characteristic where the descriptor is to be placed, if @ref BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
00432  * @param[in] p_attr        Pointer to the attribute structure.
00433  * @param[out] p_handle     Pointer to a 16-bit word where the assigned handle will be stored.
00434  *
00435  * @retval ::NRF_SUCCESS Successfully added a descriptor.
00436  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00437  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, characteristic handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints.
00438  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation, a characteristic context is required.
00439  * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack.
00440  * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
00441  * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX.
00442  */
00443 SVCALL(SD_BLE_GATTS_DESCRIPTOR_ADD, uint32_t, sd_ble_gatts_descriptor_add(uint16_t char_handle, ble_gatts_attr_t const *p_attr, uint16_t *p_handle));
00444 
00445 /**@brief Set the value of a given attribute.
00446  *
00447  * @param[in] conn_handle  Connection handle. If the value does not belong to a system attribute then @ref BLE_CONN_HANDLE_INVALID can be used.
00448  * @param[in] handle       Attribute handle.
00449  * @param[in,out] p_value  Attribute value information.
00450  *
00451  * @note Values other than system attributes can be set at any time, regardless of wheter any active connections exist.
00452  *
00453  * @retval ::NRF_SUCCESS Successfully set the value of the attribute.
00454  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00455  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00456  * @retval ::NRF_ERROR_NOT_FOUND Attribute not found.
00457  * @retval ::NRF_ERROR_FORBIDDEN Forbidden handle supplied, certain attributes are not modifiable by the application.
00458  * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX.
00459  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
00460  * @retval ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE @ref BLE_CONN_HANDLE_INVALID supplied on a system attribute.
00461  */
00462 SVCALL(SD_BLE_GATTS_VALUE_SET, uint32_t, sd_ble_gatts_value_set(uint16_t conn_handle, uint16_t handle, ble_gatts_value_t *p_value));
00463 
00464 /**@brief Get the value of a given attribute.
00465  *
00466  * @param[in] conn_handle  Connection handle. If the value does not belong to a system attribute then @ref BLE_CONN_HANDLE_INVALID can be used.
00467  * @param[in] handle       Attribute handle.
00468  * @param[in,out] p_value  Attribute value information.
00469  *
00470  * @note                 If the attribute value is longer than the size of the supplied buffer,
00471  *                       p_len will return the total attribute value length (excluding offset),
00472  *                       and not the number of bytes actually returned in p_data.
00473  *                       The application may use this information to allocate a suitable buffer size.
00474  * 
00475  * @note                 When retrieving system attribute values with this function, the connection handle
00476  *                       may refer to an already disconnected connection. Refer to the documentation of
00477  *                       @ref sd_ble_gatts_sys_attr_get for further information.
00478  *
00479  * @retval ::NRF_SUCCESS Successfully retrieved the value of the attribute.
00480  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00481  * @retval ::NRF_ERROR_NOT_FOUND Attribute not found.
00482  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
00483  * @retval ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE @ref BLE_CONN_HANDLE_INVALID supplied on a system attribute.
00484  */
00485 SVCALL(SD_BLE_GATTS_VALUE_GET, uint32_t, sd_ble_gatts_value_get(uint16_t conn_handle, uint16_t handle, ble_gatts_value_t *p_value));
00486 
00487 /**@brief Notify or Indicate an attribute value.
00488  *
00489  * @details This function checks for the relevant Client Characteristic Configuration descriptor value to verify that the relevant operation
00490  *          (notification or indication) has been enabled by the client. It is also able to update the attribute value before issuing the PDU, so that
00491  *          the application can atomically perform a value update and a server initiated transaction with a single API call.
00492  *          If the application chooses to indicate an attribute value, a @ref BLE_GATTS_EVT_HVC event will be issued as soon as the confirmation arrives from
00493  *          the peer.
00494  *
00495  * @note    The local attribute value may be updated even if an outgoing packet is not sent to the peer due to an error during execution. 
00496  *          When receiveing the error codes @ref NRF_ERROR_INVALID_STATE, @ref NRF_ERROR_BUSY, @ref BLE_ERROR_GATTS_SYS_ATTR_MISSING and 
00497  *          @ref BLE_ERROR_NO_TX_BUFFERS the Attribute Table has been updated.
00498  *          The caller can check whether the value has been updated by looking at the contents of *(p_hvx_params->p_len).
00499  *
00500  * @note    It is important to note that a notification will <b>consume an application buffer</b>, and will therefore 
00501  *          generate a @ref BLE_EVT_TX_COMPLETE event when the packet has been transmitted. An indication on the other hand will use the 
00502  *          standard server internal buffer and thus will only generate a @ref BLE_GATTS_EVT_HVC event as soon as the confirmation 
00503  *          has been received from the peer. Please see the documentation of @ref sd_ble_tx_buffer_count_get for more details.
00504  *
00505  * @param[in] conn_handle  Connection handle.
00506  * @param[in] p_hvx_params Pointer to an HVx parameters structure. If the p_data member contains a non-NULL pointer the attribute value will be updated with
00507  *                         the contents pointed by it before sending the notification or indication.
00508  *
00509  * @retval ::NRF_SUCCESS Successfully queued a notification or indication for transmission, and optionally updated the attribute value.
00510  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
00511  * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State or notifications and/or indications not enabled in the CCCD.
00512  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00513  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00514  * @retval ::BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied. Only attributes added directly by the application are available to notify and indicate.
00515  * @retval ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE Invalid attribute type(s) supplied, only characteristic values may be notified and indicated.
00516  * @retval ::NRF_ERROR_NOT_FOUND Attribute not found.
00517  * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied.
00518  * @retval ::NRF_ERROR_BUSY Procedure already in progress.
00519  * @retval ::BLE_ERROR_GATTS_SYS_ATTR_MISSING System attributes missing, use @ref sd_ble_gatts_sys_attr_set to set them to a known value.
00520  * @retval ::BLE_ERROR_NO_TX_BUFFERS There are no available buffers to send the data, applies only to notifications.
00521  */
00522 SVCALL(SD_BLE_GATTS_HVX, uint32_t, sd_ble_gatts_hvx(uint16_t conn_handle, ble_gatts_hvx_params_t const *p_hvx_params));
00523 
00524 /**@brief Indicate the Service Changed attribute value.
00525  *
00526  * @details This call will send a Handle Value Indication to one or more peers connected to inform them that the Attribute
00527  *          Table layout has changed. As soon as the peer has confirmed the indication, a @ref BLE_GATTS_EVT_SC_CONFIRM event will
00528  *          be issued.
00529  *
00530  * @note    Some of the restrictions and limitations that apply to @ref sd_ble_gatts_hvx also apply here.
00531  *
00532  * @param[in] conn_handle  Connection handle.
00533  * @param[in] start_handle Start of affected attribute handle range.
00534  * @param[in] end_handle   End of affected attribute handle range.
00535  *
00536  * @retval ::NRF_SUCCESS Successfully queued the Service Changed indication for transmission.
00537  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
00538  * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State or notifications and/or indications not enabled in the CCCD.
00539  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00540  * @retval ::BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied, handles must be in the range populated by the application.
00541  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation, notifications or indications must be enabled in the CCCD.
00542  * @retval ::NRF_ERROR_BUSY Procedure already in progress.
00543  * @retval ::BLE_ERROR_GATTS_SYS_ATTR_MISSING System attributes missing, use @ref sd_ble_gatts_sys_attr_set to set them to a known value.
00544  */
00545 SVCALL(SD_BLE_GATTS_SERVICE_CHANGED, uint32_t, sd_ble_gatts_service_changed(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle));
00546 
00547 /**@brief Respond to a Read/Write authorization request.
00548  *
00549  * @note This call should only be used as a response to a @ref BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST event issued to the application.
00550  *
00551  * @param[in] conn_handle                 Connection handle.
00552  * @param[in] p_rw_authorize_reply_params Pointer to a structure with the attribute provided by the application.
00553  *
00554  * @retval ::NRF_SUCCESS               Successfully queued a response to the peer, and in the case of a write operation, Attribute Table updated.
00555  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
00556  * @retval ::NRF_ERROR_INVALID_STATE   Invalid Connection State or no authorization request pending.
00557  * @retval ::NRF_ERROR_INVALID_PARAM   Authorization op invalid,
00558  *                                         or for Read Authorization reply: requested handles not replied with,
00559  *                                         or for Write Authorization reply: handle supplied does not match requested handle.
00560  * @retval ::NRF_ERROR_BUSY The stack is busy. Retry at later time.
00561  */
00562 SVCALL(SD_BLE_GATTS_RW_AUTHORIZE_REPLY, uint32_t, sd_ble_gatts_rw_authorize_reply(uint16_t conn_handle, ble_gatts_rw_authorize_reply_params_t const *p_rw_authorize_reply_params));
00563 
00564 
00565 /**@brief Update persistent system attribute information.
00566  *
00567  * @details Supply information about persistent system attributes to the stack, 
00568  *          previously obtained using @ref sd_ble_gatts_sys_attr_get.
00569  *          This call is only allowed for active connections, and is usually 
00570  *          made immediately after a connection is established with an known bonded device,
00571  *          often as a response to a @ref BLE_GATTS_EVT_SYS_ATTR_MISSING.
00572  *
00573  *          p_sysattrs may point directly to the application's stored copy of the system attributes 
00574  *          obtained using @ref sd_ble_gatts_sys_attr_get.
00575  *          If the pointer is NULL, the system attribute info is initialized, assuming that
00576  *          the application does not have any previously saved system attribute data for this device.
00577  *
00578  * @note The state of persistent system attributes is reset upon connection establishment and then remembered for its duration. 
00579  *
00580  * @note If this call returns with an error code different from @ref NRF_SUCCESS, the storage of persistent system attributes may have been completed only partially.
00581  *       This means that the state of the attribute table is undefined, and the application should either provide a new set of attributes using this same call or
00582  *       reset the SoftDevice to return to a known state.
00583  *
00584  * @note When the @ref BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS is used with this function, only the system attributes included in system services will be modified.
00585  * @note When the @ref BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS is used with this function, only the system attributes included in user services will be modified.
00586  *
00587  * @param[in]  conn_handle        Connection handle.
00588  * @param[in]  p_sys_attr_data    Pointer to a saved copy of system attributes supplied to the stack, or NULL.
00589  * @param[in]  len                Size of data pointed by p_sys_attr_data, in octets. 
00590  * @param[in]  flags              Optional additional flags, see @ref BLE_GATTS_SYS_ATTR_FLAGS
00591  *
00592  * @retval ::NRF_SUCCESS Successfully set the system attribute information.
00593  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
00594  * @retval ::NRF_ERROR_INVALID_STATE   Invalid Connection State.
00595  * @retval ::NRF_ERROR_INVALID_DATA Invalid data supplied, the data should be exactly the same as retrieved with @ref sd_ble_gatts_sys_attr_get.
00596  * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
00597  * @retval ::NRF_ERROR_BUSY The stack is busy. Retry at later time.
00598  */ 
00599 SVCALL(SD_BLE_GATTS_SYS_ATTR_SET, uint32_t, sd_ble_gatts_sys_attr_set(uint16_t conn_handle, uint8_t const *p_sys_attr_data, uint16_t len, uint32_t flags)); 
00600 
00601  
00602 /**@brief Retrieve persistent system attribute information from the stack.
00603  *
00604  * @details This call is used to retrieve information about values to be stored perisistently by the application
00605  *          during the lifetime of a connection or after it has been terminated. When a new connection is established with the same bonded device, 
00606  *          the system attribute information retrieved with this function should be restored using using @ref sd_ble_gatts_sys_attr_set.
00607  *          If retrieved after disconnection, the data should be read before a new connection established. The connection handle for
00608  *          the previous, now disconnected, connection will remain valid until a new one is created to allow this API call to refer to it.
00609  *          Connection handles belonging to active connections can be used as well, but care should be taken since the system attributes
00610  *          may be written to at any time by the peer during a connection's lifetime.
00611  *
00612  * @note When the @ref BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS is used with this function, only the system attributes included in system services will be returned.
00613  * @note When the @ref BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS is used with this function, only the system attributes included in user services will be returned.
00614  *
00615  * @param[in]     conn_handle       Connection handle of the recently terminated connection.
00616  * @param[out]    p_sys_attr_data   Pointer to a buffer where updated information about system attributes will be filled in. NULL can be provided to 
00617  *                                  obtain the length of the data
00618  * @param[in,out] p_len             Size of application buffer if p_sys_attr_data is not NULL. Unconditially updated to actual length of system attribute data.
00619  * @param[in]     flags             Optional additional flags, see @ref BLE_GATTS_SYS_ATTR_FLAGS
00620  *
00621  * @retval ::NRF_SUCCESS Successfully retrieved the system attribute information.
00622  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
00623  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00624  * @retval ::NRF_ERROR_DATA_SIZE The system attribute information did not fit into the provided buffer.
00625  * @retval ::NRF_ERROR_NOT_FOUND No system attributes found.
00626  */ 
00627 SVCALL(SD_BLE_GATTS_SYS_ATTR_GET, uint32_t, sd_ble_gatts_sys_attr_get(uint16_t conn_handle, uint8_t *p_sys_attr_data, uint16_t *p_len, uint32_t flags)); 
00628 
00629 /** @} */
00630 
00631 #endif // BLE_GATTS_H__
00632 
00633 /**
00634   @}
00635 */