General Description

APIs unique to designs configured as a GATT Server role.

A letter 'S' is appended to the API name: Cy_BLE_GATTS_

Functions
cy_en_ble_gatt_err_code_t	Cy_BLE_GATTS_WriteAttributeValuePeer (cy_stc_ble_conn_handle_t connHandle, const cy_stc_ble_gatt_handle_value_pair_t handleValuePair)
	Wrapper API for Cy_BLE_GATTS_WriteAttributeValue() to trigger a peer initiated attribute value write operation to GATT database. More...

cy_en_ble_gatt_err_code_t	Cy_BLE_GATTS_WriteAttributeValueLocal (const cy_stc_ble_gatt_handle_value_pair_t *handleValuePair)
	Wrapper API for Cy_BLE_GATTS_WriteAttributeValue to trigger a locally initiated attribute value write operation to GATT database. More...

cy_en_ble_gatt_err_code_t	Cy_BLE_GATTS_ReadAttributeValueLocal (cy_stc_ble_conn_handle_t connHandle, const cy_stc_ble_gatt_handle_value_pair_t handleValuePair)
	Wrapper API for Cy_BLE_GATTS_ReadAttributeValue() to trigger a local initiated attribute value read operation to GATT database. More...

cy_en_ble_gatt_err_code_t	Cy_BLE_GATTS_ReadAttributeValuePeer (cy_stc_ble_conn_handle_t connHandle, const cy_stc_ble_gatt_handle_value_pair_t handleValuePair)
	Wrapper API for Cy_BLE_GATTS_ReadAttributeValue() to trigger a peer initiated attribute value read operation to GATT database. More...

cy_en_ble_api_result_t	Cy_BLE_GATTS_SendNotification (cy_stc_ble_conn_handle_t connHandle, cy_stc_ble_gatt_handle_value_pair_t handleValuePair)
	Wrapper API to write the attribute value to local GATT database and send the updated value to the peer device using notification procedure. More...

cy_en_ble_api_result_t	Cy_BLE_GATTS_SendIndication (cy_stc_ble_conn_handle_t connHandle, cy_stc_ble_gatt_handle_value_pair_t handleValuePair)
	Wrapper API to write the attribute value to local GATT database and send the updated value to the peer device using indication procedure. More...

bool	Cy_BLE_GATTS_IsNotificationEnabled (cy_stc_ble_conn_handle_t *connHandle, cy_ble_gatt_db_attr_handle_t attrHandle)
	Wrapper API to read CCCD attribute value from the local GATT database and check if the notification is enabled by the peer device. More...

bool	Cy_BLE_GATTS_IsIndicationEnabled (cy_stc_ble_conn_handle_t *connHandle, cy_ble_gatt_db_attr_handle_t attrHandle)
	Wrapper API to read CCCD attribute value from the local GATT database and check if the indication is enabled by the peer device. More...

cy_en_ble_api_result_t	Cy_BLE_GATTS_SendErrorRsp (cy_stc_ble_conn_handle_t connHandle, const cy_stc_ble_gatt_err_info_t errRspParam)
	Replacement for Cy_BLE_GATTS_ErrorRsp() API. More...

cy_en_ble_gatt_err_code_t	Cy_BLE_GATTS_EnableAttribute (cy_stc_ble_gatts_db_attr_enable_info_t *param)
	This function is used by GATT Server application to enable the attribute entry for a service or characteristic logical group in the GATT database registered in the BLE Stack. More...

cy_en_ble_gatt_err_code_t	Cy_BLE_GATTS_DisableAttribute (cy_stc_ble_gatts_db_attr_disable_info_t *param)
	This function is used by GATT Server application to disable the attribute entry for service or characteristic logical group in the GATT database registered in the BLE Stack. More...

cy_en_ble_gatt_err_code_t	Cy_BLE_GATTS_DbAuthorize (cy_stc_ble_gatts_db_authorize_info_t *param)
	This function sets or clears authorization permission for the GATT database. More...

cy_en_ble_api_result_t	Cy_BLE_GATTS_WriteRsp (cy_stc_ble_conn_handle_t connHandle)
	This function is used by GATT Server application to send a Write Response to a peer GATT Client. More...

Function Documentation

◆ Cy_BLE_GATTS_WriteAttributeValuePeer()

cy_en_ble_gatt_err_code_t Cy_BLE_GATTS_WriteAttributeValuePeer	(	cy_stc_ble_conn_handle_t *	connHandle,
		const cy_stc_ble_gatt_handle_value_pair_t *	handleValuePair
	)

Wrapper API for Cy_BLE_GATTS_WriteAttributeValue() to trigger a peer initiated attribute value write operation to GATT database.

This function is used to write to the value field of the specified attribute in the GATT database of a GATT Server by a peer device. If the attribute is CCCD, the value is stored in specific CCCD storages. Writing a CCCD value must be executed in the connected state. This is a blocking function. No event is generated on calling this function.

If a peer device connected to the GATT Server initiates a Write operation, this function is executed on the GATT Server. During such a call, the function checks for the attribute permissions (flags) before executing the Write operation by calling.

Parameters

connHandle	The pointer to the connection handle.
handleValuePair	The pointer to the cy_stc_ble_gatt_handle_value_pair_t structure.

Returns: cy_en_ble_gatt_err_code_t : The return value indicates whether the function succeeded or failed. The following are possible error codes.

Errors codes	Description
CY_BLE_GATT_ERR_NONE	On successful operation.
CY_BLE_GATT_ERR_INVALID_HANDLE	handleValuePair.attrHandle is not valid.
CY_BLE_GATT_ERR_WRITE_NOT_PERMITTED	The write operation is not permitted on this attribute (Peer Initiated).
CY_BLE_GATT_ERR_UNLIKELY_ERROR	Invalid arguments passed.
CY_BLE_GATT_ERR_INSUFFICIENT_ENCRYPTION	The link is not encrypted (Peer Initiated).
CY_BLE_GATT_ERR_INSUFFICIENT_ENC_KEY_SIZE	The link is encrypted with a insufficient key size (Peer Initiated).
CY_BLE_GATT_ERR_INSUFFICIENT_AUTHENTICATION	The link is un-authenticated (Peer Initiated).
CY_BLE_GATT_ERR_INSUFFICIENT_AUTHORIZATION	The peer client is not authorized (Peer Initiated).
CY_BLE_GATT_ERR_INVALID_ATTRIBUTE_LEN	handleValuePair.value.len is invalid.

◆ Cy_BLE_GATTS_WriteAttributeValueLocal()

cy_en_ble_gatt_err_code_t Cy_BLE_GATTS_WriteAttributeValueLocal ( const cy_stc_ble_gatt_handle_value_pair_t * handleValuePair )

Wrapper API for Cy_BLE_GATTS_WriteAttributeValue to trigger a locally initiated attribute value write operation to GATT database.

This function is used to write to the value field of the specified attribute in the GATT database of a GATT Server.

Note: this function doesn't write CCCD attribute value.

This is a blocking function. No event is generated on calling this function.

Parameters

handleValuePair The pointer to the cy_stc_ble_gatt_handle_value_pair_t structure.

Returns: cy_en_ble_gatt_err_code_t : The return value indicates whether the function succeeded or failed. The following are possible error codes.

Errors codes	Description
CY_BLE_GATT_ERR_NONE	On successful operation.
CY_BLE_GATT_ERR_INVALID_HANDLE	handleValuePair.attrHandle is not valid.
CY_BLE_GATT_ERR_UNLIKELY_ERROR	Invalid arguments passed.
CY_BLE_GATT_ERR_INVALID_ATTRIBUTE_LEN	handleValuePair.value.len is invalid.

◆ Cy_BLE_GATTS_ReadAttributeValueLocal()

cy_en_ble_gatt_err_code_t Cy_BLE_GATTS_ReadAttributeValueLocal	(	cy_stc_ble_conn_handle_t *	connHandle,
		const cy_stc_ble_gatt_handle_value_pair_t *	handleValuePair
	)

Wrapper API for Cy_BLE_GATTS_ReadAttributeValue() to trigger a local initiated attribute value read operation to GATT database.

This function is used to read the value field of the specified attribute from the GATT database in a GATT Server. If the attribute is CCCD, the value is restored from specific CCCD storages. Reading a CCCD value must be executed in the connected state. This is a blocking function. No event is generated on calling this function.

Parameters

connHandle	The pointer to the connection handle. This parameter is required only for the Read CCCD attribute. If you read a non-CCCD attribute, the connection handle can be NULL.
handleValuePair	The pointer to the cy_stc_ble_gatt_handle_value_pair_t structure.

Returns: cy_en_ble_gatt_err_code_t : The return value indicates whether the function succeeded or failed. The following are possible error codes.

Error Codes	Description
CY_BLE_GATT_ERR_NONE	On successful operation
CY_BLE_GATT_ERR_INVALID_HANDLE	handleValuePair.attrHandle is not valid
CY_BLE_GATT_ERR_UNLIKELY_ERROR	Invalid arguments passed

◆ Cy_BLE_GATTS_ReadAttributeValuePeer()

cy_en_ble_gatt_err_code_t Cy_BLE_GATTS_ReadAttributeValuePeer	(	cy_stc_ble_conn_handle_t *	connHandle,
		const cy_stc_ble_gatt_handle_value_pair_t *	handleValuePair
	)

Wrapper API for Cy_BLE_GATTS_ReadAttributeValue() to trigger a peer initiated attribute value read operation to GATT database.

This function is used to read the value field of the specified attribute from the GATT database in a GATT Server by a peer device. If the attribute is CCCD, the value is restored from specific CCCD storages. Reading a CCCD value must be executed in the connected state. This is a blocking function. No event is generated on calling this function.

If a peer initiates a call to this function, the function checks for changed attribute permissions before performing this operation.

Parameters

connHandle	The pointer to the connection handle.
handleValuePair	The pointer to the cy_stc_ble_gatt_handle_value_pair_t structure.

Returns: cy_en_ble_gatt_err_code_t : The return value indicates whether the function succeeded or failed. The following are possible error codes.

Errors codes	Description
CY_BLE_GATT_ERR_NONE	On successful operation.
CY_BLE_GATT_ERR_INVALID_HANDLE	handleValuePair.attrHandle is not valid.
CY_BLE_GATT_ERR_READ_NOT_PERMITTED	The Read operation is not permitted on this attribute (Peer Initiated).
CY_BLE_GATT_ERR_UNLIKELY_ERROR	Invalid arguments passed.
CY_BLE_GATT_ERR_INSUFFICIENT_ENCRYPTION	The link is not encrypted (Peer Initiated).
CY_BLE_GATT_ERR_INSUFFICIENT_ENC_KEY_SIZE	The link is encrypted with an insufficient key size (Peer Initiated).
CY_BLE_GATT_ERR_INSUFFICIENT_AUTHENTICATION	The link is un-authenticated (Peer Initiated).
CY_BLE_GATT_ERR_INSUFFICIENT_AUTHORIZATION	The peer client is not authorized (Peer Initiated).

◆ Cy_BLE_GATTS_SendNotification()

cy_en_ble_api_result_t Cy_BLE_GATTS_SendNotification	(	cy_stc_ble_conn_handle_t *	connHandle,
		cy_stc_ble_gatt_handle_value_pair_t *	handleValuePair
	)

Wrapper API to write the attribute value to local GATT database and send the updated value to the peer device using notification procedure.

This API will internally use Cy_BLE_GATTS_WriteAttributeValueLocal() and Cy_BLE_GATTS_Notification() APIs

Parameters

connHandle	The pointer to the connection handle.
handleValuePair	The pointer to the cy_stc_ble_gatt_handle_value_pair_t structure.

Returns: cy_en_ble_api_result_t : The return value indicates whether the function succeeded or failed. The following are possible error codes.

Error Codes	Description
CY_BLE_SUCCESS	On successful operation
CY_BLE_ERROR_NO_DEVICE_ENTITY	If there is no connection for corresponding bdHandle.
CY_BLE_ERROR_INVALID_PARAMETER	Validation of the input parameter failed.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted. Or an error was returned during the Write attribute value in the GATT database.
CY_BLE_ERROR_NTF_DISABLED	Characteristic notifications disabled.

Note: This operation is not permitted when the BLE Stack is busy processing previous requests. The CY_BLE_ERROR_INVALID_OPERATION error code will be returned if the stack queue is full or for other reasons, the stack cannot process the operation. If the BLE Stack busy event CY_BLE_EVT_STACK_BUSY_STATUS is triggered with the status busy, calling this API will trigger this error code. For details, refer to the CY_BLE_EVT_STACK_BUSY_STATUS event.

◆ Cy_BLE_GATTS_SendIndication()

cy_en_ble_api_result_t Cy_BLE_GATTS_SendIndication	(	cy_stc_ble_conn_handle_t *	connHandle,
		cy_stc_ble_gatt_handle_value_pair_t *	handleValuePair
	)

Wrapper API to write the attribute value to local GATT database and send the updated value to the peer device using indication procedure.

This API will internally use Cy_BLE_GATTS_WriteAttributeValueLocal() and Cy_BLE_GATTS_Indication() APIs

Parameters

connHandle	The pointer to the connection handle.
handleValuePair	The pointer to the cy_stc_ble_gatt_handle_value_pair_t structure.

Returns: cy_en_ble_api_result_t : The return value indicates whether the function succeeded or failed. The following are possible error codes.

Error Codes	Description
CY_BLE_SUCCESS	On successful operation
CY_BLE_ERROR_NO_DEVICE_ENTITY	If there is no connection for corresponding bdHandle.
CY_BLE_ERROR_INVALID_PARAMETER	Validation of the input parameter failed.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted. Or an error was returned during the Write attribute value in the GATT database.
CY_BLE_ERROR_IND_DISABLED	Characteristic indications disabled.

Note: This operation is not permitted when the BLE Stack is busy processing previous requests. The CY_BLE_ERROR_INVALID_OPERATION error code will be returned if the BLE Stack queue is full or for other reasons, the stack cannot process the operation. If the BLE Stack busy event CY_BLE_EVT_STACK_BUSY_STATUS is triggered with the status busy, calling this API will trigger this error code. For details, refer to the CY_BLE_EVT_STACK_BUSY_STATUS event.

◆ Cy_BLE_GATTS_IsNotificationEnabled()

bool Cy_BLE_GATTS_IsNotificationEnabled	(	cy_stc_ble_conn_handle_t *	connHandle,
		cy_ble_gatt_db_attr_handle_t	attrHandle
	)

Wrapper API to read CCCD attribute value from the local GATT database and check if the notification is enabled by the peer device.

This function is used to be aware of the notification status (enabled/disabled)

Parameters

connHandle	The pointer to the connection handle.
attrHandle	The attribute handle of the CCCD descriptor or the characteristic which includes the CCCD descriptor.

Returns

true - Notification is enabled.
false - Notification is disabled or if reading CCCD returned an error.

◆ Cy_BLE_GATTS_IsIndicationEnabled()

bool Cy_BLE_GATTS_IsIndicationEnabled	(	cy_stc_ble_conn_handle_t *	connHandle,
		cy_ble_gatt_db_attr_handle_t	attrHandle
	)

Wrapper API to read CCCD attribute value from the local GATT database and check if the indication is enabled by the peer device.

This function is used to be aware of the indication status (enabled/disabled)

Parameters

connHandle	The pointer to the connection handle.
attrHandle	The attribute handle of the CCCD descriptor or the characteristic which includes the CCCD descriptor.

Returns

true - Indication is enabled.
false - Indication is disabled or reading CCCD returned an error.

◆ Cy_BLE_GATTS_SendErrorRsp()

cy_en_ble_api_result_t Cy_BLE_GATTS_SendErrorRsp	(	cy_stc_ble_conn_handle_t *	connHandle,
		const cy_stc_ble_gatt_err_info_t *	errRspParam
	)

Replacement for Cy_BLE_GATTS_ErrorRsp() API.

This function sends an Error Response to the peer device. The Error Response is used to state that a given request cannot be performed, and to provide the reason as defined in cy_en_ble_gatt_err_code_t. This is a non-blocking function.

Deprecate the Cy_BLE_GATTS_ErrorRsp() API in BLE_PDL v2_0

This function sends an Error Response to the peer device. The Error Response is used to state that a given request cannot be performed, and to provide the reason as defined in cy_en_ble_gatt_err_code_t. This is a non-blocking function.

Parameters

connHandle	The pointer to the connection handle.
errRspParam	The pointer to the cy_stc_ble_gatt_err_info_t structure where, the following to be set: errRspParam->opCode errRspParam->attrHandle errRspParam->errorCode

Returns: cy_en_ble_api_result_t : the return value indicates whether the function succeeded or failed. Following are the possible error codes.

Error codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	If param is NULL or connHandle is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTS_EnableAttribute()

cy_en_ble_gatt_err_code_t Cy_BLE_GATTS_EnableAttribute ( cy_stc_ble_gatts_db_attr_enable_info_t * param )

This function is used by GATT Server application to enable the attribute entry for a service or characteristic logical group in the GATT database registered in the BLE Stack.

This is a blocking function. No event is generated on calling this function.

This function returns an error if the attribute does not belong to any service or characteristic logical group. If the attribute entry is already enabled, then this function returns status CY_BLE_GATT_ERR_NONE.

Parameters

param Parameter is of type 'cy_stc_ble_gatts_db_attr_enable_info_t'. param->attrHandle: Handle of the attribute to enable(type cy_ble_gatt_db_attr_handle_t) in GATT database.

Returns: cy_en_ble_gatt_err_code_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_GATT_ERR_NONE	On successful operation.
CY_BLE_GATT_ERR_INVALID_HANDLE	'attrHandle' is not valid.
CY_BLE_GATT_ERR_UNLIKELY_ERROR	NULL pointer as input parameter.

◆ Cy_BLE_GATTS_DisableAttribute()

cy_en_ble_gatt_err_code_t Cy_BLE_GATTS_DisableAttribute ( cy_stc_ble_gatts_db_attr_disable_info_t * param )

This function is used by GATT Server application to disable the attribute entry for service or characteristic logical group in the GATT database registered in the BLE Stack.

This is a blocking function. No event is generated on calling this function.

This function returns an error if the attribute does not belong to a service or a characteristic logical group. If attribute entry is already disabled then it returns CY_BLE_GATT_ERR_NONE as the status. All the attribute entries are enabled in the GATT database during GATT database registration.

Parameters

param Parameter is of type 'cy_stc_ble_gatts_db_attr_disable_info_t'. param->attrHandle: Attribute handle of the registered GATT Database to disable particular attribute entry, of type 'cy_ble_gatt_db_attr_handle_t'

Returns: cy_en_ble_gatt_err_code_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_GATT_ERR_NONE	On successful operation.
CY_BLE_GATT_ERR_INVALID_HANDLE	'attrHandle' is not valid.
CY_BLE_GATT_ERR_UNLIKELY_ERROR	NULL pointer as input parameter.

◆ Cy_BLE_GATTS_DbAuthorize()

cy_en_ble_gatt_err_code_t Cy_BLE_GATTS_DbAuthorize ( cy_stc_ble_gatts_db_authorize_info_t * param )

This function sets or clears authorization permission for the GATT database.

This is a blocking function. No event is generated on calling this function.

Parameters

param Parameter is of type 'cy_stc_ble_gatts_db_authorize_info_t'.

Returns: cy_en_ble_gatt_err_code_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Errors codes	Description
CY_BLE_GATT_ERR_NONE	On successful operation.
CY_BLE_GATT_ERR_UNLIKELY_ERROR	If 'param' is NULL.

◆ Cy_BLE_GATTS_WriteRsp()

cy_en_ble_api_result_t Cy_BLE_GATTS_WriteRsp ( cy_stc_ble_conn_handle_t connHandle )

This function is used by GATT Server application to send a Write Response to a peer GATT Client.

This function should be used after receiving Write Request through CY_BLE_EVT_GATTS_WRITE_REQ event. This is a non-blocking function.

The Write Response must be sent after the attribute value is written or saved by the GATT Server.

If peer GATT Client is a PSoC 6 device, Write Response PDU results in CY_BLE_EVT_GATTC_WRITE_RSP event at the GATT Client's end.

Parameters

connHandle Connection handle to identify the peer GATT entity, of type cy_stc_ble_conn_handle_t.

Returns: cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

Error codes	Description
CY_BLE_SUCCESS	On successful operation.
CY_BLE_ERROR_INVALID_PARAMETER	If 'connHandle' is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

General Description

Functions

Function Documentation

◆ Cy_BLE_GATTS_WriteAttributeValuePeer()

◆ Cy_BLE_GATTS_WriteAttributeValueLocal()

◆ Cy_BLE_GATTS_ReadAttributeValueLocal()

◆ Cy_BLE_GATTS_ReadAttributeValuePeer()

◆ Cy_BLE_GATTS_SendNotification()

◆ Cy_BLE_GATTS_SendIndication()

◆ Cy_BLE_GATTS_IsNotificationEnabled()

◆ Cy_BLE_GATTS_IsIndicationEnabled()

◆ Cy_BLE_GATTS_SendErrorRsp()

◆ Cy_BLE_GATTS_EnableAttribute()

◆ Cy_BLE_GATTS_DisableAttribute()

◆ Cy_BLE_GATTS_DbAuthorize()

◆ Cy_BLE_GATTS_WriteRsp()