Mistake on this page?
Report an issue in GitHub or email us
Public Types | Public Member Functions | Protected Attributes
ServiceDiscovery Class Referenceabstract

Host callback types needed by the service discovery procedure. More...

#include <ServiceDiscovery.h>

Public Types

typedef FunctionPointerWithContext< const DiscoveredService * > ServiceCallback_t
 Service discovered event handler. More...
 
typedef FunctionPointerWithContext< const DiscoveredCharacteristic * > CharacteristicCallback_t
 Characteristic discovered event handler. More...
 
typedef FunctionPointerWithContext< ble::connection_handle_tTerminationCallback_t
 Service discovery ended event. More...
 

Public Member Functions

virtual ble_error_t launch (ble::connection_handle_t connectionHandle, ServiceCallback_t sc=nullptr, CharacteristicCallback_t cc=nullptr, const UUID &matchingServiceUUID=UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN), const UUID &matchingCharacteristicUUIDIn=UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN))=0
 Launch service discovery. More...
 
virtual bool isActive () const =0
 Check whether service-discovery is currently active. More...
 
virtual void terminate ()=0
 Terminate an ongoing service discovery. More...
 
virtual void onTermination (TerminationCallback_t callback)=0
 Set up a callback to be invoked when service discovery is terminated. More...
 
virtual ble_error_t reset ()
 Clear all ServiceDiscovery state of the associated object. More...
 

Protected Attributes

ble::connection_handle_t connHandle
 Connection handle as provided by the SoftDevice. More...
 
UUID matchingServiceUUID
 UUID-based filter that specifies the service that the application is interested in. More...
 
ServiceCallback_t serviceCallback
 The registered callback handle for when a matching service is found during service-discovery. More...
 
UUID matchingCharacteristicUUID
 UUID-based filter that specifies the characteristic that the application is interested in. More...
 
CharacteristicCallback_t characteristicCallback
 The registered callback handler for when a matching characteristic is found during service-discovery. More...
 

Detailed Description

Host callback types needed by the service discovery procedure.

This class is also an interface that may be used in vendor port to model the service discovery process. This interface is not used in user code.

Attention
Implementing this interface is not a requirement for the implementation of the service discover process.

Definition at line 47 of file gatt/ServiceDiscovery.h.

Member Typedef Documentation

Characteristic discovered event handler.

The callback accepts a pointer to a DiscoveredCharacteristic as parameter.

Attention
The argument passed to the callback may not persist after the callback invocation; therefore, the callbacks must make a shallow copy of the DiscoveredCharacteristic passed as parameter to access its value beyond the callback scope.

Definition at line 74 of file gatt/ServiceDiscovery.h.

Service discovered event handler.

The callback accepts a pointer to a DiscoveredService as parameter.

Attention
The argument passed to the callback may not persist after the callback invocation; therefore, the callbacks must make a shallow copy of the DiscoveredService passed as parameter to access its value beyond the callback scope.

Definition at line 60 of file gatt/ServiceDiscovery.h.

Service discovery ended event.

The callback accepts a connection handle as parameter. This parameter is used to identify on which connection the service discovery process ended.

Definition at line 83 of file gatt/ServiceDiscovery.h.

Member Function Documentation

virtual bool isActive ( ) const
pure virtual

Check whether service-discovery is currently active.

virtual ble_error_t launch ( ble::connection_handle_t  connectionHandle,
ServiceCallback_t  sc = nullptr,
CharacteristicCallback_t  cc = nullptr,
const UUID matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
const UUID matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN) 
)
pure virtual

Launch service discovery.

Once launched, service discovery remains active with callbacks being issued back into the application for matching services or characteristics. isActive() can be used to determine status, and a termination callback (if set up) is invoked at the end. Service discovery can be terminated prematurely, if needed, using terminate().

Parameters
connectionHandleHandle for the connection with the peer.
scThis is the application callback for a matching service. Taken as NULL by default. Note: service discovery may still be active when this callback is issued; calling asynchronous BLE-stack APIs from within this application callback might cause the stack to abort service discovery. If this becomes an issue, it may be better to make a local copy of the discoveredService and wait for service discovery to terminate before operating on the service.
ccThis is the application callback for a matching characteristic. Taken as NULL by default. Note: service discovery may still be active when this callback is issued; calling asynchronous BLE-stack APIs from within this application callback might cause the stack to abort service discovery. If this becomes an issue, it may be better to make a local copy of the discoveredCharacteristic and wait for service discovery to terminate before operating on the characteristic.
matchingServiceUUIDUUID-based filter for specifying a service in which the application is interested. By default, it is set as the wildcard UUID_UNKNOWN, in which case it matches all services. If characteristic-UUID filter (below) is set to the wildcard value, then a service callback is invoked for the matching service (or for every service if the service filter is a wildcard).
matchingCharacteristicUUIDInUUID-based filter for specifying a characteristic in which the application is interested. By default, it is set as the wildcard UUID_UKNOWN to match against any characteristic. If both service-UUID filter and characteristic-UUID filter are used with nonwildcard values, then only a single characteristic callback is invoked for the matching characteristic.
Note
Using wildcard values for both service-UUID and characteristic- UUID result in complete service discovery: callbacks being called for every service and characteristic.
Providing NULL for the characteristic callback results in characteristic discovery being skipped for each matching service. This allows for an inexpensive method to discover only services.
Returns
BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
virtual void onTermination ( TerminationCallback_t  callback)
pure virtual

Set up a callback to be invoked when service discovery is terminated.

virtual ble_error_t reset ( )
virtual

Clear all ServiceDiscovery state of the associated object.

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

Returns
BLE_ERROR_NONE on success.

Definition at line 173 of file gatt/ServiceDiscovery.h.

virtual void terminate ( )
pure virtual

Terminate an ongoing service discovery.

This should result in an invocation of the TerminationCallback if service discovery is active.

Field Documentation

CharacteristicCallback_t characteristicCallback
protected

The registered callback handler for when a matching characteristic is found during service-discovery.

Definition at line 207 of file gatt/ServiceDiscovery.h.

ble::connection_handle_t connHandle
protected

Connection handle as provided by the SoftDevice.

Definition at line 187 of file gatt/ServiceDiscovery.h.

UUID matchingCharacteristicUUID
protected

UUID-based filter that specifies the characteristic that the application is interested in.

Definition at line 202 of file gatt/ServiceDiscovery.h.

UUID matchingServiceUUID
protected

UUID-based filter that specifies the service that the application is interested in.

Definition at line 192 of file gatt/ServiceDiscovery.h.

ServiceCallback_t serviceCallback
protected

The registered callback handle for when a matching service is found during service-discovery.

Definition at line 197 of file gatt/ServiceDiscovery.h.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.