path: root/hcid/dbus-api.txt

D-Bus API description for BlueZ
*******************************

Copyright (C) 2004-2006  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) 2005-2006  Eduardo Rocha <eduardo.rocha@indt.org.br>


Constant definitions
====================

The class of device definition from the Bluetooth specification divides into
three different parts. It the major class, the minor class and the service
classes. The D-Bus interface will always use string constants to identify
any of these classes.

Service classes		positioning, networking, rendering, capturing,
			object transfer, audio, telephony, information

Major classes		miscellaneous, computer, phone, access point,
			audio/video, peripheral, imaging, wearable, toy,
			uncategorized

Minor classes computer	uncategorized, desktop, server, laptop, handheld,
			palm, wearable

Minor classes phone	uncategorized, cellular, cordless, smart phone,
			modem, isdn

Minor classes access point	fully, 1-17 percent, 17-33 percent,
			33-50 percent, 50-67 percent, 67-83 percent,
			83-99 percent, not available

Minor classes audio video	uncategorized, headset, handsfree,microphone,
			loudspeaker, headphones, portable audio, car audio,
			set-top box, hifi audio, vcr, video camera, camcorder,
			video monitor, video display and loudspeaker,
			video conferencing, gaming/toy, unknown

Minor classes peripheral	uncategorized, keyboard, pointing, combo

Minor classes imaging	display, camera, scanner, printer

Minor classes wearable	wrist watch, pager, jacket, helmet, glasses

Minor classes toy	robot, vehicle, doll, controller, game

Error hierarchy
===============

Interface	org.bluez.Error

Errors		Failed

			An unknown error occured. The error messages is
			taken from the strerror(errno) function.

		InvalidArguments

			Error returned when the argument list is invalid or
			out of specification for the method.

		NotAuthorized

			Error returned when the caller of a method is not
			authorized. This might happen if a caller tries to
			terminate a connection that it hasn't created.

		OutOfMemory

			Error returned when a memory allocation via malloc()
			fails. This error is similar to ENOMEM.

		NoSuchAdapter

			Error returned when the requested adapter doesn't
			exists. This error is similar to ENODEV.

		NotReady
			
			Error returned when the adapter is DOWN.

		NotAvailable

			Error returned when a specified record is not
			available.

		NotConnected

			Error returned when the remote device isn't connected
			at the moment.

		ConnectionAttemptFailed

		AlreadyExists

			Error returned if a record for a specific procedure
			already exists and it has been tried create a new
			one. The error message however should indicate the
			procedure that fails. For example "Bonding already
			exists"

		DoesNotExist

			Error returned if a record for a specifc procedure
			doesn't exist. The error message however should
			indicate the procedure that fails. For example
			"Bonding does not exist".

		InProgress

			Error returned if an operation is in progress. Since
			this is a generic error that can be used in various
			situations, the error message should be more clear
			about what is in progress. For example "Bonding in
			progress".

		AuthenticationFailed

		AuthenticationTimeout

		AuthenticationRejected

		AuthenticationCanceled

		UnsupportedMajorClass


Manager hierarchy
=================

Service		org.bluez
Interface	org.bluez.Manager
Object path	/org/bluez

Methods		uint32 InterfaceVersion()

			Returns the current interface version. At the moment
			only version 0 is supported.

		string DefaultAdapter()

			Returns object path for the default adapter.

		string FindAdapter(string pattern)

			Returns object path for the specified adapter. Valid
			patterns are "hci0" or "00:11:22:33:44:55".

		array{string} ListAdapters()

			Returns list of adapter object paths under /org/bluez

		array{string} ListServices()

			Returns list of service connection identifiers.

Signals		void AdapterAdded(string path)

			Parameter is object path of added adapter.

		void AdapterRemoved(string path)

			Parameter is object path of removed adapter.


Adapter hierarchy
=================

Service		org.bluez
Interface	org.bluez.Adapter
Object path	/org/bluez/{hci0,hci1,...}

Methods		string GetAddress()

			Returns the device address for a given path.

			Example: "00:11:22:33:44:55"

			Possible errors: none

		string GetVersion()

			Returns the version of the Bluetooth chip. This version
			is compiled from the LMP version. In case of EDR the
			features attribute must be checked.

			Example: "Bluetooth 2.0 + EDR"

			Possible errors: none

		string GetRevision()

			Returns the revision of the Bluetooth chip. This is a
			vendor specific value and in most cases it represents
			the firmware version. This might derive from the HCI
			revision and LMP subversion values or via extra vendor
			specific commands.

			In case the revision of a chip is not available. This
			method should return the LMP subversion value as a
			string.

			Example: "HCI 19.2"

			Possible errors: none

		string GetManufacturer()

			Returns the manufacturer of the Bluetooth chip. If
			the company id is not know the sting "Company ID %d"
			where %d should be replaced with the numeric value
			from the manufacturer field.

			Example: "Cambridge Silicon Radio"

			Possible errors: none

		string GetCompany()

			Returns the company name from the OUI database of the
			Bluetooth device address. This function will need a
			valid and up-to-date oui.txt from the IEEE. This value
			will be different from the manufacturer string in the
			most cases.

			If the oui.txt file is not present or the OUI part of
			the BD_ADDR is not listed, it should return the
			string "OUI %s" where %s is the actual OUI.

			Example: "Apple Computer"

			Possible errors: none

		string GetMode()

			Returns the current mode of a adapter.

			Valid modes: "off", "connectable", "discoverable"

			Possible errors: none

		void SetMode(string mode)

			Sets mode of the adapter. See GetMode for valid strings
			for the mode parameter.

			Possible errors: org.bluez.Error.Failed

		uint32 GetDiscoverableTimeout()

			Returns the discoverable timeout in seconds. A value
			of zero means that the timeout is disabled and it will
			stay in discoverable mode forever.

			The default value for the discoverable timeout should
			be 180 seconds (3 minutes).

			Possible errors: none

		void SetDiscoverableTimeout(uint32 timeout)

			Sets the discoverable timeout in seconds. A value of
			zero disables the timeout and the adapter would be
			always discoverable.

			Changing this value doesn't set the adapter into
			discoverable mode. The SetMode method must be used.

			Possible errors: org.bluez.Error.InvalidArguments

		boolean IsConnectable()

			Returns true if the local adapter is connectable and
			false if it is switched off.

			It is also possible to use GetMode to retrieve this
			information.

			Possible errors: none

		boolean IsDiscoverable()

			Returns true if the local adapter is discoverable and
			false if it is only connectable or switched off.

			It is also possible to use GetMode to retrieve this
			information.

			Possible errors: none

		boolean IsConnected(string address)

			Return true if the local adapter is connected to
			the remote device.

			Possible errors: org.bluez.Error.InvalidArguments

		array{string} ListConnections()

			Returns a list with addresses of currently connected
			remote devices.

			Possible errors: none

		string GetMajorClass()

			Returns the current major class value for this
			system. This value is set to "computer" for now.

			If the major class can't be matched by a string
			the decimal value as string should be returned.

			Possible errors: none

		array{string} ListAvailableMinorClasses()

			Returns a list of available minor classes for the
			currently used major class. At the moment this should
			only return a list of minor classes if the major
			class is set to "computer".

			If the major class is not "computer" an error should
			be returned.

			Possible errors: org.bluez.Error.UnsupportedMajorClass

		string GetMinorClass()

			Returns the current minor class value for this
			system where the default major class is "computer".

			If the major class is not "computer" an error should
			be returned.

			Valid values: "uncategorized", "desktop", "server",
			              "laptop", "handheld", "palm", "wearable"

			The default value is "uncategorized".

			Possible errors: org.bluez.Error.UnsupportedMajorClass

		void SetMinorClass(string minor)

			Sets the local minor class and on success it sends
			a MinorClassChanged signal.

			If the major class is not "computer" an error should
			be returned.

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

		array{string} GetServiceClasses()

			Returns the current set of service classes.

			In the case no service classes are set (when no
			service has been registered) an empty list should
			be returned.

			Valid values: "positioning", "networking", "rendering",
			              "capturing", "object transfer", "audio",
			              "telephony", "information"

			Possible errors: none

		string GetName()

			Returns the local adapter name (friendly name) in UTF-8.

			Possible errors: org.bluez.Error.NotReady 

		void SetName(string name)

			Sets the local adapter name. If EIR is supported by
			the local hardware this modifies also the extended
			response data value.

			Possible errors: org.bluez.Error.Failed

			Questions: What to do (in case of EIR) if one
			           low-level API call fails.

		string GetRemoteVersion(string address)

			Get the version info for a remote device. This request
			returns always this information based on its cached
			data. The base for this string is the LMP version
			value and the features for EDR support.

			Not available can be received if the remote device was
			not contacted(connected) previously. Remote data is
			automatically retrieved in the first connection.

			Example: "Bluetooth 2.0 + EDR"

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

		string GetRemoteRevision(string address)

			Get the revision of the Bluetooth chip. This is a
			vendor specific value and in most cases it represents
			the firmware version. This derives only from the LMP
			subversion value.

			Example: "HCI 19.2"

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

		string GetRemoteManufacturer(string address)

			Get the manufacturer of the chip for a remote device.

			Example: "Nokia Mobile Phones"

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

		string GetRemoteCompany(string address)

			Get the company name from the OUI database of the
			Bluetooth device address. This function will need a
			valid and up-to-date oui.txt from the IEEE. This value
			will be different from the manufacturer string in the
			most cases.

			Example: "Microsoft Corporation"

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

		string GetRemoteMajorClass(string address)

			Get the major device class of the specified device.

			Example: "computer"

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

		string GetRemoteMinorClass(string address)

			Get the minor device class of the specified device.

			Example: "laptop"

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

		array{string} GetRemoteServiceClasses(string address)

			Get the service classes of the specified device.

			Example: ["networking", "object transfer"]

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

		uint32 GetRemoteClass(string address)

			Get the remote major, minor, and service classes 
			encoded as 32 bit integer.

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

		string GetRemoteName(string address)

			Get adapter name for a remote device. This request
			returns always a cached name. The service daemon is
			responsible for updating the cache.

			If no remote name is available, then this function
			will return RequestDeferred. In this case the service
			daemon will try to resolve the name at the next
			possible opportunity. On success a RemoteNameUpdated
			signal will be send and if a failure happens it will
			be indicated by a RemoteNameFailed signal.

			If this is an empty string, the UI might want to
			display the BD_ADDR instead.

			Example: "00:11:22:33:44:55", "Nokia 770"

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

		string GetRemoteAlias(string address)

			Returns alias name for remote device. If this is
			an empty string value, the UI should show the
			remote name instead.

			An alias should supersede the remote name.

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

		void SetRemoteAlias(string address, string alias)

			Sets alias name for remote device. If alias name is
			empty, then no alias is set.

			On success the SetRemoteAlias method will produce a
			RemoteAliasChanged signal which applications can use
			to update their current display of the remote device
			name.

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

		void ClearRemoteAlias(string address)

			Resets alias name for remote device. If there is no
			alias set for the device this method will silently
			succeed, but no RemoteAliasCleared signal has to be
			sent in this case.

			On success the ClearRemoteAlias method will produce
			a RemoteAliasCleared signal.

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

		string LastSeen(string address)

			Returns the date and time when the adapter has been
			seen by a discover procedure.

			Example: "2006-02-08 12:00:00 GMT"

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

			Question: Can we find a better name?

		string LastUsed(string address)

			Returns the date and time of the last time when the
			adapter has been connected.

			Example: "2006-02-08 12:00:00 GMT"

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

			Question: Can we find a better name?

		void DisconnectRemoteDevice(string address)

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

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

		void CreateBonding(string address)

			This method creates a bonding with a remote device.

			If a link key for this adapter already exists, this
			procedure should fail instead of trying to create a
			new pairing.

			If no connection to the remote device exists, a
			low-level ACL connection must be created.

			This function will block and the calling application
			should take care of setting are higher timeout. This
			might be needed in case of a page timeout from the
			low-level HCI commands.

			In case of success it will send a BondingCreated
			signal.

			Possible errors: org.bluez.Error.Failed
					 org.bluez.Error.InvalidArguments
			                 org.bluez.Error.AlreadyExists
			                 org.bluez.Error.InProgress
					 org.bluez.Error.NoSuchAdapter
			                 org.bluez.Error.ConnectionAttemptFailed
			                 org.bluez.Error.AuthenticationFailed
			                 org.bluez.Error.AuthenticationTimeout
			                 org.bluez.Error.AuthenticationRejected
			                 org.bluez.Error.AuthenticationCanceled

		void CancelBondingProcess(string address)

			This method will cancel the CreateBonding process.

			The CreateBonding method will return
			AuthenticationCanceled to signal that an attempt to
			create a bonding has been canceled.

			Possible errors: org.bluez.Error.Failed
					 org.bluez.Error.InvalidArguments
					 org.bluez.Error.NotInProgress
					 org.bluez.Error.NotAuthorized
					 org.bluez.Error.NoSuchAdapter

		void RemoveBonding(string address)

			This method removes the bonding with a remote device.

			For security reasons this includes removing the actual
			link key and also disconnecting any open connections
			for the remote device.

			If the link key was stored on the Bluetooth chip, it
			must be removed from there, too.

			After deleting the link key this method will send a
			BondingRemoved signal.

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

		boolean HasBonding(string address)

			Returns true if the remote device is bonded and false
			if no link key is available.

			Possible errors: org.bluez.Error.InvalidArguments

		array{string} ListBondings()

			List device addresses of currently bonded adapter.

			Possible errors: none

		uint8 GetPinCodeLength(string address)

			Returns the PIN code length that was used in the
			pairing process.

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

		uint8 GetEncryptionKeySize(string address)

			Returns the currently used encryption key size.

			This method will fail if no connection to the address
			has been established.

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

		void DiscoverDevices()

			This method starts the device discovery procedure. This
			includes an inquiry procedure and remote device name
			resolving.

			On start up this process will generate a DiscoveryStart
			signal and then return RemoteDeviceFound and also
			RemoteNameUpdated signals. If the procedure has been
			finished an DiscoveryCompleted signal will be sent.

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

		void DiscoverDevicesWithoutNameResolving()

			This method starts the device discovery procedure. This
			includes an inquiry and an optional remote device name
			resolving. The remote names can be retrieved with
			GetRemoteName and in the case a name doesn't exist it
			will be queued for later resolving and GetRemoteName
			will return an error.

			While this procedure is running every found device
			will be returned with RemoteDeviceFound. While
			DiscoverDevices() automatically resolves unknown
			devices names and sends RemoteNameUpdated in this
			case it will only happen if GetRemoteName has been
			called and no previously stored name is available.

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

		void CancelDiscovery()

			This method will cancel any previous DiscoverDevices
			or DiscoverDevicesWithoutNameResolving actions.

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

		void StartPeriodicDiscovery()

			This method starts a periodic discovery.

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

		void StopPeriodicDiscovery()

			This method stops a periodic discovery.

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

		array{uint32} GetRemoteServiceHandles(string address, string match)

			This method will request the SDP database of a remote
			device and retrieve the service record handles.

		array{byte} GetRemoteServiceRecord(string address, uint32 handle)

			This method will request the SDP database of a remote
			device for a service record and return the binary
			stream of it.

Signals		void ModeChanged(string mode)

			If the current mode is changed with SetMode this signal
			will inform about the new mode.

			This signal can also be triggered by low-level HCI
			commands.

		void MinorClassChanged(string minor)

			After changing the minor class with SetMinorClass this
			signal will provide the new class value.

		void NameChanged(string name)

			After changing the local adapter name with SetName this
			signal will provide the new name.

			This signal can also be triggered by low-level HCI
			commands.

		void DiscoveryStarted()

			This signal indicates that a device discovery
			procedure has been started.

		void DiscoveryCompleted()

			This signal indicates that a device discovery
			procedure has been completed.

		void RemoteDeviceFound(string address, uint32 class, int16 rssi)

			This signal will be send every time an inquiry result
			has been found by the service daemon. In general they
			only appear during a device discovery.

		void RemoteClassUpdated(string address, uint32 class)

			This signal will be send every time the remote class
			of device has been changed. This happens for example
			after a remote connection attempt. This signal will
			not be send if the class of device hasn't changed
			compared to cached one.

		void RemoteNameUpdated(string address, string name)

			This signal will be send every time the service daemon
			detect a new name for a remote device.

		void RemoteNameFailed(string address)

			This signal will be sent every time the service daemon
			tries to resolve a remote and this fails.

		void RemoteAliasChanged(string address, string alias)

			After changing an alias with SetRemoteAlias this
			signal will indicate the new alias.

		void RemoteAliasCleared(string address)

			After removing an alias with ClearRemoteAlias this
			signal will indicate that the alias is no longer
			valid.

		void RemoteDeviceConnected(string address)

			This signal will be send if a low level connection
			between two devices has been created.

		void RemoteDeviceDisconnected(string address)

			This signal will be send if a low level connection
			between two devices has been terminated.

		void BondingCreated(string address)

			Signals that a successful bonding has been created.

		void BondingRemoved(string address)

			Signals that a bonding was removed.


Security hierarchy
==================

Service		org.bluez
Interface	org.bluez.Security
Object path	/org/bluez
		/org/bluez/{hci0,hci1,...}

Methods		void RegisterDefaultPasskeyAgent(string path)

			This registers the default passkey agent. It can
			register a passkey for all adapters or for a
			specific device depending on with object path has
			been used.

			The path parameter defines the object path of the
			passkey agent that will be called when a passkey
			needs to be entered.

			If an application disconnects from the bus all
			registered passkey agent will be removed.

			Possible errors: org.bluez.Error.AlreadyExists

		void UnregisterDefaultPasskeyAgent(string path)

			This unregisters a default passkey agent that has
			been previously registered. The object path and
			the path parameter must match the same values that
			has been used on registration.

			Possible errors: org.bluez.Error.DoesNotExist

		void RegisterPasskeyAgent(string path, string address)

			This registers the application passkey agent that
			will be used for any application specific passkey
			tasks.

			The path parameter defines the object path of the
			passkey agent that will be called when a passkey
			needs to be entered. The address defines the remote
			device that it will answer passkey requests for.

			If an application disconnects from the bus all
			registered passkey agent will be removed. It will
			also be unregistered after a timeout and if the
			pairing succeeds or fails. The application has to
			take care of that it reregisters the passkey agent.

			Possible errors: org.bluez.Error.AlreadyExists

		void UnregisterPasskeyAgent(string path, string address)

			This unregisters a passkey agent that has been
			previously registered. The object path and the path
			and address parameter must match the same values
			that has been used on registration.

			The method is actually only needed if an application
			wants to removed the passkey agent and don't wanna
			wait for the automatic timeout.

			Possible errors: org.bluez.Error.DoesNotExist


PasskeyAgent hierarchy
======================

Service		unique name
Interface	org.bluez.PasskeyAgent
Object path	freely definable

Methods		string Request(string path, string address)

			This method gets called when the service daemon
			needs to get the passkey for an authentication. The
			return value is actual passkey.

			The first argument contains the path of the local
			adapter and the second one the remote address.

			Possible errors: org.bluez.Error.Rejected
			                 org.bluez.Error.Canceled

		void Cancel(string path, string address)

			This method is called to indicate that the
			authentication request failed before a reply was
			returned by the Request method.

		void Release()

			This method gets called when the service daemon
			unregisters a passkey agent. An agent can use
			it to do cleanup tasks. There is no need to
			unregister the agent, because when this method
			gets called it has already been unregistered.


RFCOMM hierarchy (experimental)
===============================

Service		org.bluez
Interface	org.bluez.RFCOMM
Object path	/org/bluez/{hci0,hci1,...}

Methods		string Connect(string address, string service)

			This creates a connection to a remote RFCOMM based
			service. The service string can either be a UUID-128,
			a service abbreviation or a record handle.

			The return value will be the path of the newly
			created RFCOMM TTY device (for example /dev/rfcomm0).

			If the application disconnects from the D-Bus this
			connection will be terminated.

			Valid service values: "vcp", "map", "pbap", "sap",
			                      "ftp", "bpp", "bip", "synch",
			                      "dun", "opp", "fax", "spp"

		void CancelConnect(string address, string service)

			This method cancels a previous Connect method call.

		string ConnectByChannel(string address, byte channel)

			This creates a connection to a remote RFCOMM based
			service. In contrast to Connect a channel number is
			needed.

			The return value will be the path of the newly
			creates RFCOMM TTY device (for example /dev/rfcomm0).

			If the application disconnects from the D-Bus this
			connection will be terminated.

		void CancelConnectByChannel(string address, byte channel)

			This method cancels a previous ConnectByChannel
			method call.

		void Disconnect(string device)

			This will disconnect a previously connected RFCOMM
			service. The device parameter must be the return value
			from a previous Connect or ConnectByChannel method
			call (for example /dev/rfcomm0).

		string Bind(string address, string service)

		string BindByChannel(string address, byte channel)

		void Release(string device)

		array{string} ListBindings()


Signals		void Connected(string address, byte channel, string service)

			This signal will be issued once a RFCOMM connection
			has been established through Connect or ConnectByChannel
			and the service will be translated into a profile if
			it is known. Otherwise the UUID will be listed. If
			no UUID or service name is available it will be an
			empty string.

		void Disconnected(string address, byte channel, string service)

			This signal will be issued if a RFCOMM connection
			gets terminated through Disconnect or of the caller
			application disconnects from the D-Bus.


SDP hierarchy (experimental)
============================

Service		org.bluez
Interface	org.bluez.SDP
Object path	/org/bluez/{hci0,hci1,...}

Methods		array{string} GetIdentifiers(string address)

		array{string} GetIdentifiersByService(string address, string service)

		string GetUUID(string identifier)

		string GetName(string identifier)

		string RegisterRFCOMM(string service, byte channel)

		void UnregisterRFCOMM(string identifier)