BlueZ D-Bus Audio API description
*********************************

Copyright (C) 2004-2008  Marcel Holtmann <marcel@holtmann.org>
Copyright (C) 2005-2007  Johan Hedberg <johan.hedberg@nokia.com>
Copyright (C) 2005-2006  Brad Midgley <bmidgley@xmission.com>

Audio hierarchy
===============

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

This is a generic audio interface that abstracts the different audio profiles.

Methods		void Connect()

			Connect all supported audio profiles on the device.

		void Disconnect()

			Disconnect all audio profiles on the device

		dict GetProperties()

			Returns all properties for the interface. See the
			properties section for available properties.

Signals		void PropertyChanged(string name, variant value)

			This signal indicates a changed value of the given
			property.

Properties	string State

			Possible values: "disconnected", "connecting",
			"connected"

			"disconnected" -> "connecting"
				Either an incoming or outgoing connection
				attempt ongoing.

			"connecting" -> "disconnected"
				Connection attempt failed

			"connecting" -> "connected"
				Successfully connected

			"connected" -> "disconnected"
				Disconnected from the remote device

Headset hierarchy
=================

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

Methods		void Connect()

			Connect to the HSP/HFP service on the remote device.

		void Disconnect()

			Disconnect from the HSP/HFP service on the remote
			device.

		boolean IsConnected() {deprecated}

			Returns TRUE if there is a active connection to the
			HSP/HFP connection on the remote device.

		void IndicateCall()

			Indicate an incoming call on the headset
			connected to the stream. Will continue to
			ring the headset about every 3 seconds.

		void CancelCall()

			Cancel the incoming call indication.

		void Play()

			Open the audio connection to the headset.

		void Stop()

			Close the audio connection.

		boolean IsPlaying() {deprecated}

			Returns true if an audio connection to the headset
			is active.

		uint16 GetSpeakerGain() {deprecated}

			Returns the current speaker gain if available,
			otherwise returns the error NotAvailable.

		uint16 GetMicrophoneGain() {deprecated}

			Returns the current microphone gain if available,
			otherwise returns the error NotAvailable.

		void SetSpeakerGain(uint16 gain) {deprecated}

			Changes the current speaker gain if possible.

		void SetMicrophoneGain(uint16 gain) {deprecated}

			Changes the current speaker gain if possible.

		dict GetProperties()

			Returns all properties for the interface. See the
			properties section for available properties.

			Possible Errors: org.bluez.Error.InvalidArguments

		void SetProperty(string name, variant value)

			Changes the value of the specified property. Only
			properties that are listed a read-write are changeable.
			On success this will emit a PropertyChanged signal.

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

Signals		void AnswerRequested()

			Sent when the answer button is pressed on the headset

		void Connected() {deprecated}

			Sent when the device has been connected to.

		void Disconnected() {deprecated}

			Sent when the device has been disconnected from.

		void Stopped() {deprecated}

			Sent when the audio connection is closed

		void Playing() {deprecated}

			Sent when the audio connection is opened

		void SpeakerGainChanged(uint16 gain) {deprecated}

			The speaker gain changed.

		void MicrophoneGainChanged(uint16 gain) {deprecated}

			The microphone gain changed.

		PropertyChanged(string name, variant value)

			This signal indicates a changed value of the given
			property.

properties	string State [readonly]

			Possible values: "disconnected", "connecting",
			"connected", "playing"

			"disconnected" -> "connecting"
				Either an incoming or outgoing connection
				attempt ongoing.

			"connecting" -> "disconnected"
				Connection attempt failed

			"connecting" -> "connected"
				Successfully connected

			"connected" -> "playing"
				SCO audio connection successfully opened

			"playing" -> "connected"
				SCO audio connection closed

			"connected" -> "disconnected"
			"playing" -> "disconnected"
				Disconnected from the remote device

		boolean Connected [readonly]

			Indicates if there is a active connection to the
			HSP/HFP connection on the remote device.

		boolean Playing  [readonly]

			Indicates if an audio connection to the headset
			is active.

		uint16 SpeakerGain  [readwrite]

			The speaker gain when available.

		uint16 MicrophoneGain  [readwrite]

			The speaker gain when available.


AudioSink hierarchy
===================

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

Methods		void Connect()

			Connect and setup a stream to a A2DP sink on the
			remote device.

		void Disconnect()

			Disconnect from the remote device.

		boolean IsConnected() {deprecated}

			Returns TRUE if a stream is setup to a A2DP sink on
			the remote device.

		dict GetProperties()

			Returns all properties for the interface. See the
			properties section for available properties.

			Possible Errors: org.bluez.Error.InvalidArguments

Signals		void Connected() {deprecated}

			Sent when a successful connection has been made to the
			remote A2DP Sink

		void Disconnected() {deprecated}

			Sent when the device has been disconnected from.

		void Playing() {deprecated}

			Sent when a stream with remote device is started.

		void Stopped() {deprecated}

			Sent when a stream with remote device is suspended.

		PropertyChanged(string name, variant value)

			This signal indicates a changed value of the given
			property.

properties	string State [readonly]

			Possible values: "disconnected", "connecting",
			"connected", "playing"

			"disconnected" -> "connecting"
				Either an incoming or outgoing connection
				attempt ongoing.

			"connecting" -> "disconnected"
				Connection attempt failed

			"connecting" -> "connected"
				Successfully connected

			"connected" -> "playing"
				Audio stream active

			"playing" -> "connected"
				Audio stream suspended

			"connected" -> "disconnected"
			"playing" -> "disconnected"
				Disconnected from the remote device

		boolean Connected [readonly]

			Indicates if a stream is setup to a A2DP sink on
			the remote device.

		boolean Playing  [readonly]

			Indicates if a stream is active to a A2DP sink on
			the remote device.


HeadsetGateway hierarchy
========================

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

This interface is available for remote devices which can function in the Audio
Gateway role of the HFP profiles.

Methods		void Connect()

			Connect to the AG service on the remote device.

		void Disconnect()

			Disconnect from the AG service on the remote device

		void AnswerCall()

			It has to called only after Ring signal received.

		void TerminateCall()

			Terminate call which is running or reject an incoming
			call. This has nothing with any 3-way situation incl.
			RaH. Just plain old PDH.

		void Call(string number)

			Dial a number 'number'. No number processing is done
			thus if AG would reject to dial it don't blame me :)

		string GetOperatorName()

			Find out the name of the currently selected network
			operator by AG.

		void SendDTMF(string digits)

			Will send each digit in the 'digits' sequentially. Would
			send nothing if there is non-dtmf digit.

		string GetSubscriberNumber()

			Get the voicecall subscriber number of AG

		dict GetProperties()

			Returns all properties for the interface. See the
			properties section for available properties.

Signals		void Ring(string number)

			Someone's calling from 'number'.
			Caller number is provided as received from AG.

		void CallTerminated()

			Call failed to set up. It means that we tried to call
			someone or someone tried to call us but call was not
			accepted.

		void CallStarted()

			Call set up successfully.

		void CallEnded()

			Call was started and now ended. In contrast with
			CallTerminated where call didn't started

		PropertyChanged(string name, variant value)

			This signal indicates a changed value of the given
			property.

properties	boolean Connected [readonly]

			Indicates if there is an active connection to the
			AG service on the remote device.

		uint16 RegistrationStatus [readonly]

			Service availability indicatior of AG, where:
			0 implies no service. No Home/Roam network available.
			1 implies presense of service. Home/Roam network
			available.

		uint16 SignalStrength [readonly]

			Signal strength indicator of AG, the value ranges from
			0 to 5.

		uint16 RoamingStatus [readonly]

			Roaming status indicator of AG, where:
			0 means roaming is not active
			1 means a roaming is active

		uint16 BatteryCharge [readonly]

			Battery Charge indicator of AG, the value ranges from
			0 to 5.

		uint16 SpeakerGain  [readonly]

			The speaker gain when available.

		uint16 MicrophoneGain  [readonly]

			The speaker gain when available.