mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-12-24 11:23:41 +08:00
c50a8a397d
Add btd_request_authorization_cable_configured() function to allow cable configured devices to ask the user straight away about whether the device should be allowed to connect to the computer. This allows us to ask the user at the time of the USB connection and initial setup, rather than when the first Bluetooth connection is made. The fact that the device might not be connected to the adapter when this event is triggered is mentioned in the Agent API docs.
186 lines
5.5 KiB
Plaintext
186 lines
5.5 KiB
Plaintext
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.
|