Bluetooth related tools
=======================

This package contains some tools for doing Bluetooth related tasks:

- btname: Set/Get the local Bluetooth name
- btlk: Edit/List stored link keys
- btpair: Perform pairing to a device
- btpin: BT PIN code request proxy

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

btpair D-BUS API
================

Service:
com.nokia.btpair

Interface:
com.nokia.btpair

Object path:
com.nokia.btpair

Method calls accepted on com.nokia.btpair interface:

Name: pair_bda
Parameters:
	1. string	BT address
	2. uint32	clock offset (cast from uint16_t)
	3. boolean (optional) Also request encryption
Return parameters:
	none
Errors:
	com.nokia.btpair.error.connect_failed
	com.nokia.btpair.error.disconnected
	com.nokia.btpair.error.timeout
	com.nokia.btpair.error.refused
	com.nokia.btpair.error.auth_failed
	com.nokia.btpair.error.too_frequent
	com.nokia.btpair.error.resource_limit
	com.nokia.btpair.error.canceled
	com.nokia.btpair.error.failed
	com.nokia.btpair.error.in_progress
Description:
	Perform pairing to specified BDA


Name: pair_handle
Parameters:
	1. uint32	Connection handle
	2. boolean (optional) Also request encryption
Return parameters:
	none
Errors:
	The same as for pair_bda, except connect_failed.
Description:
	Perform pairing for an existing connection handle


btname D-BUS API
================

Service:
com.nokia.btname

Interfaces:
com.nokia.btname.request
com.nokia.btname.signal

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

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

Name: get
Parameters:
	none
Return parameters:
	1. string		local bluetooth name
Errors:
	"com.nokia.btname.error.failed"
Description:
	Get the local bluetooth name

Name: set
Parameters:
	1. string		new bluetooth name
Return parameters:
	none
Errors:
	"com.nokia.btname.error.failed"
Description:
	Set the local bluetooth name


Signals emited to system D-BUS from com.nokia.btname.signal interface:

Name: changed
Parameters:
	1. string		New local bluetooth name
Description:
	Sent everytime the local bluetooth name is changed with btname


btpin D-BUS API
===============

btpin works as a kind of PIN-request proxy. It was implemented to get more
flexibility to handling different kind of pairing situations, e.g. pairing
wizard, pin-code popup dialog, strong pairing dialog for SIM Access Profile,
etc.
btpin maintains a stack of pin-handlers internally and when it receives a
pin-request from the hci-layer (actually from hcid via D-BUS) it starts going
through its stack starting from the top and gives the pin request to the first
matching handler. At the bottom of the stack there is always a permanent handler
which will match any BDA and return the contents of /etc/bluetooth/pin file.


Service:
com.nokia.btpin

Interface:
com.nokia.btpin

Object Path:
/com/nokia/btpin

Method calls accepted on com.nokia.btpin interface:

Name: register
Parameters:
	1. string	Object path (location of pin handler)
	2. string (optional) remote BDA to match
Return parameters:
	none
Errors:
	com.nokia.btpin.error.duplicate
Description:
	Register a new handler for PIN requests


Name: unregister
Parameters:
	1. string	Object path (location of pin handler)
	2. string (optional) remote BDA to match
Return parameters:
	none
Errors:
	com.nokia.btpin.error.nomatch
Description:
	Unregister a PIN handler



btlk
====

btlk can currently only be used from the command line. See "btlk -h" for more
info. It should also be noted that the tool only supports editing the
/etc/bluetooth/link_key binary file which has been removed in the latest
bluez-utils versions (not part of maemo yet) in favor for ASCII based files in
/var/lib/bluetooth

