S132 SoftDevice v5.0.0-1.alpha
Functions

Functions

uint32_t sd_ble_gatts_service_add (uint8_t type, ble_uuid_t const *p_uuid, uint16_t *p_handle)
 Add a service declaration to the Attribute Table. More...
 
uint32_t sd_ble_gatts_include_add (uint16_t service_handle, uint16_t inc_srvc_handle, uint16_t *p_include_handle)
 Add an include declaration to the Attribute Table. More...
 
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)
 Add a characteristic declaration, a characteristic value declaration and optional characteristic descriptor declarations to the Attribute Table. More...
 
uint32_t sd_ble_gatts_descriptor_add (uint16_t char_handle, ble_gatts_attr_t const *p_attr, uint16_t *p_handle)
 Add a descriptor to the Attribute Table. More...
 
uint32_t sd_ble_gatts_value_set (uint16_t conn_handle, uint16_t handle, ble_gatts_value_t *p_value)
 Set the value of a given attribute. More...
 
uint32_t sd_ble_gatts_value_get (uint16_t conn_handle, uint16_t handle, ble_gatts_value_t *p_value)
 Get the value of a given attribute. More...
 
uint32_t sd_ble_gatts_hvx (uint16_t conn_handle, ble_gatts_hvx_params_t const *p_hvx_params)
 Notify or Indicate an attribute value. More...
 
uint32_t sd_ble_gatts_service_changed (uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle)
 Indicate the Service Changed attribute value. More...
 
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)
 Respond to a Read/Write authorization request. More...
 
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)
 Update persistent system attribute information. More...
 
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)
 Retrieve persistent system attribute information from the stack. More...
 
uint32_t sd_ble_gatts_initial_user_handle_get (uint16_t *p_handle)
 Retrieve the first valid user attribute handle. More...
 
uint32_t sd_ble_gatts_attr_get (uint16_t handle, ble_uuid_t *p_uuid, ble_gatts_attr_md_t *p_md)
 Retrieve the attribute UUID and/or metadata. More...
 
uint32_t sd_ble_gatts_exchange_mtu_reply (uint16_t conn_handle, uint16_t server_rx_mtu)
 Reply to an ATT_MTU exchange request by sending an Exchange MTU Response to the client. More...
 

Detailed Description

Function Documentation

uint32_t sd_ble_gatts_attr_get ( uint16_t  handle,
ble_uuid_t p_uuid,
ble_gatts_attr_md_t p_md 
)

Retrieve the attribute UUID and/or metadata.

Parameters
[in]handleAttribute handle
[out]p_uuidUUID of the attribute. Use NULL to omit this field.
[out]p_mdMetadata of the attribute. Use NULL to omit this field.
Return values
NRF_SUCCESSSuccessfully retrieved the attribute metadata,
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid parameters supplied. Returned when both p_uuid and p_md are NULL.
NRF_ERROR_NOT_FOUNDAttribute was not found.
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 
)

Add a characteristic declaration, a characteristic value declaration and optional characteristic descriptor declarations to the Attribute Table.

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).
Several restrictions apply to the parameters, such as matching permissions between the user description descriptor and the writeable auxiliaries bits, readable (no security) and writeable (selectable) CCCDs and SCCDs and valid presentation format values.
If no metadata is provided for the optional descriptors, their permissions will be derived from the characteristic permissions.
Relevant Message Sequence Charts
GATTS ATT Table Population
Parameters
[in]service_handleHandle of the service where the characteristic is to be placed, if BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
[in]p_char_mdCharacteristic metadata.
[in]p_attr_char_valuePointer to the attribute structure corresponding to the characteristic value.
[out]p_handlesPointer to the structure where the assigned handles will be stored.
Return values
NRF_SUCCESSSuccessfully added a characteristic.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied, service handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints.
NRF_ERROR_INVALID_STATEInvalid state to perform operation, a service context is required.
NRF_ERROR_FORBIDDENForbidden value supplied, certain UUIDs are reserved for the stack.
NRF_ERROR_NO_MEMNot enough memory to complete operation.
NRF_ERROR_DATA_SIZEInvalid data size(s) supplied, attribute lengths are restricted by Maximum attribute lengths.
uint32_t sd_ble_gatts_descriptor_add ( uint16_t  char_handle,
ble_gatts_attr_t const *  p_attr,
uint16_t *  p_handle 
)

Add a descriptor to the Attribute Table.

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).
Relevant Message Sequence Charts
GATTS ATT Table Population
Parameters
[in]char_handleHandle of the characteristic where the descriptor is to be placed, if BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
[in]p_attrPointer to the attribute structure.
[out]p_handlePointer to a 16-bit word where the assigned handle will be stored.
Return values
NRF_SUCCESSSuccessfully added a descriptor.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied, characteristic handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints.
NRF_ERROR_INVALID_STATEInvalid state to perform operation, a characteristic context is required.
NRF_ERROR_FORBIDDENForbidden value supplied, certain UUIDs are reserved for the stack.
NRF_ERROR_NO_MEMNot enough memory to complete operation.
NRF_ERROR_DATA_SIZEInvalid data size(s) supplied, attribute lengths are restricted by Maximum attribute lengths.
uint32_t sd_ble_gatts_exchange_mtu_reply ( uint16_t  conn_handle,
uint16_t  server_rx_mtu 
)

Reply to an ATT_MTU exchange request by sending an Exchange MTU Response to the client.

This function is only used to reply to a BLE_GATTS_EVT_EXCHANGE_MTU_REQUEST event.

The SoftDevice sets ATT_MTU to the minimum of:

However, the SoftDevice never sets ATT_MTU lower than BLE_GATT_MTU_SIZE_DEFAULT.

Events generated
BLE_EVT_DATA_LENGTH_CHANGEDGenerated if a data length update procedure is performed after the ATT_MTU exchange.
Relevant Message Sequence Charts
GATTS ATT_MTU Exchange
Parameters
[in]conn_handleThe connection handle identifying the connection to perform this procedure on.
[in]server_rx_mtuServer RX MTU size.
Return values
NRF_SUCCESSSuccessfully sent response to the client.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEInvalid Connection State or no ATT_MTU exchange request pending.
NRF_ERROR_INVALID_PARAMInvalid Server RX MTU size supplied.
NRF_ERROR_BUSYThe stack is busy. Retry at later time.
uint32_t sd_ble_gatts_hvx ( uint16_t  conn_handle,
ble_gatts_hvx_params_t const *  p_hvx_params 
)

Notify or Indicate an attribute value.

This function checks for the relevant Client Characteristic Configuration descriptor value to verify that the relevant operation (notification or indication) has been enabled by the client. It is also able to update the attribute value before issuing the PDU, so that the application can atomically perform a value update and a server initiated transaction with a single API call. If the application chooses to indicate an attribute value, a BLE_GATTS_EVT_HVC event will be issued as soon as the confirmation arrives from the peer.

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. The Attribute Table has been updated if one of the following error codes is returned: NRF_ERROR_INVALID_STATE, NRF_ERROR_BUSY, NRF_ERROR_FORBIDDEN, BLE_ERROR_GATTS_SYS_ATTR_MISSING and BLE_ERROR_NO_TX_PACKETS. The caller can check whether the value has been updated by looking at the contents of *(p_hvx_params->p_len).
It is important to note that a notification will consume an application buffer, and will therefore generate a BLE_EVT_TX_COMPLETE event when the packet has been transmitted. An indication on the other hand will use the standard server internal buffer and thus will only generate a BLE_GATTS_EVT_HVC event as soon as the confirmation has been received from the peer. Please see the documentation of sd_ble_tx_packet_count_get for more details.
Events generated
BLE_EVT_TX_COMPLETETransmission complete.
BLE_GATTS_EVT_HVCConfirmation received from peer.
Relevant Message Sequence Charts
GATTS Handle Value Indication or Notification with System Attributes Missing
GATTS Handle Value Notification
GATTS Handle Value Indication
GATTS Handle Value Indication or Notification disabled
App TX Packet Management
Parameters
[in]conn_handleConnection handle.
[in]p_hvx_paramsPointer to an HVx parameters structure. If the p_data member contains a non-NULL pointer the attribute value will be updated with the contents pointed by it before sending the notification or indication.
Return values
NRF_SUCCESSSuccessfully queued a notification or indication for transmission, and optionally updated the attribute value.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_STATEOne or more of the following is true:
  • Invalid Connection State
  • Notifications and/or indications not enabled in the CCCD
  • An ATT_MTU exchange is ongoing
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied.
BLE_ERROR_INVALID_ATTR_HANDLEInvalid attribute handle(s) supplied. Only attributes added directly by the application are available to notify and indicate.
BLE_ERROR_GATTS_INVALID_ATTR_TYPEInvalid attribute type(s) supplied, only characteristic values may be notified and indicated.
NRF_ERROR_NOT_FOUNDAttribute not found.
NRF_ERROR_FORBIDDENThe connection's current security level is lower than the one required by the write permissions of the CCCD associated with this characteristic.
NRF_ERROR_DATA_SIZEInvalid data size(s) supplied.
NRF_ERROR_BUSYProcedure already in progress.
BLE_ERROR_GATTS_SYS_ATTR_MISSINGSystem attributes missing, use sd_ble_gatts_sys_attr_set to set them to a known value.
BLE_ERROR_NO_TX_PACKETSNo available application packets for this connection, applies only to notifications.
uint32_t sd_ble_gatts_include_add ( uint16_t  service_handle,
uint16_t  inc_srvc_handle,
uint16_t *  p_include_handle 
)

Add an include declaration to the Attribute Table.

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).
The included service must already be present in the Attribute Table prior to this call.
Relevant Message Sequence Charts
GATTS ATT Table Population
Parameters
[in]service_handleHandle of the service where the included service is to be placed, if BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
[in]inc_srvc_handleHandle of the included service.
[out]p_include_handlePointer to a 16-bit word where the assigned handle will be stored.
Return values
NRF_SUCCESSSuccessfully added an include declaration.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied, handle values need to match previously added services.
NRF_ERROR_INVALID_STATEInvalid state to perform operation.
NRF_ERROR_NOT_SUPPORTEDFeature is not supported, service_handle must be that of the last added service.
NRF_ERROR_FORBIDDENForbidden value supplied, self inclusions are not allowed.
NRF_ERROR_NO_MEMNot enough memory to complete operation.
NRF_ERROR_NOT_FOUNDAttribute not found.
uint32_t sd_ble_gatts_initial_user_handle_get ( uint16_t *  p_handle)

Retrieve the first valid user attribute handle.

Parameters
[out]p_handlePointer to an integer where the handle will be stored.
Return values
NRF_SUCCESSSuccessfully retrieved the handle.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
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 
)

Respond to a Read/Write authorization request.

Note
This call should only be used as a response to a BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST event issued to the application.
Relevant Message Sequence Charts
GATTS Queued Writes: App handled, one or more attributes require authorization
GATTS Queued Writes: Stack handled, one or more attributes require authorization
GATTS Queued Writes: App handled, no attributes require authorization
GATTS Read Request with Authorization
GATTS Write Request with Authorization
GATTS Queued Writes: Prepare Queue Full
GATTS Queued Writes: App handled, peer cancels operation
Parameters
[in]conn_handleConnection handle.
[in]p_rw_authorize_reply_paramsPointer to a structure with the attribute provided by the application.
Note
ble_gatts_authorize_params_t::p_data is ignored when this function is used to respond to a BLE_GATTS_AUTHORIZE_TYPE_READ event if ble_gatts_authorize_params_t::update is set to 0.
Return values
NRF_SUCCESSSuccessfully queued a response to the peer, and in the case of a write operation, Attribute Table updated.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_STATEInvalid Connection State or no authorization request pending.
NRF_ERROR_INVALID_PARAMAuthorization op invalid, handle supplied does not match requested handle, or invalid data to be written provided by the application.
NRF_ERROR_BUSYThe stack is busy. Retry at later time.
uint32_t sd_ble_gatts_service_add ( uint8_t  type,
ble_uuid_t const *  p_uuid,
uint16_t *  p_handle 
)

Add a service declaration to the Attribute Table.

Note
Secondary Services are only relevant in the context of the entity that references them, it is therefore forbidden to add a secondary service declaration that is not referenced by another service later in the Attribute Table.
Relevant Message Sequence Charts
GATTS ATT Table Population
Parameters
[in]typeToggles between primary and secondary services, see GATT Server Service Types.
[in]p_uuidPointer to service UUID.
[out]p_handlePointer to a 16-bit word where the assigned handle will be stored.
Return values
NRF_SUCCESSSuccessfully added a service declaration.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied, Vendor Specific UUIDs need to be present in the table.
NRF_ERROR_FORBIDDENForbidden value supplied, certain UUIDs are reserved for the stack.
NRF_ERROR_NO_MEMNot enough memory to complete operation.
uint32_t sd_ble_gatts_service_changed ( uint16_t  conn_handle,
uint16_t  start_handle,
uint16_t  end_handle 
)

Indicate the Service Changed attribute value.

This call will send a Handle Value Indication to one or more peers connected to inform them that the Attribute Table layout has changed. As soon as the peer has confirmed the indication, a BLE_GATTS_EVT_SC_CONFIRM event will be issued.

Note
Some of the restrictions and limitations that apply to sd_ble_gatts_hvx also apply here.
Events generated
BLE_GATTS_EVT_SC_CONFIRMConfirmation of attribute table change received from peer.
Relevant Message Sequence Charts
GATTS Service Changed
Parameters
[in]conn_handleConnection handle.
[in]start_handleStart of affected attribute handle range.
[in]end_handleEnd of affected attribute handle range.
Return values
NRF_SUCCESSSuccessfully queued the Service Changed indication for transmission.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_NOT_SUPPORTEDService Changed not enabled at initialization. See sd_ble_enable and ble_gatts_enable_params_t.
NRF_ERROR_INVALID_STATEOne or more of the following is true:
  • Invalid Connection State
  • Notifications and/or indications not enabled in the CCCD
  • An ATT_MTU exchange is ongoing
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied.
BLE_ERROR_INVALID_ATTR_HANDLEInvalid attribute handle(s) supplied, handles must be in the range populated by the application.
NRF_ERROR_BUSYProcedure already in progress.
BLE_ERROR_GATTS_SYS_ATTR_MISSINGSystem attributes missing, use sd_ble_gatts_sys_attr_set to set them to a known value.
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 
)

Retrieve persistent system attribute information from the stack.

This call is used to retrieve information about values to be stored perisistently by the application during the lifetime of a connection or after it has been terminated. When a new connection is established with the same bonded device, the system attribute information retrieved with this function should be restored using using sd_ble_gatts_sys_attr_set. If retrieved after disconnection, the data should be read before a new connection established. The connection handle for the previous, now disconnected, connection will remain valid until a new one is created to allow this API call to refer to it. Connection handles belonging to active connections can be used as well, but care should be taken since the system attributes may be written to at any time by the peer during a connection's lifetime.

Note
When the BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS is used with this function, only the system attributes included in system services will be returned.
When the BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS is used with this function, only the system attributes included in user services will be returned.
Relevant Message Sequence Charts
GATTS System Attributes Handling: Bonded Peer
Parameters
[in]conn_handleConnection handle of the recently terminated connection.
[out]p_sys_attr_dataPointer to a buffer where updated information about system attributes will be filled in. The format of the data is described in User memory layout for System Attributes. NULL can be provided to obtain the length of the data.
[in,out]p_lenSize of application buffer if p_sys_attr_data is not NULL. Unconditially updated to actual length of system attribute data.
[in]flagsOptional additional flags, see System Attribute Flags
Return values
NRF_SUCCESSSuccessfully retrieved the system attribute information.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid flags supplied.
NRF_ERROR_DATA_SIZEThe system attribute information did not fit into the provided buffer.
NRF_ERROR_NOT_FOUNDNo system attributes found.
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 
)

Update persistent system attribute information.

Supply information about persistent system attributes to the stack, previously obtained using sd_ble_gatts_sys_attr_get. This call is only allowed for active connections, and is usually made immediately after a connection is established with an known bonded device, often as a response to a BLE_GATTS_EVT_SYS_ATTR_MISSING.

p_sysattrs may point directly to the application's stored copy of the system attributes obtained using sd_ble_gatts_sys_attr_get. If the pointer is NULL, the system attribute info is initialized, assuming that the application does not have any previously saved system attribute data for this device.

Note
The state of persistent system attributes is reset upon connection establishment and then remembered for its duration.
If this call returns with an error code different from NRF_SUCCESS, the storage of persistent system attributes may have been completed only partially. 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 reset the SoftDevice to return to a known state.
When the BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS is used with this function, only the system attributes included in system services will be modified.
When the BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS is used with this function, only the system attributes included in user services will be modified.
Relevant Message Sequence Charts
GATTS Handle Value Indication or Notification with System Attributes Missing
GATTS System Attributes Handling: Unknown Peer
GATTS System Attributes Handling: Bonded Peer
Parameters
[in]conn_handleConnection handle.
[in]p_sys_attr_dataPointer to a saved copy of system attributes supplied to the stack, or NULL.
[in]lenSize of data pointed by p_sys_attr_data, in octets.
[in]flagsOptional additional flags, see System Attribute Flags
Return values
NRF_SUCCESSSuccessfully set the system attribute information.
BLE_ERROR_INVALID_CONN_HANDLEInvalid Connection Handle.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_STATEInvalid Connection State.
NRF_ERROR_INVALID_PARAMInvalid flags supplied.
NRF_ERROR_INVALID_DATAInvalid data supplied, the data should be exactly the same as retrieved with sd_ble_gatts_sys_attr_get.
NRF_ERROR_NO_MEMNot enough memory to complete operation.
NRF_ERROR_BUSYThe stack is busy. Retry at later time.
uint32_t sd_ble_gatts_value_get ( uint16_t  conn_handle,
uint16_t  handle,
ble_gatts_value_t p_value 
)

Get the value of a given attribute.

Note
If the attribute value is longer than the size of the supplied buffer, p_len will return the total attribute value length (excluding offset), and not the number of bytes actually returned in p_data. The application may use this information to allocate a suitable buffer size.
When retrieving system attribute values with this function, the connection handle may refer to an already disconnected connection. Refer to the documentation of sd_ble_gatts_sys_attr_get for further information.
Parameters
[in]conn_handleConnection handle. Ignored if the value does not belong to a system attribute.
[in]handleAttribute handle.
[in,out]p_valueAttribute value information.
Return values
NRF_SUCCESSSuccessfully retrieved the value of the attribute.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_NOT_FOUNDAttribute not found.
NRF_ERROR_INVALID_PARAMInvalid attribute offset supplied.
BLE_ERROR_INVALID_CONN_HANDLEInvalid connection handle supplied on a system attribute.
BLE_ERROR_GATTS_SYS_ATTR_MISSINGSystem attributes missing, use sd_ble_gatts_sys_attr_set to set them to a known value.
uint32_t sd_ble_gatts_value_set ( uint16_t  conn_handle,
uint16_t  handle,
ble_gatts_value_t p_value 
)

Set the value of a given attribute.

Note
Values other than system attributes can be set at any time, regardless of wheter any active connections exist.
Relevant Message Sequence Charts
GATTS Queued Writes: Prepare Queue Full
GATTS Queued Writes: App handled, no attributes require authorization
Parameters
[in]conn_handleConnection handle. Ignored if the value does not belong to a system attribute.
[in]handleAttribute handle.
[in,out]p_valueAttribute value information.
Return values
NRF_SUCCESSSuccessfully set the value of the attribute.
NRF_ERROR_INVALID_ADDRInvalid pointer supplied.
NRF_ERROR_INVALID_PARAMInvalid parameter(s) supplied.
NRF_ERROR_NOT_FOUNDAttribute not found.
NRF_ERROR_FORBIDDENForbidden handle supplied, certain attributes are not modifiable by the application.
NRF_ERROR_DATA_SIZEInvalid data size(s) supplied, attribute lengths are restricted by Maximum attribute lengths.
BLE_ERROR_INVALID_CONN_HANDLEInvalid connection handle supplied on a system attribute.

Documentation feedback | Developer Zone | Subscribe | Updated