dbus-api.txt

Linux的蓝牙操作工具。配合bluez-lib使用

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

Copyright (C) 2004-2007  Marcel Holtmann <[e-mail]>
Copyright (C) 2005-2006  Johan Hedberg <[e-mail]>
Copyright (C) 2005-2006  Claudio Takahasi <[e-mail]>
Copyright (C) 2005-2006  Eduardo Rocha <[e-mail]>


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

Shared Errors (Can be thrown by hcid or any bluetooth service)
		
		DeviceUnreachable
		
			The remote device is either powered down or out of range.

		AlreadyConnected
			A connection request has been received on an already
			connected device.

		ConnectionAttemptFailed

			An unexpected error (other than DeviceUnreachable) error
			has occured while attempting a connection to a device.

		NotConnected
			The remote device is not connected, while the method call
			would expect it to be, or is not in the expected state to
			perform the action.

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

		InvalidArguments

			The DBUS request does not contain the right number of
			arguments with the right type, or the arguments are there 
			but their value is wrong, or does not makes sense in the
			current context.

		OutOfMemory

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

		NotAvailable

			Error returned when a specified record is not
			available.

		NotSupported 
			
			The remote device does not support the expected
			feature.

		AlreadyExists
			One of the requested elements already exists

		DoesNotExist
			One of the requested elements does not exist

		Canceled
			The operation was canceled.

		Failed

			This is a the most generic error.
			It is thrown when something unexpected happens.


Hcid specific Errors (Can be thrown by hcid only)

		NotReady

			Error returned when the adapter is DOWN.

		UnknwownMethod
		
			This is an experimental 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.

		Rejected

		NoSuchAdapter

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

		NoSuchService
		
		RequestDeferred
		
		NotInProgress

		UnsupportedMajorClass

		AuthenticationCanceled

		AuthenticationFailed

		AuthenticationTimeout

		AuthenticationRejected

		RepeatedAttempts

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.

			Possible errors: org.bluez.Error.InvalidArguments

		string DefaultAdapter()

			Returns object path for the default adapter.

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

		string FindAdapter(string pattern)

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

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

		array{string} ListAdapters()

			Returns list of adapter object paths under /org/bluez

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

		string FindService(string pattern)

			Returns object path for the specified service. Valid
			patterns are the unqiue identifier or a bus name.

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

		array{string} ListServices()

			Returns list of object paths of current services.

			Possible errors: org.bluez.Error.InvalidArguments

		string ActivateService(string pattern)

			Returns the unqiue bus id of the specified service.
			Valid patterns are the same as for FindService(). If
			the service is not running it will be started.

Signals		void AdapterAdded(string path)

			Parameter is object path of added adapter.

		void AdapterRemoved(string path)

			Parameter is object path of removed adapter.

		void DefaultAdapterChanged(string path)

			Parameter is object path of the new default adapter.

		void ServiceAdded(string path)

			Parameter is object path of registered service agent.

		void ServiceRemoved(string path)

			Parameter is object path of unregistered service agent.


Database hierarchy
==================

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

Methods		void RegisterService(string identifier, string name, string description)

			This method registers a new service specified by
			its unique identifier. This is only needed for
			services that are not started through the
			Bluetooth daemon.

		void UnregisterService(string identifier)

			This method unregisters a service specified by
			its unique identifier.

		uint32 AddServiceRecord(array{byte})

			Adds a new service record and returns the assigned
			record handle.

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

		uint32 AddServiceRecordFromXML(string record)

			Adds a new service record and returns the assigned
			record handle.

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

		void UpdateServiceRecord(uint32 handle, array{byte})

			Updates a given service record.

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

		void UpdateServiceRecordFromXML(uint32 handle, string record)

			Updates a given service record provided in the
			XML format.

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

		void RemoveServiceRecord(uint32 handle)

			Remove a service record identified by its handle.

			It is only possible to remove service records that
			where added by the current connection.

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

		void RequestAuthorization(string address, string uuid)

			This method gets called when a service wants to check
			if a remote device is authorized to perform some
			action. The authorization request is forwarded to an
			authorization agent.

			The address parameter is the Bluetooth address of the
			remote device and the uuid is the identifier of the
			profile requesting the authorization. This parameter
			can also be left blank.

		void CancelAuthorizationRequest(string address, string uuid)

			This method cancels an authorization process requested
			by a previous call to RequestAuthorization(). The
			address and uuid parameters must match.


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

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

Methods		dict GetInfo()

			Returns the properties of the local adapter.

		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: org.bluez.Error.Failed

		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: org.bluez.Error.Failed

		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: org.bluez.Error.Failed

		array{string} ListAvailableModes()

			Returns a list of available modes the adapter can
			be switched into.

		string GetMode()

			Returns the current mode of a adapter.

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

			Possible errors: none

		void SetMode(string mode)

			Sets mode of the adapter. See GetMode for valid strings
			for the mode parameter. In addition to the valid strings
			for GetMode, this method also supports a special
			parameter value "on" which will change the mode to the
			previous non-off mode (or do nothing if the current
			mode isn't "off").

			Possible errors: org.bluez.Error.NoSuchAdapter
					 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/limited 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/limited.

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

			Possible errors: org.bluez.Error.NotReady
					 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/limited
			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. Currently, only "computer" is supported.
			For the other values, unsupported major class
			error is returned.

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

		array{string} ListAvailableMinorClasses()