BtctlController

BtctlController — Control discovery and RFCOMM connections

Functions

Properties

gchar * hci-device Write / Construct Only

Signals

void add-device Run First
void add-device-service Run First
void device-name Run First
void status-change Run First

Types and Values

Object Hierarchy

    GObject
    ╰── BtctlController

Description

Functions

btctl_controller_new ()

BtctlController *
btctl_controller_new (const char *hci_device);

Create a new Bluetooth controller object. This will attempt to open an HCI socket to the default Bluetooth device. Use btctl_controller_is_initialised() to check whether this was successful.

Parameters

hci_device

Bluetooth HCI device string (e.g. "hci0") or NULL.

 

Returns

a pointer to the controller object.


btctl_controller_discover_devices ()

void
btctl_controller_discover_devices (BtctlController *bc,
                                   GError **err);

Commence a synchronous device discovery cycle.

Parameters

bc

Bluetooth controller object.

 

err

An error message (if applicable).

 

btctl_controller_list_rfcomm_connections ()

void
btctl_controller_list_rfcomm_connections
                               (BtctlController *bc);

Dump established rfcomm connections to the terminal.

Parameters

bc

Bluetooth controller object.

 

btctl_controller_establish_rfcomm_connection ()

gint
btctl_controller_establish_rfcomm_connection
                               (BtctlController *bc,
                                const gchar *bdstr,
                                guint channel);

Link an rfcomm device to the destination device. Returns BTCTL_RFCOMM_NO_DEVICE if the connection cannot be made.

Parameters

bc

Bluetooth controller object.

 

bdstr

Bluetooth address of destination device.

 

channel

RFCOMM channel.

 

Returns

rfcomm device number.


btctl_controller_get_established_rfcomm_connection ()

gint
btctl_controller_get_established_rfcomm_connection
                               (BtctlController *bc,
                                const gchar *bdstr,
                                guint channel);

Find rfcomm device number (ie. N for /dev/rfcommN) connected to the destination device on the specified channel. Returns BTCTL_RFCOMM_NO_DEVICE is no device is available, or BTCTL_RFCOMM_DEVICE_IN_USE if a device is available but already in use.

Parameters

bc

Bluetooth controller object.

 

bdstr

Bluetooth address of destination device.

 

channel

RFCOMM channel.

 

Returns

rfcomm device number.


btctl_controller_scan_for_service ()

gboolean
btctl_controller_scan_for_service (BtctlController *bc,
                                   const gchar *bdstr,
                                   guint clsid,
                                   GError **err);

Performs a specific SDP scan for the service specified. The service class identifiers can be found in /usr/include/bluetooth/sdp.h

Parameters

bc

Bluetooth controller object.

 

bdstr

Bluetooth address of destination device.

 

clsid

SDP service class ID.

 

err

An error message (if applicable).

 

Returns

TRUE if the scan was successful.


btctl_controller_cancel_discovery ()

void
btctl_controller_cancel_discovery (BtctlController *bc);

Cancel an asynchronous discovery cycle. Will only work if inquiry cancellation support is present in the kernel.

Parameters

bc

Bluetooth controller object.

 

btctl_controller_discover_async ()

void
btctl_controller_discover_async (BtctlController *bc);

Commence an asychronous device discovery cycle. Signals will be sent on device discovery, but no SDP discovery is being done. The status-change signal will send information about the completion of the scan.

Parameters

bc

Bluetooth controller object.

 

btctl_controller_is_initialised ()

gboolean
btctl_controller_is_initialised (BtctlController *bc,
                                 GError **err);

Check if controller was able to get the Bluetooth HCI connection. If not, we won't be able to do anything like discovery.

Parameters

bc

Bluetooth controller object.

 

err

An error message (if applicable).

 

Returns

TRUE if initialised OK.


btctl_controller_get_signal_strength ()

int
btctl_controller_get_signal_strength (BtctlController *bc,
                                      const gchar *bdaddr,
                                      GError **err);

Bluetooth allows the monitoring of the signal strength of an established connection. There must be an existing connection for this function to work.

Parameters

bc

Bluetooth controller object.

 

bdaddr

Destination device address.

 

err

GError

 

Returns

integer representing the signal strength.

Types and Values

struct BtctlController

struct BtctlController;


BTCTL_RFCOMM_NO_DEVICE

#define BTCTL_RFCOMM_NO_DEVICE -1


BTCTL_RFCOMM_DEVICE_IN_USE

#define BTCTL_RFCOMM_DEVICE_IN_USE -2

Property Details

The “hci-device” property

  “hci-device”               gchar *

HCI device.

Flags: Write / Construct Only

Default value: NULL

Signal Details

The “add-device” signal

void
user_function (BtctlController *btctlcontroller,
               gchar           *arg1,
               guint            arg2,
               gpointer         user_data)

Emitted when a device has been discovered.

Parameters

btctlcontroller

the object which received the signal.

 

bdaddr

device bdaddr

 

clsid

device class flags

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “add-device-service” signal

void
user_function (BtctlController *btctlcontroller,
               gchar           *arg1,
               gchar           *arg2,
               guint            arg3,
               guint            arg4,
               gpointer         user_data)

Emitted when a service record is found for a device.

Parameters

btctlcontroller

the object which received the signal.

 

bdaddr

bdaddr of the device.

 

name

name of the device.

 

classid

SDP class ID of the service.

 

port

RFCOMM port the service is on, if any.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “device-name” signal

void
user_function (BtctlController *btctlcontroller,
               gchar           *arg1,
               gchar           *arg2,
               gpointer         user_data)

Emitted when a response is received to a name query.

Parameters

btctlcontroller

the object which received the signal.

 

bdaddr

bdaddr of device

 

name

name of device

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “status-change” signal

void
user_function (BtctlController *btctlcontroller,
               gint             arg1,
               gpointer         user_data)

Emitted when the discovery process changes phase.

Parameters

btctlcontroller

the object which received the signal.

 

status

status indicator

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First