Bluetooth LE Profile API document
Bluetooth LE Profile API document Rev.1.00 [May 22, 2020]

Detailed Description

Functions

ble_status_t R_BLE_GATTS_Init (uint8_t cb_num)
 This function initializes the GATT Server and registers the number of the callbacks for GATT Server event. More...
 
ble_status_t R_BLE_GATTS_SetDbInst (st_ble_gatts_db_cfg_t *p_db_inst)
 This function sets GATT Database to host stack. More...
 
ble_status_t R_BLE_GATTS_RegisterCb (ble_gatts_app_cb_t cb, uint8_t priority)
 This function registers a callback for GATT Server event. More...
 
ble_status_t R_BLE_GATTS_DeregisterCb (ble_gatts_app_cb_t cb)
 This function deregisters the callback function for GATT Server event. More...
 
ble_status_t R_BLE_GATTS_Notification (uint16_t conn_hdl, st_ble_gatt_hdl_value_pair_t *p_ntf_data)
 This function sends a notification of an attribute's value. More...
 
ble_status_t R_BLE_GATTS_Indication (uint16_t conn_hdl, st_ble_gatt_hdl_value_pair_t *p_ind_data)
 This function sends a indication of an attribute's value. More...
 
ble_status_t R_BLE_GATTS_GetAttr (uint16_t conn_hdl, uint16_t attr_hdl, st_ble_gatt_value_t *p_value)
 This function gets a attribute value from the GATT Database. More...
 
ble_status_t R_BLE_GATTS_SetAttr (uint16_t conn_hdl, uint16_t attr_hdl, st_ble_gatt_value_t *p_value)
 This function sets an attribute value to the GATT Database. More...
 
ble_status_t R_BLE_GATTS_SendErrRsp (uint16_t error_code)
 This function sends an error response to a remote device. More...
 
ble_status_t R_BLE_GATTS_RspExMtu (uint16_t conn_hdl, uint16_t mtu)
 This function replies to a MTU Exchange Request from a remote device. More...
 
ble_status_t R_BLE_GATTS_SetPrepareQueue (st_ble_gatt_pre_queue_t *p_pre_queues, uint8_t queue_num)
 Register prepare queue and buffer in Host Stack. More...
 

Function Documentation

◆ R_BLE_GATTS_Init()

ble_status_t R_BLE_GATTS_Init ( uint8_t  cb_num)

This function initializes the GATT Server and registers the number of the callbacks for GATT Server event.

Specify the cb_num parameter to a value between 1 and BLE_GATTS_MAX_CB.
R_BLE_GATTS_RegisterCb() registers the callback.
The result of this API call is returned by a return value.

Parameters
[in]cb_numThe number of callbacks to be registered.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_ARG(0x0003)The cb_num parameter is out of range.

Events
none

Message Sequence Chart

◆ R_BLE_GATTS_SetDbInst()

ble_status_t R_BLE_GATTS_SetDbInst ( st_ble_gatts_db_cfg_t p_db_inst)

This function sets GATT Database to host stack.

The result of this API call is returned by a return value. GATT Database is described in GATT Database

Parameters
[in]p_db_instGATT Database to be set.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The reason for this error is as follows.
  • The db_inst parameter is specified as NULL.
  • The array in the db_inst is specified as NULL.

Events
none

◆ R_BLE_GATTS_RegisterCb()

ble_status_t R_BLE_GATTS_RegisterCb ( ble_gatts_app_cb_t  cb,
uint8_t  priority 
)

This function registers a callback for GATT Server event.

The number of the callback that may be registered by this function is the value specified by R_BLE_GATTS_Init().
The result of this API call is returned by a return value.

Parameters
[in]cbCallback function for GATT Server event.

[in]priorityThe priority of the callback function.
Valid range is 1 <= priority <= BLE_GATTS_MAX_CB.
A lower priority number means a higher priority level.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The cb parameter is specified as NULL.
BLE_ERR_INVALID_ARG(0x0003)The priority parameter is out of range.
BLE_ERR_CONTEXT_FULL(0x000B)Host stack has already registered the maximum number of callbacks.

Events
none

Message Sequence Chart

◆ R_BLE_GATTS_DeregisterCb()

ble_status_t R_BLE_GATTS_DeregisterCb ( ble_gatts_app_cb_t  cb)

This function deregisters the callback function for GATT Server event.

The result of this API call is returned by a return value.

Parameters
[in]cbThe callback function to be deregistered.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The cb parameter is specified as NULL.
BLE_ERR_NOT_FOUND(0x000D)The callback has not been registered.

Events
none

◆ R_BLE_GATTS_Notification()

ble_status_t R_BLE_GATTS_Notification ( uint16_t  conn_hdl,
st_ble_gatt_hdl_value_pair_t p_ntf_data 
)

This function sends a notification of an attribute's value.

The maximum length of the attribute value that can be sent with notification is MTU-3.
The result of this API call is returned by a return value.

Parameters
[in]conn_hdlConnection handle identifying the remote device to be sent the notification.

[in]p_ntf_dataThe attribute value to send.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_ntf_data parameter or the value field in the value field in the p_ntf_data parameter is NULL.
BLE_ERR_INVALID_ARG(0x0003)The value_len field in the value field in the p_ntf_data parameter is 0 or the attr_hdl field in the p_ntf_data parameters is 0.
BLE_ERR_INVALID_OPERATION(0x0009)This function was called while processing other request.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)Insufficient memory is needed to generate this function.
BLE_ERR_INVALID_HDL(0x000E)The remote device specified by conn_hdl was not found.

Events
none

Message Sequence Chart

◆ R_BLE_GATTS_Indication()

ble_status_t R_BLE_GATTS_Indication ( uint16_t  conn_hdl,
st_ble_gatt_hdl_value_pair_t p_ind_data 
)

This function sends a indication of an attribute's value.

The maximum length of the attribute value that can be sent with indication is MTU-3.
The result of this API call is returned by a return value.
The remote device that receives a indication sends a confirmation.
BLE_GATTS_EVENT_HDL_VAL_CNF event notifies the application layer that the confirmation has been received.

Parameters
[in]conn_hdlConnection handle identifying the remote device to be sent the indication.

[in]p_ind_dataThe attribute value to send.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_ind_data parameter or the value field in the value field in the p_ind_data parameter is NULL.
BLE_ERR_INVALID_ARG(0x0003)The value_len field in the value field in the p_ind_data parameter is 0 or the attr_hdl field in the p_ind_data parameters is 0.
BLE_ERR_INVALID_OPERATION(0x0009)This function was called while processing other request.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)Insufficient memory is needed to generate this function.
BLE_ERR_INVALID_HDL(0x000E)The remote device specified by conn_hdl was not found.

Events

Message Sequence Chart

◆ R_BLE_GATTS_GetAttr()

ble_status_t R_BLE_GATTS_GetAttr ( uint16_t  conn_hdl,
uint16_t  attr_hdl,
st_ble_gatt_value_t p_value 
)

This function gets a attribute value from the GATT Database.

The result of this API call is returned by a return value.

Parameters
[in]conn_hdlIf the attribute value that has information about the remote device is acquired, specify the remote device with the conn_hdl parameter.
When information about the remote device is not required, set the conn_hdl parameter to BLE_GAP_INVALID_CONN_HDL.

[in]attr_hdlThe attribute handle of the attribute value to be acquired.

[out]p_valueThe attribute value to be acquired.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_value parameter is specified as NULL.
BLE_ERR_INVALID_ARG(0x0003)The attr_hdl parameter is 0 or larger than the last attribute handle of GATT Database.
BLE_ERR_INVALID_STATE(0x0008)The attribute is not in a state to be read.
BLE_ERR_INVALID_OPERATION(0x0009)The attribute cannot be read.
BLE_ERR_NOT_FOUND(0x000D)The attribute specified by the attr_hdl parameter is not belonging to any services or characteristics.
BLE_ERR_INVALID_HDL(0x000E)The remote device specified by the conn_hdl parameter was not found.

Events
none

◆ R_BLE_GATTS_SetAttr()

ble_status_t R_BLE_GATTS_SetAttr ( uint16_t  conn_hdl,
uint16_t  attr_hdl,
st_ble_gatt_value_t p_value 
)

This function sets an attribute value to the GATT Database.

The result of this API call is returned by a return value.

Parameters
[in]conn_hdlIf the attribute value that has information about the remote device is acquired, specify the remote device with the conn_hdl parameter.
When information about the remote device is not required, set the conn_hdl parameter to BLE_GAP_INVALID_CONN_HDL.

[in]attr_hdlThe attribute handle of the attribute value to be set.

[in]p_valueThe attribute value to be set.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_value parameter is specified as NULL.
BLE_ERR_INVALID_DATA(0x0002)The write size is larger than the length of the attribute value.
BLE_ERR_INVALID_ARG(0x0003)The attr_hdl parameter is 0 or larger than the last attribute handle of GATT Database.
BLE_ERR_INVALID_STATE(0x0008)The attribute is not in a state to be written.
BLE_ERR_INVALID_OPERATION(0x0009)The attribute cannot be written.
BLE_ERR_NOT_FOUND(0x000D)The attribute specified by the attr_hdl parameter is not belonging to any services or characteristics.
BLE_ERR_INVALID_HDL(0x000E)The remote device specified by the conn_hdl parameter was not found.

Events
none

◆ R_BLE_GATTS_SendErrRsp()

ble_status_t R_BLE_GATTS_SendErrRsp ( uint16_t  error_code)

This function sends an error response to a remote device.

The result is returned from the API.
The error code specified in the callback is notified as Error Response to the remote device.
The result of this API call is returned by a return value.

Parameters
[in]error_codeThe error codes to be notified the client.
It is a bitwise OR of GATT Error Group ID : 0x3000 and the following error codes defined in Core Spec and Core Spec Supplement.
Error Code description
BLE_ERR_GATT_INVALID_HANDLE(0x3001) Invalid attribute handle
BLE_ERR_GATT_READ_NOT_PERMITTED(0x3002) The attribute cannot be read.
BLE_ERR_GATT_WRITE_NOT_PERMITTED(0x3003) The attribute cannot be written.
BLE_ERR_GATT_INVALID_PDU(0x3004) Invalid PDU.
BLE_ERR_GATT_INSUFFICIENT_AUTHENTICATION(0x3005) The authentication to access the attribute is insufficient.
BLE_ERR_GATT_REQUEST_NOT_SUPPORTED(0x3006) The request is not supported.
BLE_ERR_GATT_INVALID_OFFSET(0x3007) The specified offset is larger than the length of the attribute value.
BLE_ERR_GATT_INSUFFICIENT_AUTHORIZATION(0x3008) Authorization is required to access the attribute.
BLE_ERR_GATT_PREPARE_WRITE_QUEUE_FULL(0x3009) The Write Queue in the GATT Server is full.
BLE_ERR_GATT_ATTRIBUTE_NOT_FOUND(0x300A) The specified attribute is not found.
BLE_ERR_GATT_ATTRIBUTE_NOT_LONG(0x300B) The attribute cannot be read by Read Blob Request.
BLE_ERR_GATT_INSUFFICIENT_ENC_KEY_SIZE(0x300C) The Encryption Key Size is insufficient.
BLE_ERR_GATT_INVALID_ATTRIBUTE_LEN(0x300D) The length of the specified attribute is invalid.
BLE_ERR_GATT_UNLIKELY_ERROR(0x300E) Because an error has occurred, the process cannot be advanced.
BLE_ERR_GATT_INSUFFICIENT_ENCRYPTION(0x300F) Encryption is required to access the attribute.
BLE_ERR_GATT_UNSUPPORTED_GROUP_TYPE(0x3010) The type of the specified attribute is not supported.
BLE_ERR_GATT_INSUFFICIENT_RESOURCES(0x3011) The resource to complete the request is insufficient.
0x3080 - 0x309F Application Error. The upper layer defines the error codes.
0x30E0 - 0x30FF The error code defined in Common Profile and Service Error Core Specification Supplement(CSS).
CSS ver.7 defines the error codes from 0x30FC to 0x30FF.
BLE_ERR_GATT_WRITE_REQ_REJECTED(0x30FC) The Write Request has not been completed due to the reason other than Permission.
BLE_ERR_GATT_CCCD_IMPROPERLY_CFG(0x30FD) The CCCD is set to be invalid.
BLE_ERR_GATT_PROC_ALREADY_IN_PROGRESS(0x30FE) The request is now in progress.
BLE_ERR_GATT_OUT_OF_RANGE(0x30FF) The attribute value is out of range.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_ARG(0x0003)The Group ID of the error_code parameter is not 0x3000, or it is 0x3000.
BLE_ERR_INVALID_OPERATION(0x0009)While processing other error response,this function was called.

Events
none

Message Sequence Chart

◆ R_BLE_GATTS_RspExMtu()

ble_status_t R_BLE_GATTS_RspExMtu ( uint16_t  conn_hdl,
uint16_t  mtu 
)

This function replies to a MTU Exchange Request from a remote device.

BLE_GATTS_EVENT_EX_MTU_REQ event notifies the application layer that a MTU Exchange Request has been received.
Therefore when the callback has received the event, call this function.
The new MTU is the minimum of the mtu parameter specified by this function and the mtu field in BLE_GATTS_EVENT_EX_MTU_REQ event.
Default MTU size is 23 bytes.
The result of this API call is returned by a return value.

Parameters
[in]conn_hdlConnection handle identifying the remote device to be sent MTU Exchange Response.

[in]mtuThe maximum size(in bytes) of the GATT PDU that GATT Server can receive.
Valid range is 23 <= mtu <= 247.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_ARG(0x0003)The mtu parameter is out of range.
BLE_ERR_INVALID_OPERATION(0x0009)This function was called while processing other request.
BLE_ERR_MEM_ALLOC_FAILED(0x000C)Insufficient memory is needed to generate this function.
BLE_ERR_INVALID_HDL(0x000E)The remote device specified by conn_hdl was not found.

Events
none

Message Sequence Chart

◆ R_BLE_GATTS_SetPrepareQueue()

ble_status_t R_BLE_GATTS_SetPrepareQueue ( st_ble_gatt_pre_queue_t p_pre_queues,
uint8_t  queue_num 
)

Register prepare queue and buffer in Host Stack.

This function registers the prepare queue and buffer for long chracteristic write and reliable writes. The result of this API call is returned by a return value.

Parameters
[in]p_pre_queuesThe prepare write queues to be registered.

[in]queue_numThe number of prepare write queues to be registered.
Return values
BLE_SUCCESS(0x0000)Success
BLE_ERR_INVALID_PTR(0x0001)The p_pre_queue parameter is specified as NULL.

Events
none