Initial commit

1 files changed, 171 insertions, 0 deletions

diff --git a/doc/headset-api.txt b/doc/headset-api.txt
new file mode 100644
index 0000000..c27228c
--- /dev/null
+++ b/doc/headset-api.txt
@@ -0,0 +1,171 @@
+Headset D-Bus API description
+*****************************
+
+
+HeadsetManager hierarchy
+========================
+
+Service		org.freedesktop.Headset
+Interface	org.freedesktop.HeadsetManager
+Object path	/
+
+                The HeadsetManager interface manages the detected Devices
+                and Registered Agents.
+
+Methods         array{object,dict} GetDevices()
+
+                        Get an array of device objects and properties
+                        that represent the currently attached devices.
+
+                        This method call should only be used once when an
+                        application starts up. Further device additions
+                        and removal shall be monitored via DeviceAdded and
+                        DeviceRemoved signals.
+
+                void Register(object path, dict)
+
+                        Registers a Headset Agent with a specific
+                        path (freely selectable by the subsystem) and
+                        properties
+
+                        Possible Errors: [service].Error.InvalidArguments
+
+                void Unregister(object path)
+
+                        Unregisters a Headset Agent with specific path
+
+                        Possible Errors: [service].Error.NotFound
+                                         [service].Error.InvalidArguments
+                                         [service].Error.NotAllowed
+
+Signals         DeviceAdded(object path, dict properties)
+
+                        Signal that is sent when a new device is added.  It
+                        contains the object path of new device and its
+                        properties.
+
+                DeviceRemoved(object path)
+
+                        Signal that is sent when a device has been removed.
+                        The object path is no longer accessible after this
+                        signal and only emitted for reference.
+
+
+Headset Agent hierarchy
+=======================
+
+Service		<freely defined>
+Interface	org.freedesktop.HeadsetAgent
+Object path	<freely defined>
+
+                The Agent is used to take control of the rfcomm connection of
+                a Headset. When no Agent is registered, the Headset daemon
+                will manage the rfcomm channel itself.
+
+Methods		bool NewConnection(object device, fd rfcomm, dict properties)
+
+                        Notify the agent that a new device is connected. The Agent
+                        returns True if it will use the rfcomm fd. 
+                        When all registered Agents return False, headsetd will
+                        manage the rfcomm instead.
+
+			Possible Errors: [service].Error.NotAuthorized
+					 [service].Error.Failed
+
+                void RequestDisconnection(object device)
+                        
+                        Notify the agent that the connection with the device
+                        ended.
+
+		void Release()
+
+			Notifies the Agent that it is no longer registered
+
+
+Headset hierarchy
+=================
+
+Service		org.freedesktop.Headset
+Interface	org.freedesktop.Headset
+Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Methods		object GetTransport(dict properties)
+
+                        Get a Transport Object for the given properties
+
+			Possible Errors: [service].Error.NotAuthorized
+					 [service].Error.Failed
+
+		void ReleaseTransport(object transport)
+
+			Releases transport descriptor.
+
+Properties	object Device [readonly]
+
+			The bluetooth Device object.
+
+
+HeadsetTransport hierarchy
+==========================
+
+Service		org.freedesktop.Headset
+Interface	org.freedesktop.HeadsetTransport
+Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/fdX
+
+Methods		fd, uint16, uint16 Acquire()
+
+			Acquire transport file descriptor and the MTU for read
+			and write respectively.
+
+			Possible Errors: [service].Error.NotAuthorized
+					 [service].Error.Failed
+
+		void Release()
+
+			Releases file descriptor.
+
+Properties	object Device [readonly]
+
+			The Device object.
+
+		string UUID [readonly]
+
+			UUID of the profile which this transport is for.
+
+		byte Codec [readonly]
+
+			Assigned number of codec that the transport support.
+			The values should match the profile specification which
+			is indicated by the UUID.
+
+		string State [readonly]
+
+			Indicates the state of the transport. Possible
+			values are:
+				"idle": not streaming
+				"pending": streaming but not acquired
+				"active": streaming and acquired
+
+		uint16 Delay [readwrite]
+
+			Optional. Transport delay in 1/10 of millisecond, this
+			property is only writeable when the transport was
+			acquired by the sender.
+
+		byte MicrophoneGain [readwrite]
+
+			Optional. Indicates volume level of the transport's
+			incoming audio stream. This
+			property is only writeable when the transport was
+			acquired by the sender.
+
+			Possible Values: 0-15
+
+		byte SpeakerGain [readwrite]
+
+			Optional. Indicates volume level of the transport's
+			outgoing audio stream. This
+			property is only writeable when the transport was
+			acquired by the sender.
+
+			Possible Values: 0-15