doc/agent-api.txt

   1 BlueZ D-Bus Agent API description
   2 **********************************
   3
   4
   5 Agent Manager hierarchy
   6 =======================
   7
   8 Service         org.bluez
   9 Interface       org.bluez.AgentManager1
  10 Object path     /org/bluez
  11
  12                 void RegisterAgent(object agent, string capability)
  13
  14                         This registers an agent handler.
  15
  16                         The object path defines the path of the agent
  17                         that will be called when user input is needed.
  18
  19                         Every application can register its own agent and
  20                         for all actions triggered by that application its
  21                         agent is used.
  22
  23                         It is not required by an application to register
  24                         an agent. If an application does chooses to not
  25                         register an agent, the default agent is used. This
  26                         is on most cases a good idea. Only application
  27                         like a pairing wizard should register their own
  28                         agent.
  29
  30                         An application can only register one agent. Multiple
  31                         agents per application is not supported.
  32
  33                         The capability parameter can have the values
  34                         "DisplayOnly", "DisplayYesNo", "KeyboardOnly",
  35                         "NoInputNoOutput" and "KeyboardDisplay" which
  36                         reflects the input and output capabilities of the
  37                         agent.
  38
  39                         If an empty string is used it will fallback to
  40                         "KeyboardDisplay".
  41
  42                         Possible errors: org.bluez.Error.InvalidArguments
  43                                          org.bluez.Error.AlreadyExists
  44
  45                 void UnregisterAgent(object agent)
  46
  47                         This unregisters the agent that has been previously
  48                         registered. The object path parameter must match the
  49                         same value that has been used on registration.
  50
  51                         Possible errors: org.bluez.Error.DoesNotExist
  52
  53                 void RequestDefaultAgent(object agent)
  54
  55                         This requests is to make the application agent
  56                         the default agent. The application is required
  57                         to register an agent.
  58
  59                         Special permission might be required to become
  60                         the default agent.
  61
  62                         Possible errors: org.bluez.Error.DoesNotExist
  63
  64
  65 Agent hierarchy
  66 ===============
  67
  68 Service         unique name
  69 Interface       org.bluez.Agent1
  70 Object path     freely definable
  71
  72 Methods         void Release()
  73
  74                         This method gets called when the service daemon
  75                         unregisters the agent. An agent can use it to do
  76                         cleanup tasks. There is no need to unregister the
  77                         agent, because when this method gets called it has
  78                         already been unregistered.
  79
  80                 string RequestPinCode(object device)
  81
  82                         This method gets called when the service daemon
  83                         needs to get the passkey for an authentication.
  84
  85                         The return value should be a string of 1-16 characters
  86                         length. The string can be alphanumeric.
  87
  88                         Possible errors: org.bluez.Error.Rejected
  89                                          org.bluez.Error.Canceled
  90
  91                 void DisplayPinCode(object device, string pincode)
  92
  93                         This method gets called when the service daemon
  94                         needs to display a pincode for an authentication.
  95
  96                         An empty reply should be returned. When the pincode
  97                         needs no longer to be displayed, the Cancel method
  98                         of the agent will be called.
  99
 100                         This is used during the pairing process of keyboards
 101                         that don't support Bluetooth 2.1 Secure Simple Pairing,
 102                         in contrast to DisplayPasskey which is used for those
 103                         that do.
 104
 105                         This method will only ever be called once since
 106                         older keyboards do not support typing notification.
 107
 108                         Note that the PIN will always be a 6-digit number,
 109                         zero-padded to 6 digits. This is for harmony with
 110                         the later specification.
 111
 112                         Possible errors: org.bluez.Error.Rejected
 113                                          org.bluez.Error.Canceled
 114
 115                 uint32 RequestPasskey(object device)
 116
 117                         This method gets called when the service daemon
 118                         needs to get the passkey for an authentication.
 119
 120                         The return value should be a numeric value
 121                         between 0-999999.
 122
 123                         Possible errors: org.bluez.Error.Rejected
 124                                          org.bluez.Error.Canceled
 125
 126                 void DisplayPasskey(object device, uint32 passkey,
 127                                                                 uint16 entered)
 128
 129                         This method gets called when the service daemon
 130                         needs to display a passkey for an authentication.
 131
 132                         The entered parameter indicates the number of already
 133                         typed keys on the remote side.
 134
 135                         An empty reply should be returned. When the passkey
 136                         needs no longer to be displayed, the Cancel method
 137                         of the agent will be called.
 138
 139                         During the pairing process this method might be
 140                         called multiple times to update the entered value.
 141
 142                         Note that the passkey will always be a 6-digit number,
 143                         so the display should be zero-padded at the start if
 144                         the value contains less than 6 digits.
 145
 146                 void RequestConfirmation(object device, uint32 passkey)
 147
 148                         This method gets called when the service daemon
 149                         needs to confirm a passkey for an authentication.
 150
 151                         To confirm the value it should return an empty reply
 152                         or an error in case the passkey is invalid.
 153
 154                         Note that the passkey will always be a 6-digit number,
 155                         so the display should be zero-padded at the start if
 156                         the value contains less than 6 digits.
 157
 158                         Possible errors: org.bluez.Error.Rejected
 159                                          org.bluez.Error.Canceled
 160
 161                 void RequestAuthorization(object device)
 162
 163                         This method gets called to request the user to
 164                         authorize an incoming pairing attempt which
 165                         would in other circumstances trigger the just-works
 166                         model.
 167
 168                         Possible errors: org.bluez.Error.Rejected
 169                                          org.bluez.Error.Canceled
 170
 171                 void AuthorizeService(object device, string uuid)
 172
 173                         This method gets called when the service daemon
 174                         needs to authorize a connection/service request.
 175
 176                         Possible errors: org.bluez.Error.Rejected
 177                                          org.bluez.Error.Canceled
 178
 179                 void Cancel()
 180
 181                         This method gets called to indicate that the agent
 182                         request failed before a reply was returned.