osso-gwconnect - BT Connectivity applications
=============================================

This package contains D-BUS applications for Bluetooth connectivity:

- Bluetooth Connection Daemon (btcond)
- Bluetooth SDP (btsdp)
- Bluetooth Search (btsearch)

When using the interfaces from a C-program it is recomended that you use the
definitions in bt-dbus.h (installed with osso-gwconnect-dev package).


Bluetooth Connection Daemon
===========================

This daemon is responsible for controlling connections to Bluetooth devices
as well as messaging related information through the system D-BUS.

The daemon listens for messages asigned to it on the system D-BUS as well as
broadcasts status signals to the system D-BUS.


btcond D-BUS API
================

Service:
com.nokia.btcond

Interfaces:
com.nokia.btcond.request
com.nokia.btcond.signal

Object paths:
/com/nokia/btcond/request
/com/nokia/btcond/signal

Method calls accepted on com.nokia.btcond.request interface:

Name: connection_status
Parameters:
	1. string		BDA of remote device
Return parameters:
	1. string		BDA of remote device
	2. string
		"connected"	Device is connected
		"disconnected"	Device is not connected
Errors: None
Description:
	Query device connection status


Name: disconnect
Parameters:
	1. string		BDA of device to disconnect
Return parameters: None
Errors: None
Description:
	Force disconnection from device


Name: get_dev_capability
Parameters:
	1. string 		BDA of device to query
Errors:
	"com.nokia.btcond.error.bt_disabled"
		Bluetooth is disabled (flight mode)
	"com.nokia.btcond.error.no_dev_info"
		No info about device
Return parameters:
	1. list<string> (list of SDP profiles, e.g. "DUN")
Description:
	Query device capabilities (ie. supported SDP profiles)


Name: rfcomm_connect
Parameters:
	1. string		BDA of device to connect to
	2. string		SDP profile, e.g. "DUN"
	3. boolean		Automatic disconnect
Return parameters
	1. string (device name, e.g. "/dev/rfcomm0")
Errors:
	"com.nokia.btcond.error.invalid_dev"
		Invalid BDA
	"com.nokia.btcond.error.invalid_svc"
		No such profile on device
	"com.nokia.btcond.error.connect_failed"
		Connection to device failed
	"com.nokia.btcond.error.connected"
		Already connected to specified service
	"com.nokia.btcond.error.cancelled"
		Connection creation was interrupted using the
		rfcomm_cancel_connect method call
Description:
	Connect to a specific RFCOMM service on a device. If the automatic
	disconnect parameter is true btcond will listen for when the
        caller disconnects from D-BUS and automatically disconnects the RFCOMM
	service.


Name: rfcomm_disconnect
Parameters:
	1. string (optional)	BDA of device to disconnect
	2. string		Service (e.g. "DUN") or device node [1]
Return parameters: none
Errors:
	"com.nokia.btcond.error.invalid_dev"
		Invalid BDA
	"com.nokia.btcond.error.not_connected"
		Specified service is not connected
Description:
	Disconnect a connected RFCOMM service
	[1] If only one parameter is given to this method call
        that parameter may also be the device node ("/dev/rfcommN")
	of the connected service.


Name: rfcomm_cancel_connect
Parameters:
	1. string  		BDA of remote device
	2. string		Service (e.g. "DUN")
Return parameters: none
Errors:
	"com.nokia.btcond.error.invalid_dev"
		Invalid BDA
	"com.nokia.btcond.error.invalid_svc"
		Invalid service
	"com.nokia.btcond.error.failed"
		No connection creation in progress
Description:
	Call this method to stop connection creation (e.g. if user
	selects "cancel" or if you time out while waiting for a
	reply from rfcomm_connect).


Name: rfcomm_bind
Parameters:
	1. string		BDA of remote device
	2. string		SDP profile, e.g. "DUN"
Return parameters
	1. string (device name, e.g. "/dev/rfcomm0")
Errors:
	"com.nokia.btcond.error.invalid_dev"
		No such device selected
	"com.nokia.btcond.error.invalid_svc"
		No such profile on device
	"com.nokia.btcond.error.internal"
		Internal btcond error
Description:
	Bind a device node to a service on a remote BT device.


Name: rfcomm_release
Parameters:
	1. string (optional)	BDA of remote device
	2. string		Service (e.g. "DUN") or device node [1]
Return parameters: none
Errors:
	"com.nokia.btcond.error.invalid_dev"
		No such device selected
	"com.nokia.btcond.error.not_connected"
		Specified service is not connected
Description:
	Release a bound device node
	[1] If only one parameter is given to this method call
        that parameter may also be the device node ("/dev/rfcommN")
	of the connected service.



Signals emited to system D-BUS:

Name: connection_status
Parameters:
	1. string		BT address
	2. string		"connected" or "disconnected"
Description:
	Sent everytime BT connection status changes


Name: rfcomm_status
Parameters:
	1. string		BT address
	2. string		Service (e.g. "DUN")
	3. status		"connected" or "disconnected"
Errors: None
Description:
	Sent when RFCOMM connection status changes


Name: connect_failed
Parameters:
	1. string		BT address
	2. byte			Status
Description:
	Sent everytime BT connection creation fails


Name: auth_failed
Parameters:
	1. string		BT address
	2. byte			Status
Description:
	Sent everytime a HCI authentication complete event with non-zero status
        is received.


Name: pin_req
Parameters:
	1. string 	BT address
Description:
	Sent everytime a pin is requested for a device


Name: link_key_ok
Parameters:
	1. string 	BT address
Description:
	Sent when a link key has been successfully negotiated (i.e.
        authentication succeeded) with a remote device.


Name: hci_dev_down
Parameters:
	1. string	HCI device (e.g. "hci0")
Description:
	Sent when a hci device is set to DOWN state


Name: hci_dev_up
Parameters:
	1. string	HCI device (e.g. "hci0")
Description:
	Sent when a hci device is set to UP state


Bluetooth SDP
=============

This application provides a BT SDP service over D-BUS.

D-BUS API:

Service:
	com.nokia.btsdp

Interfaces:
	com.nokia.btsdp.request

Object paths:
	/com/nokia/btsdp/request

Method calls received on com.nokia.btsdp.request interface:

Name: get_services
Parameters:
	1. string	BDA (e.g. "AB:CD:EF:98:76:65")
	2. string or uint32 (optional)
	...
Return parameters:
	1. array{struct}:
		1. byte		type ('r' = RFCOMM, 'l' = L2CAP)
		2. string	service (e.g. "DUN")
		3. byte		channel
		4. ttl		Time To Live (in seconds)
		5. name		Name of service
Errors:
	"com.nokia.btsdp.error.connect_failed"
		Unable to connect to BDA
	"com.nokia.btsdp.error.bt_disabled"
		BT is not enabled (flight mode)
	"org.freedesktop.DBus.Error.InvalidArgs"
		Invalid arguments were given.
Description:
	Get list of services of specified BDA. Detected service
	strings are:
		"DUN"  (Dialup Networking Profile)
		"FTP"  (OBEX File Transfer Profile)
		"NFTP" (Nokia OBEX File Transfer Profile)
		"OPP"  (OBEX Object Push Profile)
		"SAP"  (SIM Access Profile)
		"SPP"  (Serial Port Profile)
		"HID"  (Human Interface Device Profile)
	If two parameters are given then all services will be browsed. Any
	parameters after the second one can be either uint32 or string. A
        string is intepreted as one from the list above (e.g. "DUN"). A uint32
	is interpreted as a 16 bit UUID (e.g. 0x0100 for L2CAP). If more than
	two arguments are given then only the listed services are searched for.

BT Search
=========

This application is the backend to the Bluetooth Inquiry (device search) UI.
The UI sends a "start_search" message to this backend and the backend comences
a Bluetooth inquiry. Everytime a new device is found the backend sends a
"dev_found" signal to the UI. When inquiry is finished a "search_complete"
signal is sent to the UI.

If the BT Search backend doesn't get a "start_search" request within 5 seconds
after startup it will automatically exit. This should work fine since the backend
is desiged to be launched through D-BUS activation (i.e. D-BUS starts it when
it gets a message destined for the "com.nokia.btsearch" service.

D-BUS API:

Service:
	com.nokia.btsearch

Interfaces:
	com.nokia.btsearch.request
	com.nokia.btsearch.signal

Object paths:
	/com/nokia/btsearch/request
	/com/nokia/btsearch/signal

Method calls received on com.nokia.btsearch.request interface:

Name: start_search
Parameters: None
Return parameters: None
Errors:
	"com.nokia.btsearch.error.bt_disabled"
		BT is not enabled (flight mode)
	"com.nokia.btsearch.error.search_in_progress"
		A search is already in progress
Description:
	Subscribe to receiving inquiry result list

Name: stop_search
Parameters: None
Return parameters: None
Errors:
	"com.nokia.btsearch.error.no_search"
		A search is not in progress
Description:
	Stop an ongoing search.



Signals emitted from com.nokia.btsearch.signal interface:

Name: dev_found
Parameters:
	1. string	BDA (e.g. "12:23:45:56:67:89")
	2. string	Name (e.g. "Nokia 6600" or "<none>")
	3. byte[3]	Class of device (as in BT Assigned Numbers)
	4. byte		RSSI (0 if no BT 1.2 support)
	5. uint32	Clock offset (cast from uint16_t)
Description:
	Sent everytime a new device is found

Name: search_complete
Parameters: None
Description:
	Sent when the inquiry is finnished. btsearch will exit after sending
        this.


