Shutdown event handler.

See also

GattClient::onShutdown().

Definition at line 222 of file GattClient.h.

Callchain of shutdown event handlers.

See also

to GattClient::onShutown().

Definition at line 231 of file GattClient.h.

Handle value notification/indication event handler.

See also

to GattClient::onHVX().

Definition at line 206 of file GattClient.h.

Callchain of handle value notification/indication event handlers.

See also

GattClient::onHVX().

Definition at line 214 of file GattClient.h.

Attribute read event handler.

See also

GattClient::onDataRead().

Deprecated:

Use the version in global ble namespace.

Definition at line 143 of file GattClient.h.

Callchain of attribute read event handlers.

Deprecated:

Use the version in global ble namespace.

Definition at line 150 of file GattClient.h.

Attribute write event handler.ble::WriteCallback_t.

See also

GattClient::onDataWrite().

Deprecated:

Use the version in global ble namespace.

Definition at line 189 of file GattClient.h.

Callchain of attribute write event handlers.

See also

GattClient::onDataWrite().

Deprecated:

Use the version in global ble namespace.

Definition at line 198 of file GattClient.h.

GATT write operations.

Definition at line 155 of file GattClient.h.

Initiate the descriptor discovery procedure for a given characteristic.

When a descriptor is discovered the discovered descriptor is forwarded to discoveryCallback. After the discovery of all the descriptors, the procedure ends and send a descriptor discovery termination event to termination callback.

Application code may monitor the discovery process by querying its status with isCharacteristicDescriptorDiscoveryActive(). It can also end the discovery process by calling terminateCharacteristicDescriptorDiscovery().

Parameters

[in]	characteristic	The characteristic owning the descriptors to discover.
[in]	discoveryCallback	Handle descriptor discovered events for the duration of the procedure.
[in]	terminationCallback	Handle descriptor discovery termination event of the procedure.

Returns

BLE_ERROR_NONE if the characteristic descriptor discovery procedure has been launched successfully otherwise an appropriate error.

Launch the service discovery procedure of a GATT server peer.

The procedure invokes the application callback for matching services. The process ends after all the services present on the distant GATT server have been discovered. Termination callbacks registered with onServiceDiscoveryTermination() are invoked to notify the application of the termination of the procedure.

Application code can track the status of the procedure by invoking the function isServiceDiscoveryActive(), which returns true if the procedure is ongoing.

At any point, application code can prematurely terminate the discovery procedure by calling terminateServiceDiscovery().

Parameters

[in]	connectionHandle	Handle of the connection with the peer GATT server.
[in]	callback	Service discovered event handler invoked when a matching service has been discovered. This parameter may be NULL.
[in]	matchingServiceUUID	UUID of the service the caller is interested in. If a service discovered matches this filter, then sc is invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard, which can be used to discover all services present on the peer GATT server.

Returns

BLE_ERROR_NONE if the discovery procedure has been successfully started and an appropriate error otherwise.

Launch the service discovery procedure of a GATT server peer.

The process ends after all the services present in the attribute range startHandle to endHandle have been discovered.

Termination callbacks registered with onServiceDiscoveryTermination() are invoked to notify the application of the termination of the procedure.

Application code can track the status of the procedure by invoking the function isServiceDiscoveryActive(), which returns true if the procedure is ongoing.

At any point, application code can prematurely terminate the discovery procedure by calling terminateServiceDiscovery().

Parameters

[in]	connectionHandle	Handle of the connection with the peer GATT server.
[in]	callback	Service discovered event handler invoked when a matching service has been discovered. This parameter may be NULL.
[in]	startHandle	First attribute handle of the discovery range.
[in]	endHandle	end Lasr attribute handle of the discovery range.

Returns

BLE_ERROR_NONE if the discovery procedure has been successfully started and an appropriate error otherwise.

Query status of the descriptor discovery procedure for a given characteristic.

Parameters

[in]

characteristic

The characteristic concerned by the descriptors discovery.

Returns

true if a descriptors discovery is active for the characteristic in input otherwise false.

Check if the service discovery procedure is currently active.

Returns

true if service discovery procedure is active and false otherwise.

Launch the service and characteristic discovery procedure of a GATT server peer.

The procedure invokes application callbacks for matching services or characteristics. The process ends after all the services and characteristics present on the distant GATT server have been discovered. Termination callbacks registered with onServiceDiscoveryTermination() are invoked to notify the application of the termination of the procedure.

Application code can track the status of the procedure by invoking the function isServiceDiscoveryActive(), which returns true if the procedure is ongoing.

At any point, application code can prematurely terminate the discovery procedure by calling terminateServiceDiscovery().

Parameters

[in]	connectionHandle	Handle of the connection with the peer GATT server.
[in]	sc	Service discovered event handler invoked when a matching service has been discovered. This parameter may be NULL.
[in]	cc	Characteristic discovered event handler invoked when a matching characteristic has been found. This parameter may be NULL.
[in]	matchingServiceUUID	UUID of the service the caller is interested in. If a service discovered matches this filter, then sc is invoked with it. The special value BLE_UUID_UNKNOWN acts as a wildcard, which can be used to discover all services present on the peer GATT server.
[in]	matchingCharacteristicUUIDIn	UUID of the characteristic the caller is interested in. If a characteristic discovered matches this filter, then cc is invoked with it. The special value BLE_UUID_UNKNOWN acts as a wildcard, which can be used to discover all services present on the peer GATT server.

Discovery procedure implementation detail

It is recommended to implement several strategies based on the combination of callbacks and filters passed in input to efficiently realize the discovery procedure:

• If sc and cc are NULL, then it is not necessay to initiate any discovery, and the termination handlers can be invoked immediately.
• If matchingServiceUUID is set, then the GATT discover services by service UUID procedure should be used; otherwise, the GATT discover primary services procedure should be used.
• If cc is NULL, then the discovery process should end after the discovery of the services.

Returns

BLE_ERROR_NONE if the discovery procedure has been successfully started and an appropriate error otherwise.

Trigger MTU negotiation.

This might result in a Gap event onAttMtuChange being called if MTU changes.

Note

This does not guarantee a change in MTU size. If size remains unchanged no event will be generated.

Parameters

connection

Connection on which the MTU is to be negotiated.

Returns

BLE_ERROR_NONE if the procedure has been launched successfully otherwise an appropriate error.

Register an attribute read event handler.

Note

It is possible to unregister a callback using onDataRead().detach(callbackToRemove).

Parameters

[in]

callback

Event handler being registered.

Get the callchain of attribute read event handlers.

Returns

A reference to the read event callback chain.

Note

It is possible to register new handlers using onDataRead().add(callback).

It is possible to unregister an handler by using onDataRead().detach(callback).

Register an attribute write event handler.

Parameters

[in]

callback

Event handler being registered.

Note

It is possible to remove registered handlers using onDataWritten().detach(callbackToRemove).

Write commands (issued using writeWoResponse) don't generate a response.

Get the callchain of attribute write event handlers.

Returns

A reference to the data written callbacks chain.

Note

It is possible to register new handlers by using onDataWritten().add(callback).

It is possible to unregister an handler by using onDataWritten().detach(callback).

Register an handler for Handle Value Notification/Indication events.

Parameters

callback

Event handler to register.

Note

It is possible to unregister a callback by using onHVX().detach(callbackToRemove).

provide access to the callchain of HVX callbacks.

Returns

A reference to the HVX callbacks chain.

Note

It is possible to register callbacks using onHVX().add(callback).

It is possible to unregister callbacks using onHVX().detach(callback).

Register a service discovery termination event handler.

Parameters

[in]

callback

Event handler being registered.

Register a shutdown event handler.

The registered handler is invoked when the GattClient instance is about to be shut down.

Parameters

[in]

callback

Event handler to invoke when a shutdown event is available.

Note

onShutdown().detach(callback) may be used to unregister a given callback.

See also

BLE::shutdown()

Register a shutdown event handler.

The registered handler is invoked when the GattClient instance is about to be shut down.

Parameters

[in]	objPtr	Instance that will be used to invoke memberPtr.
[in]	memberPtr	Event handler to invoke when a shutdown event is available.

Definition at line 630 of file GattClient.h.

Get the callchain of shutdown event handlers.

Returns

A reference to the shutdown event callbacks chain.

Note

onShutdown().add(callback) may be used to register new handlers.

onShutdown().detach(callback) may be used to unregister an handler.

Forward a handle value notification or indication event to all registered handlers.

Attention

This function is meant to be called from the vendor implementation when a notification or indication event is available.

Parameters

[in]

params

Notification or Indication event to pass to the registered handlers.

Forward an attribute read event to all registered handlers.

Attention

This function is meant to be called from the vendor implementation when an attribute read event occurs.

Parameters

[in]

params

Attribute read event to pass to the registered handlers.

Forward an attribute written event to all registered handlers.

Attention

This function is meant to be called from the vendor implementation when an attribute written event occurs.

Parameters

[in]

params

Attribute written event to pass to the registered handlers.

Initiate the read procedure of an attribute handle.

Once the attribute value has been read in its entirety, the process issues an attribute read event and passes it to all events handlers registered by onDataRead.

Parameters

[in]	connHandle	Handle of the connection used to send the read request.
[in]	attributeHandle	Handle of the attribute to read data from.
[in]	offset	The offset from the start of the attribute value to be read.

Returns

BLE_ERROR_NONE if read procedure successfully started.

Implementation notes:

Reading the attribute value in its entirety may involve sending several GATT requests to the peer. The following algorithm may be used to implement the process:

If the offset is equal to 0, then send a read request; otherwise, send a read blob request at the specified offset.

While the attribute data in the response are MTU - 1 long:

• Concat the response to the value containing the previous responses.
• Increment the value of the offset by MTU - 1.
• Send a read blob request with the updated offset.

Finally, concat the last response with the value containing all the previous responses and forward that value to the event handlers.

Reset the state of the GattClient instance.

Prior to any state modification, shutdown event handlers are notified that the GattClient instance is about to be shut down. Then, running procedures end. Finally, the state of the instance is reset.

implementation note

This function is meant to be overridden in the platform-specific subclass. Nevertheless, the subclass only resets its state and not the data held in GattClient members. This is achieved by a call to GattClient::reset() from the subclass' reset() implementation.

Returns

BLE_ERROR_NONE on success.

Assign the event handler implementation that will be used by the module to signal events back to the application.

Parameters

handler

Application implementation of an EventHandler.

Terminate an ongoing characteristic descriptor discovery procedure.

If the procedure is active, then it ends, and the termination handler associated with the procedure is called.

Parameters

[in]

characteristic

The characteristic containing the descriptors being discovered.

Terminate all ongoing service discovery procedures.

It results in an invocation of the service discovery termination handler registered with onServiceDiscoveryTermination().

Initiate a write procedure on an attribute value.

If cmd is equal to GATT_OP_WRITE_REQ, then the status of the operation is reported to the event handlers registered through onDataWritten().

Parameters

[in]	cmd	Type of the write procedure used. If GATT_OP_WRITE_CMD is set, then value length is not greater than the size of the mtu of connHandle minus three.
[in]	connHandle	Handle of the connection used to send the write request or command.
[in]	attributeHandle	Handle of the attribute value to write.
[in]	length	Number of bytes present in value.
[in]	value	Data buffer to write to attributeHandle.

Returns

BLE_ERROR_NONE if the write procedure successfully started.

Implementation notes:

If the operation is a write command, then an implementation uses the GATT write without response procedure and an error is returned if the data buffer to write is larger than the size of the MTU - 3.

If the operation is a write command and the size of the data buffer to write is less than than the size of the MTU - 3, then the ATT write request procedure is used, and the response is reported to the handlers listening for write response.

Otherwise, the data buffer to write is divided in chunks with a maximum size of MTU - 5. Those chunks are sent sequentially to the peer in ATT prepare write requests. If an error response is received during the process, the procedure ends immediately, the prepared write is discarded and an error is reported to the application handlers. Once all the chunks have been sent, the transaction is completed by sending an execute write request to the peer. The peer response is forwarded to the application handlers.