BtctlController

BtctlController — Control discovery and RFCOMM connections

Synopsis

                    BtctlController;
BtctlController*    btctl_controller_new                (const char *hci_device);
#define             BTCTL_RFCOMM_NO_DEVICE
#define             BTCTL_RFCOMM_DEVICE_IN_USE
void                btctl_controller_discover_devices   (BtctlController *bc,
                                                         GError **err);
void                btctl_controller_list_rfcomm_connections
                                                        (BtctlController *bc);
gint                btctl_controller_establish_rfcomm_connection
                                                        (BtctlController *bc,
                                                         const gchar *bdstr,
                                                         guint channel);
gint                btctl_controller_get_established_rfcomm_connection
                                                        (BtctlController *bc,
                                                         const gchar *bdstr,
                                                         guint channel);
gboolean            btctl_controller_scan_for_service   (BtctlController *bc,
                                                         const gchar *bdstr,
                                                         guint clsid,
                                                         GError **err);
void                btctl_controller_cancel_discovery   (BtctlController *bc);
void                btctl_controller_discover_async     (BtctlController *bc);
gboolean            btctl_controller_is_initialised     (BtctlController *bc,
                                                         GError **err);
int                 btctl_controller_get_signal_strength
                                                        (BtctlController *bc,
                                                         const gchar *bdaddr,
                                                         GError **err);

Object Hierarchy

  GObject
   +----BtctlController

Properties

  "hci-device"               gchar*                : Write / Construct Only

Signals

  "add-device"                                     : Run First
  "add-device-service"                             : Run First
  "device-name"                                    : Run First
  "status-change"                                  : Run First

Description

Details

BtctlController

typedef struct _BtctlController BtctlController;

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.

hci_device :

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

Returns :

 a pointer to the controller object.

BTCTL_RFCOMM_NO_DEVICE

#define BTCTL_RFCOMM_NO_DEVICE -1

BTCTL_RFCOMM_DEVICE_IN_USE

#define BTCTL_RFCOMM_DEVICE_IN_USE -2

btctl_controller_discover_devices ()

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

Commence a synchronous device discovery cycle.

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.

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.

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.

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

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.

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.

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.

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.

bc :

 Bluetooth controller object.

bdaddr :

 Destination device address.

err :

 GError

Returns :

 integer representing the signal strength.

Property Details

The "hci-device" property

  "hci-device"               gchar*                : Write / Construct Only

HCI device.

Default value: NULL

Signal Details

The "add-device" signal

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

Emitted when a device has been discovered.

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.

The "add-device-service" signal

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

Emitted when a service record is found for a device.

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.

The "device-name" signal

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

Emitted when a response is received to a name query.

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.

The "status-change" signal

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

Emitted when the discovery process changes phase.

btctlcontroller :

 the object which received the signal.

status :

 status indicator

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.11