BtDevice Class Reference
[Bluetooth Hands-Free Profile Implementation]

Bluetooth Device Record. More...

#include <bt.h>

Inheritance diagram for BtDevice:

[legend]

Collaboration diagram for BtDevice:

[legend]

List of all members.

Public Member Functions
	BtDevice (BtHub *hubp, bdaddr_t const &bdaddr)
	Standard constructor.
virtual	~BtDevice ()
	Standard destructor.
void	DisconnectAll (void)
	Disconnect all active sessions.
const char *	GetName (void) const
	Query the Bluetooth name of the device.
bdaddr_t const &	GetAddr (void) const
	Query the Bluetooth address of the device.
void	GetAddr (char(&namebuf)[32]) const
	Query the Bluetooth address of the device in string form.
bool	IsNameResolving (void) const
	Query whether name resolution is pending.
bool	IsNameResolved (void) const
	Query whether the Bluetooth name of the device has been resolved.
bool	ResolveName (ErrorInfo *error=0)
	Request that the Bluetooth name of the device be resolved.
BtHub *	GetHub (void) const
DispatchInterface *	GetDi (void) const
void *	GetPrivate (void) const
	Query the private pointer associated with the object.
void	SetPrivate (void *priv)
	Assign the private pointer associated with the object.
void	Get (void)
	Increment the reference count.
void	Put (void)
	Decrement the reference count.
Public Attributes
Callback< void, BtDevice *, const char *, ErrorInfo * >	cb_NotifyNameResolved
	Notification that a query of the Bluetooth name of the device has completed.
Callback< void, BtManaged * >	cb_NotifyDestroy
	Object destruction notification callback.

---

Detailed Description

Bluetooth Device Record.

This class represents a remote Bluetooth device that can connect to local services or be connected to by local service handlers. It supports numerous use cases:

• Identifying a device to be connected to, or an incoming connection
• Interrogating the Bluetooth name of the device

Life Cycle

The associated BtHub object manages the life cycle of BtDevice objects. The BtHub keeps an index of BtDevice objects, and ensures that every object has a unique Bluetooth address key.

All BtDevice objects are instantiated by GetDevice() with create=true. Service handlers such as HfpService will perform the instantiation themselves in the case of devices remotely initating connections.

BtDevice objects are reference-counted, and are always destroyed when their reference count drops to zero. Destruction is not immediate and is executed in the context of a timer event.

Service frontends such as HfpSession will retain references on their underlying BtDevice objects, and the BtDevice will not be destroyed until the service frontend is destroyed and its reference is removed.

Clients may override the instantiation path for BtDevice objects by registering their own factory method to BtHub::cb_BtDeviceFactory. As part of a specialized factory, clients may use the default factory method, BtHub::DefaultDevFactory(). A specialized factory may be used to:

• Instantiate a class derived from BtDevice with additional functionality.
• Register all relevant callbacks with the BtDevice object from a single path, and before any may be invoked.

---

Constructor & Destructor Documentation

BtDevice	(	BtHub *	hubp,
		bdaddr_t const &	bdaddr
	)

Standard constructor.

This method will only be useful to clients that define subclasses of BtDevice and provide a callback for BtHub::cb_BtDeviceFactory.

Parameters:

[in]	hubp	BtHub with which the object will be associated
[in]	bdaddr	Bluetooth address of the device, also provided by BtHub::cb_BtDeviceFactory.

See also:

BtHub::cb_BtDeviceFactory

---

Member Function Documentation

void DisconnectAll

(

void

)

[inline]

Disconnect all active sessions.

Causes all sessions associated with this device to be disconnected if they are in a connected state. No client callbacks will be issued for any sessions.

const char* GetName

(

void

)

const [inline]

Query the Bluetooth name of the device.

If the device's Bluetooth name has been resolved, it will be returned, otherwise a string representation of the device's bdaddr will be returned. Name resolution may be requested by ResolveName().

Returns:

A pointer to a buffer containing the device name. The buffer will remain valid until the next event handling loop invocation.

See also:

IsNameResolved(), ResolveName(), BtDevice::cb_NotifyNameResolved

bdaddr_t const& GetAddr

(

void

)

const [inline]

Query the Bluetooth address of the device.

Returns:

A reference to a bdaddr_t containing the Bluetooth address of the device. Can be passed as an argument to bacmp() and ba2str().

See also:

GetName()

void GetAddr

(

char &

namebuf[32]

)

const

Query the Bluetooth address of the device in string form.

This overload of GetAddr() is useful for configuration file writing paths that need to record a textual Bluetooth address.

Parameters:

[out]

namebuf

A buffer to be filled with a string representation of the device's bdaddr.

See also:

GetName()

bool IsNameResolved

(

void

)

const [inline]

Query whether the Bluetooth name of the device has been resolved.

Return values:

	true	Bluetooth name has been resolved, GetName() will return the textual Bluetooth name.
	false	Bluetooth name has not been resolved, GetName() will return a string representation of the device's bdaddr.

See also:

GetName(), ResolveName(), BtDevice::cb_NotifyNameResolved

bool ResolveName

(

ErrorInfo *

error = 0

)

Request that the Bluetooth name of the device be resolved.

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	Name resolution has been initiated
	false	Name resolution not initiated. Reasons might include: A name resolution is already in progress Bluetooth service has been shut down

See also:

GetName(), IsNameResolved(), BtDevice::cb_NotifyNameResolved

BtHub* GetHub

(

void

)

const [inline, inherited]

Query the presiding BtHub

DispatchInterface* GetDi

(

void

)

const [inline, inherited]

Query the dispatcher interface of the presiding BtHub

void* GetPrivate

(

void

)

const [inline, inherited]

Query the private pointer associated with the object.

All BtManaged derived objects have a single pointer field reserved for the use of clients. It is always initialized to zero when the object is constructed, and clients may assign it as they wish.

Returns:

The current value of the private pointer

void SetPrivate

(

void *

priv

)

[inline, inherited]

Assign the private pointer associated with the object.

All BtManaged derived objects have a single pointer field reserved for the use of clients. It is always initialized to zero when the object is constructed, and clients may assign it as they wish.

Parameters:

priv

New value to assign to the private pointer

void Get

(

void

)

[inline, inherited]

Increment the reference count.

As per managed objects, BtManaged derived objects are not deleted so long as they have a positive reference count.

See also:

Put()

void Put

(

void

)

[inherited]

Decrement the reference count.

As per managed objects, when the object's reference count reaches zero, the object will be destroyed in the context of a timer event.

See also:

Get()

---

Member Data Documentation

Callback<void, BtDevice *, const char *, ErrorInfo*> cb_NotifyNameResolved

Notification that a query of the Bluetooth name of the device has completed.

Name resolution is normally initiated by ResolveName().

This is particularly useful for device scanning, where a BtDevice is created for each inquiry result, but no Bluetooth names are initially available. As Bluetooth names are resolved, this callback can be used to update user interface widgets.

Parameters:

	char*	Bluetooth name of the device, or NULL if name resolution failed. This value is also available by calling GetName().
	ErrorInfo*	error Error information structure describing the reason for the asynchronous name resolution failure, or 0 if the resolution succeeded.

See also:

ResolveName(), GetName(), IsNameResolved()

Callback<void, BtManaged*> cb_NotifyDestroy [inherited]

Object destruction notification callback.

This callback is invoked proir to deletion of the managed object, so that clients may release associated resources. This callback occurs in the context of a timer event, and complies with the rule of not invoking client callbacks in a nested fashion.

The decision to destroy the object is final. The client may not attempt to preserve the object by acquiring additional references from this callback.

---

The documentation for this class was generated from the following files:

• include/libhfp/bt.h
• libhfp/bt.cpp

---