GattClient Class Reference

Discover characteristic descriptors of a characteristic.

If descriptors are found within the range provided then the server should reply with a FindInformationResponse containing a list of attribute_handle_t, UUID pairs where the attribute handle is the descriptor handle and UUID is the UUID of the descriptor.

The procedure is complete when the server send an ErrorResponse with the error code ATTRIBUTE_NOT_FOUND or the FindInformationResponse has an attribute handle that is equal to the end handle of the discovery range.

Note:

This function realize a partial implementation of the Discover All Characteristics Descriptors procedure. The complete implementation of the procedure is realized at an higher level.

This function issue a Find Information ATT request..

BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.7.1

It should be possible to use this function to issue a regular ATT Find Information Request.

Parameters:

connection	The handle of the connection to send this request to.
descriptors_discovery_range	The range of attributes where the descriptors are discovered. The first handle shall be no less than the characteristic value handle plus one and the last handle shall be no more than the last handle of the characteristic.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Find characteristic declarations within a service definition.

If characteristic declarations are found within the range then the server should reply with a ReadByTypeResponse where for each attribute record:

• attribute_handle is the handle of the characteristic definition
• attribute_data contains the the following values attached to the characteristic : + properties: the properties of the characteristic. + value handle: the handle of the value of the characteristic. + uuid: the UUID of the characteristic.

The procedure is considered complete when the server send an ErrorResponse with the ErrorCode set to ATTRIBUTE_NOT_FOUND or a ReadByType response has an attribute_handle set to the end of the discovery range.

If the procedure is not complete after a server response, it should be relaunched with an updated range starting at the last attribute_handle discovered plus one.

Note:

This function realize a partial implementation of the Discover All Characteristics of a Service procedure. The complete implementation of the procedure is realized at an higher level.

This function issue a Read By Type ATT request where the type parameter is equal to Characteristic.

BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.6.1

The GATT procedure Discover Characteristics by UUID is implemented at a higher level using this function as a base.

Parameters:

connection	The handle of the connection to send this request to.
discovery_range	The range of attributes where the characteristics are discovered. It should be contained within a service.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Discover primary services in the range [begin - 0xFFFF].

If services exists in the range provided, the server will reply with a ReadByGoupType response where for each attribute_data exposed:

• attribute_handle is the service attribute handle
• end_group_handle is the last handle of the service
• attribute_value is the UUID of the service.

If the end of the range is not reached, this procedure can be relaunched with the last handle of the last service discovered plus one as the beginning of the discovery range.

If there is not services left to discover in the range, the server can either: * Reply with an ErrorResponse with the Error code set to ATTRIBUTE_NOT_FOUND * Set the end handle of the last service to 0xFFFF.

Note:

This function realize a partial implementation of the Discover All Primary Services procedure. The complete implementation of the procedure is realized at an higher level.

This function issue a Read By Group Type ATT request where the type parameter is equal to Primary Service and the Ending Handle parameter is equal to 0xFFFF.

BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.4.1

Parameters:

connection	The handle of the connection to send this request to.
begin	The beginning of the discovery range.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Discover primary services by UUID in the range [discovery_range_begining - 0xFFFF].

If services exists in the range provided, the server will reply with a FindByTypeValueResponse containing the attribute range of each service discovered.

If the end of the range is not reached, this procedure can be relaunched with the last handle of the last service discovered plus one as the beginning of the discovery range.

If there is not services left to discover in the range, the server can either: * Reply with an ErrorResponse with the Error code set to ATTRIBUTE_NOT_FOUND * Set the end handle of the last service to 0xFFFF.

Note:

This function realize a partial implementation of the Discover Primary Service by Service UUID procedure. The complete implementation of the procedure is realized at an higher level.

This function issue a Find By Type Value ATT request where the type parameter is equal to Primary Service and the Ending Handle parameter is equal to 0xFFFF.

BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.4.2

Parameters:

connection	The handle of the connection to send this request to.
begin	The beginning of the discovery range.
uuid	The UUID of the service to discover.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Negotiate the mtu to use by this connection.

First the client send to the server the maximum rx mtu that it can receive then the client reply with the maximum rx mtu it can receive. The mtu chosen for the connection is the minimum of the client Rx mtu and server Rx mtu values.

If an error occurred then the mtu used remains the default value.

The server will reply to this request with an AttExchangeMTUResponse in case of success or AttErrorResponse in case of failure.

Note:

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.3.1

Parameters:

connection

The handle of the connection to send this request to.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Send a request to the server to execute the queue of prepared write requests.

The server should respond with an ExecuteWriteResponse in case of success and an Error response in case of failure.

Note:

This function issue an ATT Execute Write Request.

: This function is one of the base function for the Write Long Characteristic Value and Reliable Writes GATT procedures.

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.4

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.5

Parameters:

connection_handle	The handle of the connection to send this request to.
execute	If true, execute the write request queue otherwise cancel it.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Find included services within a service.

If services are included in the service range then the server will reply with a ReadByTypeResponse where for each attribute record:

• attribute_handle The handle where the service is included within the service definition.
• attribute_data Contains two handles defining the range of the included. If the service found have a 16 bit uuid then its UUID is also included in the attribute data.

If the end of the service range is not reached, this procedure can be relaunched with the handle of the last included service discovered plus one as the beginning of the new discovery range.

The procedure is complete when either:

• The server reply with an ErrorResponse with the Error code set to ATTRIBUTE_NOT_FOUND
• An included service handle returned is equal to the end of the range.

If the service UUID is a 128 bits one then it is necessary to issue a read attribute request on the first handle of the service discovered to get it.

Note:

This function realize a partial implementation of the Find Included Services procedure. The complete implementation of the procedure is realized at an higher level.

This function issue a Read By Type ATT request where the type parameter is equal to Include.

BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.5.1

Parameters:

connection	The handle of the connection to send this request to.
service_range	The range of the service where service inclusion has to be discovered.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Acquire the size of the mtu for a given connection.

Parameters:

connection	The handle of the connection for which the the MTU size should be acquired.
mtu_size	Output parameter which will contain the MTU size.

Returns:

BLE_ERROR_NONE if the MTU size has been acquired or the appropriate error otherwise.

Implemented in AttClientToGattClientAdapter.

Initialisation of the instance.

An implementation can use this function to initialise the subsystems needed to realize the operations of this interface.

This function has to be called before any other operations.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Implemented in AttClientToGattClientAdapter.

Upon server message reception an implementation shall call this function.

Parameters:

connection_handle	The handle of the connection which has received the server message.
server_message	The message received from the server.

Definition at line 597 of file PalGattClient.h.

Upon transaction timeout an implementation shall call this function.

Parameters:

connection_handle

The handle of the connection of the transaction which has times out.

Note:

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part F Section 3.3.3

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.4.14

Definition at line 615 of file PalGattClient.h.

Send a prepare write request to the server.

The write request will go into a queue until the client execute or cancel the request with an execute write request which will write all the values in the queue atomically.

The server should respond with a PrepareWriteResponse containing the content of the request in case of success and an ErrorResponse in case of error.

If an ErrorResponse is received it doesn't invalidate what is already in the queue.

Note:

This function issue an ATT Prepare Write Request.

: This function is one of the base function for the Write Long Characteristic Value and Reliable Writes GATT procedures.

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.4

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.5

Parameters:

connection_handle	The handle of the connection to send this request to.
attribute_handle	Handle of the attribute to write.
value	The value to write.
offset	offset where the value should be written.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Read a partial value of an attribute.

The server will respond with a ReadBlobResponse containing the data read or an ErrorResponse in case of error.

The procedure is not complete as long as the value in response have the same size as the mtu minus one. If the procedure is not complete, it can be launch again with an updated offset to read the remaining part of the attribute value.

Note:

This function issue an ATT Read Blob Request.

: This function is the base function for the Read Long Characteristic Value and Read Long Characteristic Descriptor GATT procedures.

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.8.3

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.12.2

Parameters:

connection_handle	The handle of the connection to send this request to.
attribute_handle	Handle of the attribute to read.
offset	Beginning offset for the read operation.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Read the value of an attribute.

The server will reply with an AttReadResponse. In case of error, the server will reply with an AttErrorResponse.

Note:

This function issue an ATT Read Request.

: This function is the base function for the read Characteristic Value and Read Characteristic Descriptor GATT procedures. It can also be used to read the 128 bit UUID of a service discovered with find_included_service.

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.8.1

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.12.1

Parameters:

connection	The handle of the connection to send this request to.
attribute_handle	Handle of the attribute to read.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Read atomically multiple characteristics values.

The server will respond with a ReadMultiple response containing the concatenation of the values of the characteristics.

Note:

values might be truncated

In case of error, the server should respond a with an ErrorResponse.

Note:

This function issue an ATT Read Multiple Request.

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.8.4

Parameters:

connection_handle	The handle of the connection to send this request to.
characteristic_value_handles	Handle of the characteristic values to read.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Read a characteristic value using its UUID (type).

The server will respond a ReadByTypeResponse containing a sequence of attribute handle and attribute value pairs. To read remaining attributes, the client should launch a new request with an updated range.

The procedure is considered complete when the server respond with an ErrorResponse containing the ErrorCode ATTRIBUTE_NOT_FOUND or when an handle in the ReadByTypeResponse is equal to the end of the discovered range.

Note:

This function realize a partial implementation of the Read Using Characteristics Characteristic procedure. The complete implementation of the procedure is realized at an higher level.

This function issue a Read By Type ATT request.

BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.8.2

It should be possible to use this function to issue a regular ATT Read By Type Request.

Parameters:

connection	The handle of the connection to send this request to.
attribute_range	Range of the handle where an attribute with uuid as type is present.
uuid	UUID of the characteristic(s) to read.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Send a Signed Write without Response command to the server.

Note:

This function issue an ATT Write Command with the signed flag and the signature.

signature is calculated by the stack.

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.2

Parameters:

connection_handle	The handle of the connection to send this request to.
attribute_handle	Handle of the attribute to write.
value	The value to write.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Termination of the instance.

An implementation can use this function to release the subsystems initialised to realise the operations of this interface.

After a call to this function, initialise should be called again to allow usage of the interface.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Implemented in AttClientToGattClientAdapter.

Register a callback which will handle messages from the server.

Parameters:

cb	The callback object which will handle messages from the server. It accept two parameters in input: The handle of the connection where the message was received and the message received. Real type of the message can be obtained from its opcode.

Definition at line 562 of file PalGattClient.h.

Register a callback handling transaction timeout.

Parameters:

cb	The callback handling timeout of a transaction. It accepts as a parameter the connection handle involved in the timeout.

Note:

No more attribute protocol requests, commands, indication or notification shall be sent over a connection implied in a transaction timeout. To send a new ATT message, the conenction should be reestablished.

Definition at line 579 of file PalGattClient.h.

Send a write request to the server.

The server should respond with a WriteResponse in case of success or an ErrorResponse in case of error.

Note:

This function issue an ATT Write Request.

: This function is the base function for the Write Characteristic Value and Write Characteristic Descriptors GATT procedures.

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.3

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.12.3

Parameters:

connection_handle	The handle of the connection to send this request to.
attribute_handle	Handle of the attribute to write.
value	The value to write.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.

Send a write command to the server.

Note:

This function issue an ATT Write Command.

see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part G Section 4.9.1

Parameters:

connection_handle	The handle of the connection to send this request to.
attribute_handle	Handle of the attribute to write.
value	The value to write.

Returns:

BLE_ERROR_NONE or an appropriate error.

Implemented in AttClientToGattClientAdapter.