libhfp: BtHub Class Reference

List of all members.


Public Member Functions
	BtHub (DispatchInterface *eip)
	Standard constructor.
	~BtHub ()
	Standard destructor.
BtHci *	GetHci (void) const
	Query the HCI currently used by the Bluetooth system.
BtDevice *	DefaultDevFactory (bdaddr_t const &)
	Default factory method for BtDevice objects.
bool	AddService (BtService svcp, ErrorInfo error=0)
	Register a BtService derived service handler.
void	RemoveService (BtService *svcp)
	Unregister a BtService derived service handler.
bool	Start (ErrorInfo *error=0)
	Attempt to start the Bluetooth system.
void	Stop (void)
	Stop Bluetooth system.
bool	IsStarted (void)
	Query whether the Bluetooth system is started.
bool	GetAutoRestart (void) const
	Query whether Bluetooth auto-restart is enabled.
void	SetAutoRestart (bool autostart)
	Configure auto-restart of the Bluetooth system.
BtDevice *	GetDevice (bdaddr_t const &raddr, bool create=true)
	Look up and create a BtDevice object.
BtDevice *	GetDevice (const char *raddr, bool create=true)
	Look up and create a BtDevice object by Bluetooth address string.
BtDevice *	GetFirstDevice (void)
	Query the first enumerable Bluetooth device record.
BtDevice *	GetNextDevice (BtDevice *devp)
	Query the succeeding enumerable Bluetooth device record.
bool	StartInquiry (int timeout_ms=5000, ErrorInfo *error=0)
	Initiate an inquiry for discoverable Bluetooth devices.
void	StopInquiry (void)
	Halt and cancel an in-progress inquiry for discoverable Bluetooth devices.
bool	IsScanning (void) const
	Query whether a Bluetooth device inquiry is in progress.
Public Attributes
Callback< void, ErrorInfo * >	cb_NotifySystemState
	Notification that the Bluetooth system has stopped or restarted asynchronously.
Callback< BtDevice *, bdaddr_t const & >	cb_BtDeviceFactory
	Factory for BtDevice objects, implemented as a callback.
Callback< void, BtDevice , ErrorInfo >	cb_InquiryResult
	Notification of new inquiry result or completion of inquiry.

Detailed Description

BtHub implements single-instance Bluetooth-related functions including device list management, device inquiry, and service registration.

Each Bluetooth device is represented by a BtDevice object. The life cycle of BtDevice objects is described in the BtDevice Life Cycle section.

Hub Operation

Authentication is managed at the system level by the BlueZ hcid, and is beyond the scope of BtHub or BtDevice. At the connection level, it is possible to set policies for the system-level authentication be upheld, and this is not handled by either BtHub or BtDevice. See RfcommService::SetSecMode().

Constructor & Destructor Documentation

BtHub ( DispatchInterface * eip )

Standard constructor.

Parameters:

eip

Event dispatcher interface suitable for the environment in which BtHub is being used.

Note:: The Bluetooth system is not started by the constructor. The client must call Start() to initiate it, or enable the auto-restart mechanism with SetAutoRestart().

Member Function Documentation

BtHci* GetHci ( void ) const [inline]

Query the HCI currently used by the Bluetooth system.

The HCI object allows a number of special functions to be used, including querying the local address, the device class, and the SCO MTU.

Returns:: A pointer to the active BtHci object, or 0 if the Bluetooth service is stopped and an HCI is unavailable.

The libhfp Bluetooth subsystem will only actively attach to one HCI. While it is certainly possible to make use of multiple HCIs, there are some reasons that libhfp does not currently do this:

It is important to be able to notice collisions with other SCO listeners. Unfortunately, the kernel interfaces only return EADDRINUSE when attempting to bind a SCO socket to a specific local bdaddr. It also allows many listeners on BDADDR_ANY, but only delivers notifications to one of them.
Any registered SDP records that include RFCOMM channels would need to have the services listen on the same channel consistently across HCIs. For now, we only do this on one HCI.

bool AddService	(	BtService *	svcp,
		ErrorInfo *	error = `0`
	)

Parameters:

`[in]`	svcp	Service object to be registered. Must not currently be registered.
`[out]`	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

This function will add the svcp service object to the hub's list of registered services.

If the Bluetooth system is started -- see IsStarted(), an attempt will be made to start the service, and if unsuccessful, the registration will be aborted.

Return values:

	true	Service was successfully registered
	false	The Bluetooth system is in the started state, but the service could not be started. The service was not registered in this case.

void RemoveService ( BtService * svcp )

Unregister a BtService derived service handler.

Parameters:

svcp

Service object to be unregistered. Must be currently registered.

This function will remove its parameter service object from the hub's list of registered services.

If the Bluetooth system is started -- see IsStarted(), the service will be stopped before it is removed.

bool Start ( ErrorInfo * error = 0 )

Attempt to start the Bluetooth system.

The Bluetooth system has two components:

A connection to the local Service Discovery Protocol daemon
Worker threads to process asynchronous requests.

This function synchronously establishes both components.

Parameters:

[out] error Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	Bluetooth system started
	false	Bluetooth system could not be started for reasons that might include: No Bluetooth HCIs are connected The local SDP daemon is unavailable

Note:: This function never results in a call to BtHub::cb_NotifySystemState.

See also:: Stop(), IsStarted(), BtHub::cb_NotifySystemState

void Stop ( void )

Stop Bluetooth system.

If the Bluetooth system is started, this function will cause it to be stopped. The connection to the local Service Discovery Protocol daemon will be closed, and worker threads will be stopped.

Note:: This function performs a synchronous stop of the Bluetooth system and never results in a call to BtHub::cb_NotifySystemState.
This function will disable autorestart. See SetAutoRestart().

See also:: Start(), IsStarted()

bool IsStarted ( void ) [inline]

Query whether the Bluetooth system is started.

Return values:

	true	Bluetooth system is started
	false	Bluetooth system is not started

See also:: Start(), Stop(), BtHub::cb_NotifySystemState

void SetAutoRestart ( bool autostart )

Configure auto-restart of the Bluetooth system.

If the Bluetooth system is shut down, e.g. due to removal of the last Bluetooth HCI, auto-restart can automatically restart it if another Bluetooth HCI is connected.

Specifically, for hosts that use suspend/resume, where USB Bluetooth HCIs are effectively disconnected prior to suspend and reconnected following resume, the auto-reconnect feature can improve the resilience of the BtHub Bluetooth system.

Parameters:

autostart

true to enable auto-restart, false otherwise.

See also:: BtHub::cb_NotifySystemState, GetAutoRestart();

BtDevice * GetDevice	(	bdaddr_t const &	raddr,
		bool	create = `true`
	)

Look up and create a BtDevice object.

Parameters:

`[in]`	raddr	Address of remote Bluetooth device
	create	If no BtDevice object exists for the device, set this parameter to true to have a new one created.

Returns:: The BtDevice object associated with raddr, or NULL if no BtDevice object existed previously and create was set to false.

Note:: If a device is found or created successfully, it is returned with an additional reference added to it, to prevent it from being inadvertently destroyed as per life cycle management. The caller is responsible for releasing the reference with BtDevice::Put().

BtDevice * GetDevice	(	const char *	raddr,
		bool	create = `true`
	)

Look up and create a BtDevice object by Bluetooth address string.

This overload of GetDevice() is useful for configuration file parsing paths that create BtDevice objects for known devices. An ASCII hexadecimal Bluetooth address stored in a configuration file can be used directly by this routine.

Parameters:

`[in]`	raddr	Address of the device represented as a string, e.g. "00:07:61:D2:55:37" but not "Motorola" or "Logitech."
	create	If no BtDevice object exists for the device, set this parameter to true to have a new one created.

Returns:: The BtDevice object associated with raddr, or NULL if no BtDevice object existed previously and create was set to false.

Note:: If a device is found or created successfully, it is returned with an additional reference added to it, to prevent it from being inadvertently destroyed as per life cycle management. The caller is responsible for releasing the reference with BtDevice::Put().

Warning:: This function accepts a string representation of a Bluetooth address, e.g. "00:07:61:D2:55:37", NOT a Bluetooth name, e.g. "Motorola."
This function uses str2ba() to convert the string to a bdaddr_t, and malformed Bluetooth addresses are not reported.

BtDevice * GetFirstDevice ( void )

Query the first enumerable Bluetooth device record.

This interface, plus GetNextDevice(), permits clients to enumerate all known BtDevice objects. This can be useful for producing a list or globally applying a preference change.

Returns:: A pointer to the first BtDevice in enumeration order, or NULL if no BtDevice objects exist.

A Bluetooth device enumeration typically appears as:

        for (BtDevice *dev = hubp->GetFirstDevice();
             dev != NULL;
             dev = hubp->GetNextDevice(dev)) {
                // Do stuff with dev
        }

Warning:: The BtDevice object returned is not referenced. If the caller re-enters the event loop without adding a reference, the BtDevice may be destroyed, leaving the caller with a dangling pointer. See BtDevice life cycle management.

See also:: GetNextDevice()

BtDevice * GetNextDevice ( BtDevice * devp )

Query the succeeding enumerable Bluetooth device record.

Parameters:

devp

Pointer to preceding device

Returns:: The BtDevice object that is next in enumeration order relative to devp, or NULL if devp is the last device object in the enumeration order.

Warning:: The BtDevice object returned is not referenced. If the caller re-enters the event loop without adding a reference, the BtDevice may be destroyed, leaving the caller with a dangling pointer. See BtDevice life cycle management.

See also:: GetFirstDevice()

bool StartInquiry	(	int	timeout_ms = `5000`,
		ErrorInfo *	error = `0`
	)

Initiate an inquiry for discoverable Bluetooth devices.

This method begins the process of searching for discoverable Bluetooth devices.

If an inquiry is successfully initiated, any devices discovered will be reported through BtHub::cb_InquiryResult. The inquiry will persist for a fixed amount amount of time. Completion is signaled by invoking BtHub::cb_InquiryResult with the BtDevice pointer set to 0.

If the inquiry scan fails to start, either an error code will be returned from this method, or BtHub::cb_InquiryResult will be invoked after a short period of time with the BtDevice pointer set to 0, and an error code set as the second parameter.

Parameters:

`[in]`	timeout_ms	Time limit to place on inquiry. Longer time limits will increase the chance of finding discoverable devices, up to a point.
`[out]`	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Returns:: true if the inquiry has been initiated. IsScanning() will now return true in this case. false otherwise.

See also:: BtHub::cb_InquiryState, BtHub::cb_InquiryResult, IsScanning()

void StopInquiry ( void )

Halt and cancel an in-progress inquiry for discoverable Bluetooth devices.

If an inquiry is in progress, this method will cause it to be aborted.

bool IsScanning ( void ) const [inline]

Query whether a Bluetooth device inquiry is in progress.

When an inquiry scan is in progress, it is forbidden to request another scan, and StartInquiry() will fail.

Return values:

	true	Device scan is in progress
	false	Device scan is not in progress

Member Data Documentation

Callback<void, ErrorInfo*> cb_NotifySystemState

Notification that the Bluetooth system has stopped or restarted asynchronously.

The callback implementation can distinguish between the system having been stopped or restarted by the ErrorInfo* parameter being nonzero, or by checking IsStarted().

Parameters:

[out] ErrorInfo* Error information structure describing the reason for an asynchronous shutdown of the Bluetooth service, or 0 if the Bluetooth service has been asynchronously started.

Reasons for stopping typically include:

The last Bluetooth HCI was disconnected
The local SDP daemon became unavailable

The value of the ErrorInfo* structure passed to this callback may not reflect a specific difference between the above two events. Frequently, when an HCI is removed, the SDP daemon will shut itself down, and it becomes a race condition which events is observed first.

This callback may also be invoked if the system is successfully started by the auto-restart mechanism.

As a rule, no callbacks are invoked in a nested fashion from method calls. This callback is never invoked in a nested fashion from Stop() or Start().

See also:: SetAutoRestart()

Callback<BtDevice*, bdaddr_t const &> cb_BtDeviceFactory

Factory for BtDevice objects, implemented as a callback.

As per the BtDevice life cycle, clients of BtHub may use this callback to construct derivatives of BtDevice with additional functionality or with pre-registered callbacks.

This callback specifically violates the rule of not invoking callbacks in a nested fashion from client method calls, as it may be called nested from GetDevice() with create=true. Clients choosing to receive this callback must avoid additional BtHub / BtDevice method calls aside from constructors and DefaultDevFactory().

Parameters:

baddr_t&

Bluetooth address of the device to be represented.

Returns:: Newly created BtDevice object representing the device, or NULL on failure.

Callback<void, BtDevice *, ErrorInfo*> cb_InquiryResult

Notification of new inquiry result or completion of inquiry.

As devices are discovered during an inquiry, they are reported through this callback.

Parameters:

	BtDevice*	The BtDevice object representing the device, or `0` to indicate that the inquiry has completed.
	ErrorInfo*	If an inquiry was aborted for reasons other than StopInquiry() before the time limit elapsed, this parameter will provide an error code indicating why the inquiry failed. Otherwise, this parameter will be `0`.

See also:: StartInquiry(), IsScanning()

BtHub Class Reference [Bluetooth Hands-Free Profile Implementation]

Public Member Functions

Public Attributes

Detailed Description

Hub Operation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

BtHub Class Reference
[Bluetooth Hands-Free Profile Implementation]