doc: Describe the new agent manager support

1 files changed, 60 insertions, 0 deletions

diff --git a/doc/agent-api.txt b/doc/agent-api.txt
index a1a8969aa..28063b3cc 100644
--- a/doc/agent-api.txt
+++ b/doc/agent-api.txt
@@ -5,6 +5,66 @@ Copyright (C) 2004-2010  Marcel Holtmann <marcel@holtmann.org>
 Copyright (C) 2005-2006  Johan Hedberg <johan.hedberg@nokia.com>
 
 
+Agent Manager hierarchy
+=======================
+
+Service		org.bluez
+Interface	org.bluez.AgentManager1
+Object path	/org/bluez
+
+		void RegisterAgent(object agent, string capability)
+
+			This registers an agent handler.
+
+			The object path defines the path of the agent
+			that will be called when user input is needed.
+
+			Every application can register its own agent and
+			for all actions triggered by that application its
+			agent is used.
+
+			It is not required by an application to register
+			an agent. If an application does chooses to not
+			register an agent, the default agent is used. This
+			is on most cases a good idea. Only application
+			like a pairing wizard should register their own
+			agent.
+
+			An application can only register one agent. Multiple
+			agents per application is not supported.
+
+			The capability parameter can have the values
+			"DisplayOnly", "DisplayYesNo", "KeyboardOnly",
+			"NoInputNoOutput" and "KeyboardDisplay" which
+			reflects the input and output capabilities of the
+			agent.
+
+			If an empty string is used it will fallback to
+			"DisplayYesNo".
+
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.AlreadyExists
+
+		void UnregisterAgent(object agent)
+
+			This unregisters the agent that has been previously
+			registered. The object path parameter must match the
+			same value that has been used on registration.
+
+			Possible errors: org.bluez.Error.DoesNotExist
+
+		void RequestDefaultAgent()
+
+			This requests is to make the application agent
+			the default agent. The application is required
+			to register an agent.
+
+			Special permission might be required to become
+			the default agent.
+
+			Possible errors: org.bluez.Error.DoesNotExist
+
+
 Agent hierarchy
 ===============