General Description

APIs unique to designs configured as a GATT Client role.

A letter 'C' is appended to the API name: Cy_BLE_GATTC_

Functions
cy_en_ble_api_result_t	Cy_BLE_GATTC_StartDiscovery (cy_stc_ble_conn_handle_t connHandle)
	Starts the automatic server discovery process. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_StartPartialDiscovery (cy_stc_ble_conn_handle_t connHandle, cy_ble_gatt_db_attr_handle_t startHandle, cy_ble_gatt_db_attr_handle_t endHandle)
	Starts the automatic server discovery process as per the range provided on a GATT Server to which it is connected. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_SendConfirmation (cy_stc_ble_conn_handle_t *connHandle)
	Replacement for Cy_BLE_GATTC_Confirmation() API. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_StopCmd (cy_stc_ble_gattc_stop_cmd_param_t *param)
	This function is used by the GATT Client application to stop any of the following ongoing GATT procedures: More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_ExchangeMtuReq (cy_stc_ble_gatt_xchg_mtu_param_t *param)
	This function is used by the GATT Client application to send Exchange MTU Request PDU. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_DiscoverPrimaryServices (cy_stc_ble_gattc_read_by_group_req_t *param)
	This function is used by the GATT Client application to discover the primary services as per the handle-range provided, on a peer GATT Server. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_DiscoverPrimaryServiceByUuid (cy_stc_ble_gattc_find_by_type_value_req_t *param)
	This function is used by the GATT Client application to discover a specific primary service on a peer GATT Server, when only the Service UUID is known. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_DiscoverCharacteristics (cy_stc_ble_gattc_read_by_type_req_t *param)
	This function is used by the GATT Client application to find all characteristic declarations within a service definition on a peer GATT Server, when only the service handle range is known. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_DiscoverCharacteristicByUuid (cy_stc_ble_gattc_read_by_type_req_t *param)
	This function is used by the GATT Client application to discover service characteristics on a peer GATT Server, when only the service handle ranges are known and the characteristic UUID is known. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_DiscoverCharacteristicDescriptors (cy_stc_ble_gattc_find_info_req_t *param)
	This function is used by the GATT Client application to find all the characteristic descriptors on a peer GATT Server. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_FindIncludedServices (cy_stc_ble_gattc_read_by_type_req_t *param)
	This function is used by the GATT Client application to find Included Service declarations within a GATT Service on a peer GATT Server. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_ReadByTypeReq (cy_stc_ble_gattc_read_by_type_req_t *param)
	This function allows the user to send Read by type request to a peer GATT server. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_ReadCharacteristicValue (cy_stc_ble_gattc_read_req_t *param)
	This function is used by the GATT Client application to read a Characteristic Value from a peer GATT Server, when the GATT Client application knows the Characteristic Value Handle. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_ReadUsingCharacteristicUuid (cy_stc_ble_gattc_read_by_type_req_t *param)
	This function is used by the GATT Client application to read a Characteristic Value from a peer GATT Server when the application knows only the characteristic UUID and does not know the handle of the characteristic. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_ReadLongCharacteristicValues (cy_stc_ble_gattc_read_blob_req_t *param)
	This function is used by the GATT Client application to read a Characteristic Value from a peer GATT Server when the GATT Client knows the Characteristic Value Handle and the length of the Characteristic Value is longer than that can be sent in a single Read Response Attribute Protocol message. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_ReadMultipleCharacteristicValues (cy_stc_ble_gattc_read_mult_req_t *param)
	This function is used by the GATT Client application to read multiple Characteristic Values from a peer GATT Server when the GATT Client application knows the Characteristic Value Handles. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_ReadCharacteristicDescriptors (cy_stc_ble_gattc_read_req_t *param)
	This function is used by the GATT Client application to read a characteristic descriptor from a peer GATT Server when the GATT Client application knows the Attribute handle from the characteristic descriptor declaration. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_ReadLongCharacteristicDescriptors (cy_stc_ble_gattc_read_blob_req_t *param)
	This function is used by the GATT Client application to read a characteristic descriptor from a peer GATT Server when the GATT Client application knows the Attribute handle from the characteristic descriptor declaration and the length of the characteristic descriptor declaration is longer than what can be sent in a single Read Response Attribute Protocol message. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_WriteCharacteristicValue (cy_stc_ble_gattc_write_req_t *param)
	This function is used by the GATT Client application to write a Characteristic Value to a peer GATT Server when the GATT Client knows the Characteristic Value Handle. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_WriteCharacteristicDescriptors (cy_stc_ble_gattc_write_req_t *param)
	This function is used by the GATT client application to write a characteristic descriptor value to a peer GATT Server when the GATT Client application knows the characteristic descriptor handle. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_WriteLongCharacteristicValues (cy_stc_ble_gattc_prep_write_req_t *param)
	This function is used by the GATT Client application to write a Characteristic Value to a peer GATT Server when the GATT Client knows the Characteristic Value Handle but the length of the Characteristic Value is longer than GATT MTU size and cannot be sent in a single Write Request Attribute Protocol message. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_ReliableWrites (cy_stc_ble_gattc_reliable_write_req_t *param)
	This function is used by the GATT Client application to write a Characteristic Value to a peer GATT Server when the GATT Client knows the Characteristic Value Handle, and assurance is required that the correct Characteristic Value is going to be written by transferring the Characteristic Value to be written in both directions before the write is performed. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_WriteLongCharacteristicDescriptors (cy_stc_ble_gattc_prep_write_req_t *param)
	This function is used by the GATT Client application to write a characteristic descriptor value to a GATT Server when the GATT Client application knows the characteristic descriptor handle but the length of the characteristic descriptor value is longer than what can be sent in a single Write Request Attribute Protocol message. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_SendExecuteWriteReq (cy_stc_ble_gattc_exec_write_req_t *param)
	This function is used by the GATT Client application to send execute write request to peer GATT Server. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_WriteWithoutResponse (cy_stc_ble_gattc_write_cmd_req_t *param)
	This function is used by the GATT Client application to do a Write Without Response procedure on a Characteristic in the peer GATT Server. More...

cy_en_ble_api_result_t	Cy_BLE_GATTC_SignedWriteWithoutRsp (cy_stc_ble_gattc_signed_write_cmd_req_t *param)
	This function is used by the GATT Client application to write a specific characteristic value when the ATT bearer is not encrypted. More...

Function Documentation

◆ Cy_BLE_GATTC_StartDiscovery()

cy_en_ble_api_result_t Cy_BLE_GATTC_StartDiscovery ( cy_stc_ble_conn_handle_t connHandle )

Starts the automatic server discovery process.

Discovery procedure is based on the user configuration. It discovers only services, characteristics, descriptors which were declared in the GATT database. Discovery procedure has the following flow:

discovering primary services by BLE Stack function Cy_BLE_GATTC_DiscoverPrimaryServices();
discovering included services by BLE Stack function Cy_BLE_GATTC_FindIncludedServices();
discovering characteristics for available services by BLE Stack function Cy_BLE_GATTC_DiscoverCharacteristicDescriptors();
discovering characteristic descriptors by BLE Stack function Cy_BLE_GATTC_DiscoverCharacteristicDescriptors();

During the discovery procedure the discovery-specific BLE Stack events are handled by the PSoC 6 BLE Middleware and thus aren't passed to the application callback: CY_BLE_EVT_GATTC_READ_BY_GROUP_TYPE_RSP, CY_BLE_EVT_GATTC_READ_BY_TYPE_RSP, CY_BLE_EVT_GATTC_FIND_INFO_RSP, CY_BLE_EVT_GATTC_ERROR_RSP.

After discovering procedure all information about available services is stored in cy_stc_ble_disc_srvc_info_t structures, and discovered attributes handles are stored in service-specific client structures, such as cy_stc_ble_basc_t for Battery service or cy_stc_ble_hrsc_t for Heart Rate service.

The following events may be generated after calling this function:

CY_BLE_EVT_GATTC_DISCOVERY_COMPLETE - event is generated when the remote device was successfully discovered.
CY_BLE_EVT_GATTC_ERROR_RSP - is generated if the device discovery has failed.
CY_BLE_EVT_GATTC_SRVC_DUPLICATION - is generated if duplicate service record was found during the server device discovery.
CY_BLE_EVT_GATTC_CHAR_DUPLICATION - is generated if duplicate service's characteristic descriptor record was found during the server device discovery.
CY_BLE_EVT_GATTC_DESCR_DUPLICATION - is generated if duplicate service's characteristic descriptor record was found during the server device discovery.

Returns: cy_en_ble_api_result_t : 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_INVALID_OPERATION	The operation is not permitted
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.
CY_BLE_ERROR_INVALID_STATE	If the function is called in any state except connected or discovered

◆ Cy_BLE_GATTC_StartPartialDiscovery()

cy_en_ble_api_result_t Cy_BLE_GATTC_StartPartialDiscovery	(	cy_stc_ble_conn_handle_t	connHandle,
		cy_ble_gatt_db_attr_handle_t	startHandle,
		cy_ble_gatt_db_attr_handle_t	endHandle
	)

Starts the automatic server discovery process as per the range provided on a GATT Server to which it is connected.

This function could be used for partial server discovery after indication received to the service Changed Characteristic Value.

The following events may be generated after calling this function:

CY_BLE_EVT_GATTC_DISCOVERY_COMPLETE - event is generated when the remote device was successfully discovered.
CY_BLE_EVT_GATTC_ERROR_RSP - is generated if the device discovery has failed.
CY_BLE_EVT_GATTC_SRVC_DUPLICATION - is generated if duplicate service record was found during the server device discovery.
CY_BLE_EVT_GATTC_CHAR_DUPLICATION - is generated if duplicate service's characteristic descriptor record was found during the server device discovery.
CY_BLE_EVT_GATTC_DESCR_DUPLICATION - is generated if duplicate service's characteristic descriptor record was found during the server device discovery.

Parameters

connHandle	The handle which consists of the device ID and ATT connection ID.
startHandle	Start of affected attribute handle range.
endHandle	End of affected attribute handle range.

Returns: cy_en_ble_api_result_t : 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_INVALID_OPERATION	The operation is not permitted
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.
CY_BLE_ERROR_INVALID_STATE	If the function is called in any state except connected or discovered

◆ Cy_BLE_GATTC_SendConfirmation()

cy_en_ble_api_result_t Cy_BLE_GATTC_SendConfirmation ( cy_stc_ble_conn_handle_t * connHandle )

Replacement for Cy_BLE_GATTC_Confirmation() API.

This function sends confirmation to the GATT Server on receiving a Handle Value The indication event CY_BLE_EVT_GATTC_HANDLE_VALUE_IND occurs at the GATT Client's end. This is a non-blocking function.

This function call triggers a CY_BLE_EVT_GATTS_HANDLE_VALUE_CNF event at the GATT Server's end.

Deprecate the Cy_BLE_GATTC_Confirmation() API in BLE_PDL v2_0

Parameters

connHandle The pointer to the connection handle.

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_GATTC_StopCmd()

cy_en_ble_api_result_t Cy_BLE_GATTC_StopCmd ( cy_stc_ble_gattc_stop_cmd_param_t * param )

This function is used by the GATT Client application to stop any of the following ongoing GATT procedures:

If none of the above procedures is ongoing, then this command will be ignored. This function has no effect on ATT procedures other than those listed above. If the procedure is ongoing, this function will stop it and inform that the operation is successful through the event 'CY_BLE_EVT_GATTC_STOP_CMD_COMPLETE'. This is a non-blocking function.

If the user intends to start a new GATT procedure including those listed above and there is an ongoing GATT procedure (any one from the above list), the user needs to call this function to stop the ongoing GATT procedure and then invoke the desired GATT procedure.

Parameters

param parameter is of type cy_stc_ble_gattc_stop_cmd_param_t. param->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 'param' is NULL or 'connHandle' is invalid.

◆ Cy_BLE_GATTC_ExchangeMtuReq()

cy_en_ble_api_result_t Cy_BLE_GATTC_ExchangeMtuReq ( cy_stc_ble_gatt_xchg_mtu_param_t * param )

This function is used by the GATT Client application to send Exchange MTU Request PDU.

This function is used to send maximum size of packet (GATT MTU) that cab be received by GATT Client application. This is a non-blocking function.

Default GATT MTU size as per Bluetooth 5.0 core specification is 23 bytes. If the GATT Client application supports a size greater than the default, it has to invoke this function with the desired GATT MTU size. This function should be initiated only once during a connection.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.3.1 for more details on GATT MTU exchange operation.

If the peer GATT Server device is a PSoC 6 MCU, Exchange MTU Request PDU results in CY_BLE_EVT_GATTS_XCNHG_MTU_REQ event at the GATT Server's end, in response to which the GATT Server is expected to send its maximum size of packet (GATT MTU).

The CY_BLE_EVT_GATTC_XCHNG_MTU_RSP event is generated at the GATT Client application on receiving GATT MTU response from the GATT Server.

Parameters

param parameter is of type CY_BLE_GATT_XCHG_MTU_REQ_PARAM_T. param->mtu: Size of GATT MTU.

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 'param' is NULL or 'connHandle' is invalid or, 'mtu' value is greater than that set on calling Cy_BLE_StackInit().
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_DiscoverPrimaryServices()

cy_en_ble_api_result_t Cy_BLE_GATTC_DiscoverPrimaryServices ( cy_stc_ble_gattc_read_by_group_req_t * param )

This function is used by the GATT Client application to discover the primary services as per the handle-range provided, on a peer GATT Server.

This is a non-blocking function.

Internally, this function initiates multiple Read By Group Type Requests to the peer device, in response to which it receives Read By Group Type Responses. Each Read By Group Type Response results in CY_BLE_EVT_GATTC_READ_BY_GROUP_TYPE_RSP event, which is propagated to the application layer for handling.

Primary service discovery is complete when Error Response (CY_BLE_EVT_GATTC_ERROR_RSP) is received with Error Code set to Attribute Not Found or when the End Group Handle in the Read by Group Type Response is 0xFFFF. Completion of this operation is notified to the upper layer(s) using CY_BLE_EVT_GATTC_ERROR_RSP or CY_BLE_EVT_GATTC_LONG_PROCEDURE_END event.

Application can stop the primary service discovery if the desired primary service is found prior to discovering all the primary services on the GATT Server. This can be achieved by using the Cy_BLE_GATTC_StopCmd() function.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.5.0 for more details on this sequence of operations.

Parameters

param

parameter is of type cy_stc_ble_gattc_read_by_group_req_t. param->connHandle: Connection handle of type cy_stc_ble_conn_handle_t to identify the peer GATT entity. param->range: Parameter is of type cy_stc_ble_gatt_attr_handle_range_t where,

'range.startHandle' can be set to the start handle of the desired primary service.
'range.endHandle' can be set to the end handle of the desired primary service.

Note: 'startHandle' & 'endHandle' should not be zero and 'startHandle' shall be less than or equal to the 'endHandle'.

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 'param' is NULL or if any of the input parameters is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_DiscoverPrimaryServiceByUuid()

cy_en_ble_api_result_t Cy_BLE_GATTC_DiscoverPrimaryServiceByUuid ( cy_stc_ble_gattc_find_by_type_value_req_t * param )

This function is used by the GATT Client application to discover a specific primary service on a peer GATT Server, when only the Service UUID is known.

This is a non-blocking function.

Internally, this function initiates multiple Find By Type Value Requests with the Attribute Type parameter set to the UUID for Primary Service and the Attribute Value set to the 16-bit Bluetooth UUID or 128-bit UUID for the specific primary service. Each Find By Type Value Response received from the peer device is passed to the application as CY_BLE_EVT_GATTC_FIND_BY_TYPE_VALUE_RSP event.

The sequence of operations is complete when the Error Response is received and the Error Code is set to Attribute Not Found or when the End Group Handle in the Find By Type Value Response is 0xFFFF. Completion of this function is notified to the upper layer using CY_BLE_EVT_GATTC_ERROR_RSP or CY_BLE_EVT_GATTC_LONG_PROCEDURE_END event.

Application can stop this procedure if a desired primary service is found prior to the discovery of all the primary services of the specified service UUID supported on the GATT Server. This can be achieved by using the Cy_BLE_GATTC_StopCmd() function.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.4.2 for more details on this sequence of operations.

Parameters

param

parameter is of type cy_stc_ble_gattc_find_by_type_value_req_t. param->connHandle: Connection handle of type cy_stc_ble_conn_handle_t to identify the peer GATT entity. param->range and param->uuid are ignored in this function. param->value: Parameter is of type cy_stc_ble_gatt_value_t, where,

'value.val' should point to uint8_t array containing the UUID to look for. UUID can be 16 or 128 bit.
'value.len' should be set to 2 if the 16-bit UUID is to be found. The length should be set to 16 if 128-bit UUID is to be found.
'value.actualLen' is an unused parameter and should be ignored.

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 '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_GATTC_DiscoverCharacteristics()

cy_en_ble_api_result_t Cy_BLE_GATTC_DiscoverCharacteristics ( cy_stc_ble_gattc_read_by_type_req_t * param )

This function is used by the GATT Client application to find all characteristic declarations within a service definition on a peer GATT Server, when only the service handle range is known.

This is a non-blocking function.

Internally, multiple Read By Type Requests are sent to the GATT Server in response to which Read By Type Responses are received. Each response results in the event CY_BLE_EVT_GATTC_READ_BY_TYPE_RSP, which is passed to the application layer for handling.

The sequence of operations is complete when the Error Response is received and the Error Code is set to Attribute Not Found or the Read By Type Response has an Attribute Handle that is equal to the Ending Handle of the request. Completion of this function is notified to the upper layer using CY_BLE_EVT_GATTC_ERROR_RSP or with the CY_BLE_EVT_GATTC_LONG_PROCEDURE_END event.

Application can stop this procedure if a desired characteristic is found prior to the discovering all the characteristics of the specified service supported on the GATT Server. This can be achieved by using the Cy_BLE_GATTC_StopCmd() function.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.6.1 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_by_type_req_t, The following must be set: param->range.startHandle
param->range.endHandle
param->connHandle
The following must be ignored: param->uuidFormat (CY_BLE_GATT_16_BIT_UUID_FORMAT or CY_BLE_GATT_128_BIT_UUID_FORMAT)
param->uuid.uuid16 or param->uuid.uuid128 based on the uuidFormat

Note: 'startHandle' & 'endHandle' should not be zero, and 'startHandle' shall be less than or equal to the 'endHandle'.

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 'param' is NULL or if any of the input parameters is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_DiscoverCharacteristicByUuid()

cy_en_ble_api_result_t Cy_BLE_GATTC_DiscoverCharacteristicByUuid ( cy_stc_ble_gattc_read_by_type_req_t * param )

This function is used by the GATT Client application to discover service characteristics on a peer GATT Server, when only the service handle ranges are known and the characteristic UUID is known.

This is a non-blocking function.

Internally, multiple Read By Type Requests are sent to the peer device in response to which Read By Type Responses are received. Each of these responses results in the event CY_BLE_EVT_GATTC_READ_BY_TYPE_RSP, which is passed to the application layer for further processing.

The sequence of operations is complete when the Error Response is received and the Error Code is set to Attribute Not Found or the Read By Type Response has an Attribute Handle that is equal to the Ending Handle of the request. Completion of this function is notified to the upper layer using CY_BLE_EVT_GATTC_ERROR_RSP or CY_BLE_EVT_GATTC_LONG_PROCEDURE_END event.

Application can stop this procedure if a desired characteristic is found prior to the discovering all the characteristics of the specified service supported on the GATT Server. This can be achieved by using the Cy_BLE_GATTC_StopCmd() function.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.6.2 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_by_type_req_t, The following must be set: param->range.startHandle param->range.endHandle param->connHandle param->uuidFormat (CY_BLE_GATT_16_BIT_UUID_FORMAT or CY_BLE_GATT_128_BIT_UUID_FORMAT) param->uuid.uuid16 or readByTypeReqParam->uuid.uuid128 based on the uuidFormat

Note: 'startHandle' & 'endHandle' should not be zero, and 'startHandle' shall be less than or equal to the 'endHandle'.

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 'param' is NULL or if any of the input parameters is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_DiscoverCharacteristicDescriptors()

cy_en_ble_api_result_t Cy_BLE_GATTC_DiscoverCharacteristicDescriptors ( cy_stc_ble_gattc_find_info_req_t * param )

This function is used by the GATT Client application to find all the characteristic descriptors on a peer GATT Server.

This is a non-blocking function.

Internally, multiple Find Information Requests are sent to the peer device in response to which Find Information Responses are received by the GATT Client application. Each of these responses generate CY_BLE_EVT_GATTC_FIND_INFO_RSP event at the GATT Client application end.

The sequence of operations is complete when the Error Response is received and the Error Code is set to Attribute Not Found or the Find Information Response has an Attribute Handle that is equal to the Ending Handle of the request. Completion of this function is notified to the upper layer using CY_BLE_EVT_GATTC_ERROR_RSP or CY_BLE_EVT_GATTC_LONG_PROCEDURE_END event.

Application can stop this procedure if the desired Characteristic Descriptor is found prior to the discovering all the characteristic descriptors of the specified characteristic. This can be achieved by using the Cy_BLE_GATTC_StopCmd() function.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.7.1 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_find_info_req_t. The following must be set: param->range.startHandle
param->range.endHandle
param->connHandle

Note: 'startHandle' & 'endHandle' should not be zero, and 'startHandle' shall be less than or equal to the 'endHandle'.

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 'param' is NULL or if any of the input parameters is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_FindIncludedServices()

cy_en_ble_api_result_t Cy_BLE_GATTC_FindIncludedServices ( cy_stc_ble_gattc_read_by_type_req_t * param )

This function is used by the GATT Client application to find Included Service declarations within a GATT Service on a peer GATT Server.

This is a non-blocking function.

Internally, multiple Read By Type Requests are sent to the peer device in response to which Read By Type Responses are received (CY_BLE_EVT_GATTC_READ_BY_TYPE_RSP) and passed to the application layer.

When Read By Type Response data does not contain the service UUID, indicating the service uses a 128-bit UUID, the application layer can choose to get the service UUID by performing the following steps:

Stop ongoing GATT operation by invoking Cy_BLE_GATTC_StopCmd()
Send Read Request by invoking the function Cy_BLE_GATTC_ReadCharacteristicValue() with the read request attribute handle set to the included service attribute handle. Application should handle CY_BLE_EVT_GATTC_READ_RSP event.
Include service discovery can further be continued by calling Cy_BLE_GATTC_FindIncludedServices() function with start handle (param->range.startHandle) equals to (included service attribute handle + 1).

The sequence of operations is complete when either the Error Response is received with the Error Code set to Attribute Not Found or the Read By Type Response has an Attribute Handle of the included service declaration that is equal to the Ending Handle of the request. Completion of this function is notified to the upper layer using CY_BLE_EVT_GATTC_ERROR_RSP or CY_BLE_EVT_GATTC_LONG_PROCEDURE_END event.

Application can stop this procedure if the desired included service is found prior to the discovering all the included services of the specified service. This can be achieved by using the Cy_BLE_GATTC_StopCmd() function.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.5.1 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_by_type_req_t, The following must be set: param->range.startHandle
param->range.endHandle
param->connHandle
The following must be ignored: param->uuidFormat (CY_BLE_GATT_16_BIT_UUID_FORMAT or CY_BLE_GATT_128_BIT_UUID_FORMAT)
param->uuid.uuid16 or readByTypeReqParam->uuid.uuid128 based on the uuidFormat

Note: 'startHandle' & 'endHandle' should not be zero, and 'startHandle' shall be less than or equal to the 'endHandle'.

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 'param' is NULL or if any of the input parameters is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_ReadByTypeReq()

cy_en_ble_api_result_t Cy_BLE_GATTC_ReadByTypeReq ( cy_stc_ble_gattc_read_by_type_req_t * param )

This function allows the user to send Read by type request to a peer GATT server.

This function results in CY_BLE_EVT_GATTC_READ_BY_TYPE_RSP event or CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client depending on whether the GATT server sends read by type response or GATT Error response.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.5.1 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_by_type_req_t, Where, the following needs to be set: param->range.startHandle param->range.endHandle param->connHandle param->uuidFormat (CY_BLE_GATT_16_BIT_UUID_FORMAT or CY_BLE_GATT_128_BIT_UUID_FORMAT) param->uuid.uuid16 or readByTypeReqParam->uuid.uuid128 based on the uuidFormat

Note: 'startHandle' & 'endHandle' should not be zero, and 'startHandle' shall be less than or equal to the 'endHandle'.

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 'param' is NULL or if any of the input parameters is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_ReadCharacteristicValue()

cy_en_ble_api_result_t Cy_BLE_GATTC_ReadCharacteristicValue ( cy_stc_ble_gattc_read_req_t * param )

This function is used by the GATT Client application to read a Characteristic Value from a peer GATT Server, when the GATT Client application knows the Characteristic Value Handle.

This is a non-blocking function.

Internally, Read Request is sent to the peer GATT Server. If the read operation is successful, GATT Server sends a Read Response. This response results in CY_BLE_EVT_GATTC_READ_RSP event at the GATT Client's end, and response is passed to the application.

In response to the Read Request GATT server shall send an Error Response if

GATT Client has insufficient authentication to read requested characteristic value OR
GATT Client has insufficient authorization to read requested characteristic value OR
GATT Client has used insufficient encryption key size OR
GATT Client has insufficient encryption to read requested characteristic value OR
If GATT Client requested handle is invalid OR
If a read operation is not permitted on the requested Characteristic Value. The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, Read Request PDU results in CY_BLE_EVT_GATTS_READ_CHAR_VAL_ACCESS_REQ event at the GATT server's end, if the corresponding characteristic's attribute permission is set to CY_BLE_GATT_DB_ATTR_CHAR_VAL_RD_EVENT.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.8.1 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_req_t. The following must be set: param->attrHandle: Attribute handle to be read
param->connHandle

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 'param' is NULL or 'connHandle' is invalid, or if 'attrHandle' is zero.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_ReadUsingCharacteristicUuid()

cy_en_ble_api_result_t Cy_BLE_GATTC_ReadUsingCharacteristicUuid ( cy_stc_ble_gattc_read_by_type_req_t * param )

This function is used by the GATT Client application to read a Characteristic Value from a peer GATT Server when the application knows only the characteristic UUID and does not know the handle of the characteristic.

This is a non-blocking function.

Internally, Read By Type Request is sent to the peer GATT server. If the read operation is successful, GATT Server sends a Read By Type Response. This response results in CY_BLE_EVT_GATTC_READ_RSP event at the GATT Client's end, and response is passed to the application.

In response to this Request GATT server shall send an Error Response if

GATT Client has insufficient authentication to read the requested characteristic value OR
GATT Client has insufficient authorization to read the requested characteristic value OR
GATT Client has insufficient encryption to read the requested characteristic value OR

GATT Client has used insufficient encryption key size OR
Read operation is not permitted on the requested Characteristic Value OR
characteristic does not exist on the GATT server within the handle OR range provided OR
Starting Handle parameter greater than the Ending Handle parameter or the Starting Handle parameter is 0x0000 The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, Read By Type Request PDU results in the CY_BLE_EVT_GATTS_READ_CHAR_VAL_ACCESS_REQ event at the GATT server's end if the corresponding characteristic's attribute permission is set to CY_BLE_GATT_DB_ATTR_CHAR_VAL_RD_EVENT.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.8.2 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_by_type_req_t, Where, the following needs to be set: param->range.startHandle param->range.endHandle param->connHandle param->uuidFormat (CY_BLE_GATT_16_BIT_UUID_FORMAT or CY_BLE_GATT_128_BIT_UUID_FORMAT) param->uuid.uuid16 or readByTypeReqParam->uuid.uuid128 based on the uuidFormat

Note: 'startHandle' & 'endHandle' should not be zero, and 'startHandle' shall be less than or equal to the 'endHandle'.

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 'param' is NULL or if any of the input parameters is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_ReadLongCharacteristicValues()

cy_en_ble_api_result_t Cy_BLE_GATTC_ReadLongCharacteristicValues ( cy_stc_ble_gattc_read_blob_req_t * param )

This function is used by the GATT Client application to read a Characteristic Value from a peer GATT Server when the GATT Client knows the Characteristic Value Handle and the length of the Characteristic Value is longer than that can be sent in a single Read Response Attribute Protocol message.

This is a non-blocking function.

Internally multiple Read Blob Requests are sent to the peer device in response to which Read Blob Responses are received. For each Read Blob Request, a Read Blob Response event is received (CY_BLE_EVT_GATTC_READ_BLOB_RSP) with a portion of the Characteristic Value contained in the Part Attribute Value parameter. These events are propagated to the application layer for further processing. Each read blob response will return up to (GATT MTU-1) bytes of data. If the size of characteristic value field is an integral multiple of (GATT MTU-1) then the operation terminates with an error response event, where the error code is CY_BLE_GATT_ERR_INVALID_OFFSET. If the size of the characteristic value field is not an integral multiple of (GATT MTU-1), the last read blob response will return data bytes that are less than (GATT MTU-1). The application must monitor these two conditions before proceeding with the initiation of any other GATT operation.

In response to the this Request GATT server shall send an Error Response if

GATT Client has insufficient authentication to read the requested characteristic value OR
GATT Client has insufficient authorization to read the requested characteristic value OR
GATT Client has insufficient encryption to read the requested characteristic value OR
GATT Client has used insufficient encryption key size OR
Read operation is not permitted on the requested Characteristic Value OR
The Characteristic Value is not longer than (GATT MTU - 1) OR
The requested handle is invalid OR
Value offset is greater than length attribute value. The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, Read Blob Request PDU results in the CY_BLE_EVT_GATTS_READ_CHAR_VAL_ACCESS_REQ event at the GATT server's end if the corresponding characteristic's attribute permission is set to CY_BLE_GATT_DB_ATTR_CHAR_VAL_RD_EVENT.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.8.3 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_blob_req_t. Where, the following needs to be set: param->attrHandle param->offset param->connHandle

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 'param' is NULL or 'connHandle' is invalid, or if 'attrHandle' is zero.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_ReadMultipleCharacteristicValues()

cy_en_ble_api_result_t Cy_BLE_GATTC_ReadMultipleCharacteristicValues ( cy_stc_ble_gattc_read_mult_req_t * param )

This function is used by the GATT Client application to read multiple Characteristic Values from a peer GATT Server when the GATT Client application knows the Characteristic Value Handles.

This is a non-blocking function.

Internally, Read Multiple Request is sent to the peer GATT Server. If the read operation is successful, GATT Server sends a Read Multiple Response. This response results in CY_BLE_EVT_GATTC_READ_RSP event at the GATT Client's end, and response is passed to the application.

In response to the this Request, the GATT server shall send an Error Response if

GATT Client has insufficient authentication to read the requested characteristic value OR
GATT Client has insufficient authorization to read the requested characteristic value OR
GATT Client has insufficient encryption to read the requested characteristic value OR
GATT Client has used insufficient encryption key size OR
Read operation is not permitted on any of the requested Characteristic Value OR
Any of requested handle are invalid. The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, Read Multiple Request PDU results in the CY_BLE_EVT_GATTS_READ_CHAR_VAL_ACCESS_REQ event at the GATT server's end if the corresponding characteristic's attribute permission is set to CY_BLE_GATT_DB_ATTR_CHAR_VAL_RD_EVENT.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.8.4 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_mult_req_t. Where, the following needs to be set: param->handleList param->listCount param->connHandle

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 'param' is NULL or if any of the input parameters is invalid.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_ReadCharacteristicDescriptors()

cy_en_ble_api_result_t Cy_BLE_GATTC_ReadCharacteristicDescriptors ( cy_stc_ble_gattc_read_req_t * param )

This function is used by the GATT Client application to read a characteristic descriptor from a peer GATT Server when the GATT Client application knows the Attribute handle from the characteristic descriptor declaration.

This is a non-blocking function.

Internally, Read Request is sent to the peer GATT Server. If the read operation is successful, GATT Server sends a Read Response. This response results in CY_BLE_EVT_GATTC_READ_RSP event at the GATT Client's end, and response is passed to the application.

In response to the this Request GATT server shall send an Error Response if

GATT Client has insufficient authentication to read the requested descriptor value OR
GATT Client has insufficient authorization to read the requested descriptor value OR
GATT Client has used insufficient encryption key size OR
GATT Client has insufficient encryption to read the requested descriptor value OR
GATT Client requested handle is invalid OR
Read operation is not permitted on the requested descriptor. The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, Read Request PDU results in the CY_BLE_EVT_GATTS_READ_CHAR_VAL_ACCESS_REQ event at the GATT server's end if the corresponding characteristic's attribute permission is set to CY_BLE_GATT_DB_ATTR_CHAR_VAL_RD_EVENT.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.12.1 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_req_t. Where, the following needs to be set: param->attrHandle: Attribute handle to be read param->connHandle

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 'param' is NULL or 'connHandle' is invalid, or if 'attrHandle' is zero.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_ReadLongCharacteristicDescriptors()

cy_en_ble_api_result_t Cy_BLE_GATTC_ReadLongCharacteristicDescriptors ( cy_stc_ble_gattc_read_blob_req_t * param )

This function is used by the GATT Client application to read a characteristic descriptor from a peer GATT Server when the GATT Client application knows the Attribute handle from the characteristic descriptor declaration and the length of the characteristic descriptor declaration is longer than what can be sent in a single Read Response Attribute Protocol message.

This is a non-blocking function.

Internally multiple Read Blob Requests are sent to the peer device in response to which Read Blob Responses are received. For each Read Blob Request, a Read Blob Response event is received (CY_BLE_EVT_GATTC_READ_BLOB_RSP) with a portion of the Characteristic Value contained in the Part Attribute Value parameter. These events are propagated to the application layer for further processing. Each read blob response will return up to (GATT MTU-1) bytes of data. If the size of characteristic descriptor field is an integral multiple of (GATT MTU-1) then the operation terminates with an error response event, where the error code is CY_BLE_GATT_ERR_INVALID_OFFSET. If the size of the characteristic descriptor field is not an integral multiple of (GATT MTU-1), the last read blob response will return data bytes that are less than (GATT MTU-1). The application must monitor these two conditions before proceeding with the initiation of any other GATT operation.

In response to the this Request GATT server shall send an Error Response if

GATT Client has insufficient authentication to read the requested descriptor value OR
GATT Client has insufficient authorization to read the requested descriptor value OR
GATT Client has insufficient encryption to read the requested descriptor value OR
GATT Client has used insufficient encryption key size OR
Read operation is not permitted on the requested descriptor Value. OR
The Characteristic descriptor value is not longer than (GATT MTU - 1)
The requested handle is invalid OR
The value offset is greater than length of attribute value. The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, Read Blob Request PDU results in the CY_BLE_EVT_GATTS_READ_CHAR_VAL_ACCESS_REQ event at the GATT server's end if the corresponding characteristic's attribute permission is set to CY_BLE_GATT_DB_ATTR_CHAR_VAL_RD_EVENT.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.12.2 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_read_blob_req_t. Where, the following needs to be set: param->attrHandle param->offset param->connHandle

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 'param' is NULL or 'connHandle' is invalid, or if 'attrHandle' is zero.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_WriteCharacteristicValue()

cy_en_ble_api_result_t Cy_BLE_GATTC_WriteCharacteristicValue ( cy_stc_ble_gattc_write_req_t * param )

This function is used by the GATT Client application to write a Characteristic Value to a peer GATT Server when the GATT Client knows the Characteristic Value Handle.

This is a non-blocking function.

Internally, Write Request is sent to the peer GATT Server. If write operation is successful GATT server sends Write Response. This Response results in the event CY_BLE_EVT_GATTC_WRITE_RSP at the GATT Client application.

In response to the this Request GATT server shall send an Error Response if

GATT Client has insufficient authentication to write the requested Characteristic value OR
GATT Client has insufficient authorization to write the requested Characteristic value OR
GATT Client has insufficient encryption to write the requested Characteristic value OR
GATT Client has used insufficient encryption key size OR
Write operation is not permitted on the requested Characteristic Value OR
The requested handle is invalid OR
The requested value length is greater than attribute value length. The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, Write Request PDU results in the CY_BLE_EVT_GATTS_WRITE_REQ event at the GATT server's end.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.9.3 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_write_req_t. Where, the following needs to be set: param->handleValPair param->connHandle

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 'param' is NULL or 'connHandle' is invalid, or if 'attrHandle' is zero or if 'param->handleValPair.value.len' value is greater than (Effective GATT MTU-3).
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_WriteCharacteristicDescriptors()

cy_en_ble_api_result_t Cy_BLE_GATTC_WriteCharacteristicDescriptors ( cy_stc_ble_gattc_write_req_t * param )

This function is used by the GATT client application to write a characteristic descriptor value to a peer GATT Server when the GATT Client application knows the characteristic descriptor handle.

This is a non-blocking function.

Internally, Write Request is sent to the peer GATT Server. If write operation is successful GATT server sends Write Response. This Response results in the event CY_BLE_EVT_GATTC_WRITE_RSP at the GATT Client application.

In response to the this Request, the GATT server shall send an Error Response if

GATT Client has insufficient authentication to write the requested descriptor value OR
GATT Client has insufficient authorization to write the requested descriptor value OR
GATT Client has insufficient encryption to write the requested descriptor value OR
GATT Client has used insufficient encryption key size OR
Write operation is not permitted on the requested descriptor Value OR
The requested handle is invalid OR
The requested value length is greater than attribute value length. The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, Write Request PDU results in the CY_BLE_EVT_GATTS_WRITE_REQ event at the GATT server's end.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.12.3 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_write_req_t. Where, the following needs to be set: param->handleValPair param->connHandle

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 'param' is NULL or 'connHandle' is invalid, or if 'attrHandle' is zero or if 'param->handleValPair.value.len' value is greater than (Effective GATT MTU-3).
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_WriteLongCharacteristicValues()

cy_en_ble_api_result_t Cy_BLE_GATTC_WriteLongCharacteristicValues ( cy_stc_ble_gattc_prep_write_req_t * param )

This function is used by the GATT Client application to write a Characteristic Value to a peer GATT Server when the GATT Client knows the Characteristic Value Handle but the length of the Characteristic Value is longer than GATT MTU size and cannot be sent in a single Write Request Attribute Protocol message.

This is a non-blocking function.

Internally, multiple Prepare Write Requests are sent to the GATT Server, in response to which Prepare Write Responses are received. No events are generated by the BLE Stack for these Responses.

Prepare Write Requests are repeated until the complete Characteristic Value has been transferred to the GATT Server, after which an Execute Write Request is sent to the GATT Server to write the initially transferred value at the GATT Server's end.

If the write operation is successful, GATT Server sends an Execute Write Response. This response results in CY_BLE_EVT_GATTC_EXEC_WRITE_RSP event at the GATT Client application. The value associated with this event has to be checked by the application layer to confirm that the long write operation is succeeded.

In response to the Prepare Write Request, GATT server shall send an Error Response if

GATT Client has insufficient authentication to write the requested characteristic value OR
GATT Client has insufficient authorization to write the requested characteristic value OR
GATT Client has insufficient encryption to write the requested characteristic value OR
GATT Client has used insufficient encryption key size OR
Write operation is not permitted on the requested Characteristic Value OR
The requested handle is invalid.

In response to Execute Write Request, GATT server shall send an Error Response if

If the prepared attribute value exceeds the maximum length of attribute value OR
If the prepare value offset is greater than the current length of the attribute value The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, this function results in following events at the GATT Server's end.

CY_BLE_EVT_GATTS_PREP_WRITE_REQ - event for Prepare Write Request.
CY_BLE_EVT_GATTS_EXEC_WRITE_REQ - event for Execute Write Request.
CY_BLE_EVT_MEMORY_REQUEST - Need confirmation from NPAL.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.9.4 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_prep_write_req_t, where 'param->value.val' points to the actual data to be written. 'param' and all associated variables need to be retained in memory by the calling application until the GATT Write Long Characteristic Value operation is completed successfully.

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 'param' is NULL or 'connHandle' is invalid, or if 'attrHandle' is zero.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_ReliableWrites()

cy_en_ble_api_result_t Cy_BLE_GATTC_ReliableWrites ( cy_stc_ble_gattc_reliable_write_req_t * param )

This function is used by the GATT Client application to write a Characteristic Value to a peer GATT Server when the GATT Client knows the Characteristic Value Handle, and assurance is required that the correct Characteristic Value is going to be written by transferring the Characteristic Value to be written in both directions before the write is performed.

This is a non-blocking function.

Internally, multiple Prepare Write Requests are sent to the GATT Server, in response to which Prepare Write Responses are received. No events are generated by the BLE Stack for these Responses.

Prepare Write Requests are repeated until the complete Characteristic Value has been transferred to the GATT Server, after which an Execute Write Request is sent to the GATT Server to write the initially transferred value at the GATT Server's end.

If the write operation is successful, GATT Server sends an Execute Write Response. This response results in CY_BLE_EVT_GATTC_EXEC_WRITE_RSP event at the GATT Client application. The value associated with this event has to be checked by the application layer to confirm that the long write operation is succeeded.

In response to the Prepare Write Request GATT server shall send an Error Response if

GATT Client has insufficient authentication to write the requested characteristic value OR
GATT Client has insufficient authorization to write the requested characteristic value OR
GATT Client has insufficient encryption to write the requested characteristic value OR
GATT Client has used insufficient encryption key size OR
Write operation is not permitted on the requested Characteristic Value OR
GATT server does not have sufficient space to queue this request.

In response to Execute Write Request, GATT server shall send an Error Response if

The prepared attribute value exceeds the maximum length of attribute value OR
The prepare value offset is greater than the current length of the attribute value The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, this function results in following events at the GATT Server's end.

CY_BLE_EVT_GATTS_PREP_WRITE_REQ - event for Prepare Write Request.
CY_BLE_EVT_GATTS_EXEC_WRITE_REQ - event for Execute Write Request.
CY_BLE_EVT_MEMORY_REQUEST - Need confirmation from NPAL.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.9.5 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_reliable_write_req_t. Since more than one writes are performed 'param' and all associated variables need to be retained in memory by the calling application until the GATT Reliable Write operation is completed successfully. param->handleValOffsetPair: array of type 'cy_stc_ble_gatt_handle_value_offset_param_t', which contains the values to be written, has to be specified. param->numOfRequests: Number of requests. That is, the count of array of structures of type cy_stc_ble_gatt_handle_value_offset_param_t. Each array element represents a value and the attribute to which the value has to be written.

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 'param' or 'handleValOffsetPair' is NULL or 'connHandle' is invalid, or if 'numOfRequests' is zero.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_WriteLongCharacteristicDescriptors()

cy_en_ble_api_result_t Cy_BLE_GATTC_WriteLongCharacteristicDescriptors ( cy_stc_ble_gattc_prep_write_req_t * param )

This function is used by the GATT Client application to write a characteristic descriptor value to a GATT Server when the GATT Client application knows the characteristic descriptor handle but the length of the characteristic descriptor value is longer than what can be sent in a single Write Request Attribute Protocol message.

This is a non-blocking function.

Internally, multiple Prepare Write Requests are sent to the GATT Server, in response to which Prepare Write Responses are received. No events are generated by the BLE Stack for these Responses.

Prepare Write Requests are repeated until the complete descriptor value has been transferred to the GATT Server, after which an Execute Write Request is sent to the GATT Server to write the initially transferred value at the GATT Server's end.

If the write operation is successful, GATT Server sends an Execute Write Response. This response results in CY_BLE_EVT_GATTC_EXEC_WRITE_RSP event at the GATT Client application. The value associated with this event has to be checked by the application layer to confirm that the long write operation is succeeded.

In response to the Prepare Write Request GATT server shall send an Error Response if

GATT Client has insufficient authentication to write the requested descriptor value OR
GATT Client has insufficient authorization to write the requested descriptor value OR
GATT Client has insufficient encryption to write the requested descriptor value OR
GATT Client has used insufficient encryption key size OR
Write operation is not permitted on the requested descriptor value OR
GATT server does not have sufficient space to queue this request.

In response to Execute Write Request, GATT server shall send an Error Response if

The prepared attribute value exceeds the maximum length of attribute value OR
The prepare value offset is greater than the current length of the attribute value The Error Code parameter is set as specified in the Attribute Protocol. This Error response results in CY_BLE_EVT_GATTC_ERROR_RSP event at the GATT client application.

If the peer GATT Server is a PSoC 6 MCU, this function results in following events at the GATT Server's end.

CY_BLE_EVT_GATTS_PREP_WRITE_REQ - event for Prepare Write Request.
CY_BLE_EVT_GATTS_EXEC_WRITE_REQ - event for Execute Write Request.
CY_BLE_EVT_MEMORY_REQUEST - Need confirmation from NPAL.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.12.4 for more details on the sequence of operations.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_prep_write_req_t, where 'param->value.val' points to the actual data to be written. 'param' and all associated variables must be retained in memory by the calling application until the GATT Write Long Characteristic Value operation is completed successfully.

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 'param' is NULL or 'connHandle' is invalid, or if 'attrHandle' is zero.
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_SendExecuteWriteReq()

cy_en_ble_api_result_t Cy_BLE_GATTC_SendExecuteWriteReq ( cy_stc_ble_gattc_exec_write_req_t * param )

This function is used by the GATT Client application to send execute write request to peer GATT Server.

This function should be called if client has previously initiated long/reliable write operation but GATT Client has received error response from GATT Server. Using this function GATT client application can request to cancel all the pending prepare write requests on GATT Server.

In response to this request, GATT server sends Execute Write Response. This response results in CY_BLE_EVT_GATTC_EXEC_WRITE_RSP event at the GATT Client application.

If the peer GATT Server is a PSoC 6 MCU, Execute Write Request PDU results in CY_BLE_EVT_GATTS_EXEC_WRITE_REQ event at the GATT Server's end.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_exec_write_req_t. param->connHandle: Connection handle to identify the peer GATT entity of type cy_stc_ble_conn_handle_t. param->flag: Indicates whether Queued Write is to be executed (0x01) or canceled (0x00)

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 '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_GATTC_WriteWithoutResponse()

cy_en_ble_api_result_t Cy_BLE_GATTC_WriteWithoutResponse ( cy_stc_ble_gattc_write_cmd_req_t * param )

This function is used by the GATT Client application to do a Write Without Response procedure on a Characteristic in the peer GATT Server.

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

Internally, Write Command is sent to the GATT Server and nothing is received in response from the GATT Server.

Refer to Bluetooth 5.0 core specification, Volume 3, Part G, section 4.9.1 for more details on the sequence of operations.

If the peer GATT server is a PSoC 6 MCU, Write Without Response PDU results in CY_BLE_EVT_GATTS_WRITE_CMD_REQ event GATT Server's end.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_write_req_t. Where, the following needs to be set: param->handleValPair param->connHandle

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 'param' is NULL or 'connHandle' is invalid, or if 'attrHandle' is zero or if 'param->handleValPair.value.len' value is greater than (Effective GATT MTU-3).
CY_BLE_ERROR_INVALID_OPERATION	This operation is not permitted.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

◆ Cy_BLE_GATTC_SignedWriteWithoutRsp()

cy_en_ble_api_result_t Cy_BLE_GATTC_SignedWriteWithoutRsp ( cy_stc_ble_gattc_signed_write_cmd_req_t * param )

This function is used by the GATT Client application to write a specific characteristic value when the ATT bearer is not encrypted.

This procedure shall be used only if the Characteristic Properties authenticated bit is enabled and the GATT client and GATT server devices share a bond as defined in Bluetooth Spec 5.0 [Vol. 3] Part C, Generic Access Profile. This is a blocking function. No event is generated on calling this function.

This function only writes the first (GATT_MTU - 15) octets of an Attribute Value. This function cannot be used to write a long Attribute.

Internally, Signed Write Command is used. Refer to Bluetooth Spec 5.0 Security Manager [Vol. 3] Part H, Section 2.4.5.

If the authenticated Characteristic Value that is written is the wrong size, has an invalid value as defined by the profile, or the signed value does not authenticate the client, then the write shall not succeed and no error shall be generated by the server.

If peer GATT server is a PSoC 6 device, Signed Write Without Response PDU results in CY_BLE_EVT_GATTS_DATA_SIGNED_CMD_REQ event at the GATT Server's end.

Parameters

param Pointer to a variable of type cy_stc_ble_gattc_write_req_t. Where, the following needs to be set: param->handleValPair param->connHandle

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 'param' is NULL or if 'attrHandle' is zero.
CY_BLE_ERROR_NO_DEVICE_ENTITY	'connHandle.bdHandle' value does not represent any existing entry in the Stack.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.
CY_BLE_ERROR_INSUFFICIENT_RESOURCES	BLE Stack resources are unavailable.

General Description

Functions

Function Documentation

◆ Cy_BLE_GATTC_StartDiscovery()

◆ Cy_BLE_GATTC_StartPartialDiscovery()

◆ Cy_BLE_GATTC_SendConfirmation()

◆ Cy_BLE_GATTC_StopCmd()

◆ Cy_BLE_GATTC_ExchangeMtuReq()

◆ Cy_BLE_GATTC_DiscoverPrimaryServices()

◆ Cy_BLE_GATTC_DiscoverPrimaryServiceByUuid()

◆ Cy_BLE_GATTC_DiscoverCharacteristics()

◆ Cy_BLE_GATTC_DiscoverCharacteristicByUuid()

◆ Cy_BLE_GATTC_DiscoverCharacteristicDescriptors()

◆ Cy_BLE_GATTC_FindIncludedServices()

◆ Cy_BLE_GATTC_ReadByTypeReq()

◆ Cy_BLE_GATTC_ReadCharacteristicValue()

◆ Cy_BLE_GATTC_ReadUsingCharacteristicUuid()

◆ Cy_BLE_GATTC_ReadLongCharacteristicValues()

◆ Cy_BLE_GATTC_ReadMultipleCharacteristicValues()

◆ Cy_BLE_GATTC_ReadCharacteristicDescriptors()

◆ Cy_BLE_GATTC_ReadLongCharacteristicDescriptors()

◆ Cy_BLE_GATTC_WriteCharacteristicValue()

◆ Cy_BLE_GATTC_WriteCharacteristicDescriptors()

◆ Cy_BLE_GATTC_WriteLongCharacteristicValues()

◆ Cy_BLE_GATTC_ReliableWrites()

◆ Cy_BLE_GATTC_WriteLongCharacteristicDescriptors()

◆ Cy_BLE_GATTC_SendExecuteWriteReq()

◆ Cy_BLE_GATTC_WriteWithoutResponse()

◆ Cy_BLE_GATTC_SignedWriteWithoutRsp()