BtctlController

BtctlController — Control discovery and RFCOMM connections

Synopsis




            BtctlController;
BtctlController* btctl_controller_new       (void);
#define     BTCTL_RFCOMM_NO_DEVICE
#define     BTCTL_RFCOMM_DEVICE_IN_USE
void        btctl_controller_discover_devices
                                            (BtctlController *bc);
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);
void        btctl_controller_scan_for_service
                                            (BtctlController *bc,
                                             const gchar *bdstr,
                                             guint clsid);
void        btctl_controller_cancel_discovery
                                            (BtctlController *bc);
void        btctl_controller_discover_async (BtctlController *bc);
gboolean    btctl_controller_is_initialised (BtctlController *bc);
int         btctl_controller_get_signal_strength
                                            (BtctlController *bc,
                                             const gchar *bdaddr,
                                             GError **err);

Object Hierarchy


  GObject
   +----BtctlController

Signal Prototypes


"add-device"
            void        user_function      (BtctlController *btctlcontroller,
                                            gchar *arg1,
                                            guint arg2,
                                            gpointer user_data);
"add-device-service"
            void        user_function      (BtctlController *btctlcontroller,
                                            gchar *arg1,
                                            gchar *arg2,
                                            guint arg3,
                                            guint arg4,
                                            gpointer user_data);
"device-name"
            void        user_function      (BtctlController *btctlcontroller,
                                            gchar *arg1,
                                            gchar *arg2,
                                            gpointer user_data);
"status-change"
            void        user_function      (BtctlController *btctlcontroller,
                                            gint arg1,
                                            gpointer user_data);

Description

Details

BtctlController

typedef struct _BtctlController BtctlController;


btctl_controller_new ()

BtctlController* btctl_controller_new       (void);

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.

Returns : a pointer to the controller object if successful, otherwise NULL.

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);

Commence a synchronous device discovery cycle.

bc : Bluetooth controller object.

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 ()

void        btctl_controller_scan_for_service
                                            (BtctlController *bc,
                                             const gchar *bdstr,
                                             guint clsid);

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.

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.

bc : Bluetooth controller object.

btctl_controller_is_initialised ()

gboolean    btctl_controller_is_initialised (BtctlController *bc);

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.
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.

Signals

The "add-device" signal

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

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);

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);

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);

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.