bluez/doc/device-api.txt

BlueZ D-Bus Device API description
**********************************

Copyright (C) 2004-2010  Marcel Holtmann <marcel@holtmann.org>
Copyright (C) 2005-2006  Johan Hedberg <johan.hedberg@nokia.com>
Copyright (C) 2005-2006  Claudio Takahasi <claudio.takahasi@indt.org.br>
Copyright (C) 2006-2007  Luiz von Dentz <luiz.dentz@indt.org.br>


Device hierarchy
================

Service		org.bluez
Interface	org.bluez.Device
Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX

Methods		dict DiscoverServices(string pattern)

			This method starts the service discovery to retrieve
			remote service records. The pattern parameter can
			be used to specify specific UUIDs. And empty string
			will look for the public browse group.

			The return value is a dictionary with the record
			handles as keys and the service record in XML format
			as values. The key is uint32 and the value a string
			for this dictionary.

			Possible errors: org.bluez.Error.NotReady
					 org.bluez.Error.Failed
					 org.bluez.Error.InProgress

		void CancelDiscovery()

			This method will cancel any previous DiscoverServices
			transaction.

			Possible errors: org.bluez.Error.NotReady
					 org.bluez.Error.Failed
					 org.bluez.Error.NotAuthorized

		void Connect()

			This is a generic method to connect any profiles
			the remote device supports that can be connected
			to and have been flagged as auto-connectable on
			our side.

			Possible errors: org.bluez.Error.NotReady
					 org.bluez.Error.Failed
					 org.bluez.Error.InProgress
					 org.bluez.Error.AlreadyConnected
		void CancelConnect()

			This method can be used to cancel a preceeding
			Connect call before a reply to it has been received.

		void Disconnect()

			This method disconnects a specific remote device by
			terminating the low-level ACL connection. The use of
			this method should be restricted to administrator
			use.

			A DisconnectRequested signal will be sent and the
			actual disconnection will only happen 2 seconds later.
			This enables upper-level applications to terminate
			their connections gracefully before the ACL connection
			is terminated.

			Possible errors: org.bluez.Error.NotConnected

		void ConnectProfile(string uuid)

			This method connects a specific profile of this
			device. The profile needs to be registered client
			profile.

			Possible errors: org.bluez.Error.DoesNotExist
					 org.bluez.Error.AlreadyConnected
					 org.bluez.Error.ConnectFailed

		void DisconnectProfile(string uuid)

			This method disconnects a specific profile of
			this device. The profile needs to be registered
			client profile.

			There is no connection tracking for a profile, so
			as long as the profile is registered this will always
			succeed.

			Possible errors: org.bluez.Error.DoesNotExist
					 org.bluez.Error.NotConnected

		void Pair(object agent, string capability)

			This method will connect to the remote device,
			initiate pairing and then retrieve all SDP records
			(or GATT primary services).

			The agent object path is assumed to reside within the
			process (D-Bus connection instance) that calls this
			method. No separate registration procedure is needed
			for it and it gets automatically released once the
			pairing operation is complete.

			The capability parameter is the same as for the
			Adapter.RegisterAgent method.

			Possible errors: org.bluez.Error.InvalidArguments
					 org.bluez.Error.Failed

		void CancelPairing()

			This method can be used to cancel a pairing
			operation initiated by the Pair method.

Signals		DisconnectRequested()

			This signal will be sent when a low level
			disconnection to a remote device has been requested.
			The actual disconnection will happen 2 seconds later.

Properties	string Address [readonly]

			The Bluetooth device address of the remote device.

		string Name [readonly]

			The Bluetooth remote name. This value can not be
			changed. Use the Alias property instead.

		uint16 Vendor [readonly] [optional]

			Vendor unique numeric identifier.

		uint16 VendorSource [readonly] [optional]

			Vendor source numeric identifier.

		uint16 Product [readonly] [optional]

			Product unique numeric identifier.

		uint16 Version [readonly] [optional]

			Version unique numeric identifier.

		string Icon [readonly] [optional]

			Proposed icon name according to the freedesktop.org
			icon naming specification.

		uint32 Class [readonly] [optional]

			The Bluetooth class of device of the remote device.

		uint16 Appearance [readonly] [optional]

			External appearance of device, as found on GAP service.

		array{string} UUIDs [readonly]

			List of 128-bit UUIDs that represents the available
			remote services.

		array{object} Services [readonly]

			List of characteristics based services.

		boolean Paired [readonly]

			Indicates if the remote device is paired.

		boolean Connected [readonly]

			Indicates if the remote device is currently connected.
			A PropertiesChanged signal indicate changes to this
			status.

		boolean Trusted [readwrite]

			Indicates if the remote is seen as trusted. This
			setting can be changed by the application.

		boolean Blocked [readwrite]

			If set to true any incoming connections from the
			device will be immediately rejected. Any device
			drivers will also be removed and no new ones will
			be probed as long as the device is blocked.

		string Alias [readwrite]

			The name alias for the remote device. The alias can
			be used to have a different friendly name for the
			remote device.

			In case no alias is set, it will return the remote
			device name. Setting an empty string as alias will
			convert it back to the remote device name.

			When resetting the alias with an empty string, the
			emitted PropertiesChanged signal will show the remote
			name again.

		object Adapter [readonly]

			The object path of the adapter the device belongs to.

		boolean LegacyPairing [readonly]

			Set to true if the device only supports the pre-2.1
			pairing mechanism. This property is useful in the
			Adapter.DeviceFound signal to anticipate whether
			legacy or simple pairing will occur.

			Note that this property can exhibit false-positives
			in the case of Bluetooth 2.1 (or newer) devices that
			have disabled Extended Inquiry Response support.