From: Luiz Augusto von Dentz <[email protected]>
This renames agent-api.txt to org.bluez.Agent{Manager}.rst and generate
manpages org.bluez.Agent{Manager}.5.
---
Makefile.am | 11 +-
doc/agent-api.txt | 185 ---------------------------------
doc/org.bluez.Agent.rst | 149 ++++++++++++++++++++++++++
doc/org.bluez.AgentManager.rst | 83 +++++++++++++++
4 files changed, 239 insertions(+), 189 deletions(-)
delete mode 100644 doc/agent-api.txt
create mode 100644 doc/org.bluez.Agent.rst
create mode 100644 doc/org.bluez.AgentManager.rst
diff --git a/Makefile.am b/Makefile.am
index 9e74f4f0fc76..b25bc521cab3 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -358,7 +358,8 @@ CLEANFILES += $(builtin_files) src/bluetooth.service
if MANPAGES
man_MANS += src/bluetoothd.8
man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
- doc/org.bluez.DeviceSet.5
+ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
+ doc/org.bluez.Agent.5
man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
@@ -366,7 +367,8 @@ man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
endif
manual_pages += src/bluetoothd.8
manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
- doc/org.bluez.DeviceSet.5
+ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
+ doc/org.bluez.Agent.5
manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
@@ -407,12 +409,13 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
doc/settings-storage.txt
EXTRA_DIST += doc/mgmt-api.txt \
- doc/agent-api.txt doc/profile-api.txt \
+ doc/profile-api.txt \
doc/network-api.txt doc/health-api.txt \
doc/sap-api.txt doc/input-api.txt
EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
- doc/org.bluez.DeviceSet.rst
+ doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
+ doc/org.bluez.Agent.rst
EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \
doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \
diff --git a/doc/agent-api.txt b/doc/agent-api.txt
deleted file mode 100644
index 0d9347cab390..000000000000
--- a/doc/agent-api.txt
+++ /dev/null
@@ -1,185 +0,0 @@
-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.
diff --git a/doc/org.bluez.Agent.rst b/doc/org.bluez.Agent.rst
new file mode 100644
index 000000000000..11d09b94d228
--- /dev/null
+++ b/doc/org.bluez.Agent.rst
@@ -0,0 +1,149 @@
+===============
+org.bluez.Agent
+===============
+
+-----------------------------------
+BlueZ D-Bus Agent API documentation
+-----------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+: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.
diff --git a/doc/org.bluez.AgentManager.rst b/doc/org.bluez.AgentManager.rst
new file mode 100644
index 000000000000..dfc0297da8d2
--- /dev/null
+++ b/doc/org.bluez.AgentManager.rst
@@ -0,0 +1,83 @@
+======================
+org.bluez.AgentManager
+======================
+
+------------------------------------------
+BlueZ D-Bus AgentManager API documentation
+------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service: org.bluez
+:Interface: org.bluez.AgentManager1
+:Object path: /org/bluez
+
+Methods
+-------
+
+void RegisterAgent(object agent, string capability)
+```````````````````````````````````````````````````
+
+ Registers pairing agent.
+
+ The object path defines the path of the agent that will be called when
+ user input is needed and must implement **org.bluez.Agent(5)**
+ interface.
+
+ 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.
+
+ Possible capability values:
+
+ :"":
+
+ Fallback to "KeyboardDisplay".
+
+ :"DisplayOnly":
+ :"DisplayYesNo":
+ :"KeyboardOnly":
+ :"NoInputNoOutput":
+ :"KeyboardDisplay":
+
+ Possible errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.AlreadyExists:
+
+void UnregisterAgent(object agent)
+``````````````````````````````````
+
+ Unregisters an agent that has been previously registered using
+ **RegisterAgent**. 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)
+``````````````````````````````````````
+
+ Requests 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:
+
--
2.41.0