doc/agent-api.txt

BlueZ D-Bus Agent API description
**********************************


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

			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(object agent)

			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
===============

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

Methods		void Release()

			This method gets called when the service daemon
			unregisters the 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.

		string RequestPinCode(object device)

			This method gets called when the service daemon
			needs to get the passkey for an authentication.

			The return value should be a string of 1-16 characters
			length. The string can be alphanumeric.

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

		void DisplayPinCode(object device, string pincode)

			This method gets called when the service daemon
			needs to display a pincode for an authentication.

			An empty reply should be returned. When the pincode
			needs no longer to be displayed, the Cancel method
			of the agent will be called.

			This is used during the pairing process of keyboards
			that don't support Bluetooth 2.1 Secure Simple Pairing,
			in contrast to DisplayPasskey which is used for those
			that do.

			This method will only ever be called once since
			older keyboards do not support typing notification.

			Note that the PIN will always be a 6-digit number,
			zero-padded to 6 digits. This is for harmony with
			the later specification.

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

		uint32 RequestPasskey(object device)

			This method gets called when the service daemon
			needs to get the passkey for an authentication.

			The return value should be a numeric value
			between 0-999999.

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

		void DisplayPasskey(object device, uint32 passkey,
								uint16 entered)

			This method gets called when the service daemon
			needs to display a passkey for an authentication.

			The entered parameter indicates the number of already
			typed keys on the remote side.

			An empty reply should be returned. When the passkey
			needs no longer to be displayed, the Cancel method
			of the agent will be called.

			During the pairing process this method might be
			called multiple times to update the entered value.

			Note that the passkey will always be a 6-digit number,
			so the display should be zero-padded at the start if
			the value contains less than 6 digits.

		void RequestConfirmation(object device, uint32 passkey)

			This method gets called when the service daemon
			needs to confirm a passkey for an authentication.

			To confirm the value it should return an empty reply
			or an error in case the passkey is invalid.

			Note that the passkey will always be a 6-digit number,
			so the display should be zero-padded at the start if
			the value contains less than 6 digits.

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

		void RequestAuthorization(object device)

			This method gets called to request the user to
			authorize an incoming pairing attempt which
			would in other circumstances trigger the just-works
			model, or when the user plugged in a device that
			implements cable pairing. In the latter case, the
			device would not be connected to the adapter via
			Bluetooth yet.

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

		void AuthorizeService(object device, string uuid)

			This method gets called when the service daemon
			needs to authorize a connection/service request.

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

		void Cancel()

			This method gets called to indicate that the agent
			request failed before a reply was returned.