doc/agent-api.txt

   1 BlueZ D-Bus Agent API description
   2 **********************************
   3
   4 Copyright (C) 2004-2010  Marcel Holtmann <marcel@holtmann.org>
   5 Copyright (C) 2005-2006  Johan Hedberg <johan.hedberg@nokia.com>
   6
   7
   8 Agent hierarchy
   9 ===============
  10
  11 Service         unique name
  12 Interface       org.bluez.Agent
  13 Object path     freely definable
  14
  15 Methods         void Release()
  16
  17                         This method gets called when the service daemon
  18                         unregisters the agent. An agent can use it to do
  19                         cleanup tasks. There is no need to unregister the
  20                         agent, because when this method gets called it has
  21                         already been unregistered.
  22
  23                 string RequestPinCode(object device)
  24
  25                         This method gets called when the service daemon
  26                         needs to get the passkey for an authentication.
  27
  28                         The return value should be a string of 1-16 characters
  29                         length. The string can be alphanumeric.
  30
  31                         Possible errors: org.bluez.Error.Rejected
  32                                          org.bluez.Error.Canceled
  33
  34                 uint32 RequestPasskey(object device)
  35
  36                         This method gets called when the service daemon
  37                         needs to get the passkey for an authentication.
  38
  39                         The return value should be a numeric value
  40                         between 0-999999.
  41
  42                         Possible errors: org.bluez.Error.Rejected
  43                                          org.bluez.Error.Canceled
  44
  45                 void DisplayPasskey(object device, uint32 passkey, uint8 entered)
  46
  47                         This method gets called when the service daemon
  48                         needs to display a passkey for an authentication.
  49
  50                         The entered parameter indicates the number of already
  51                         typed keys on the remote side.
  52
  53                         An empty reply should be returned. When the passkey
  54                         needs no longer to be displayed, the Cancel method
  55                         of the agent will be called.
  56
  57                         During the pairing process this method might be
  58                         called multiple times to update the entered value.
  59
  60                         Note that the passkey will always be a 6-digit number,
  61                         so the display should be zero-padded at the start if
  62                         the value contains less than 6 digits.
  63
  64                 void DisplayPinCode(object device, string pincode)
  65
  66                         This method gets called when the service daemon
  67                         needs to display a pincode for an authentication.
  68
  69                         An empty reply should be returned. When the pincode
  70                         needs no longer to be displayed, the Cancel method
  71                         of the agent will be called.
  72
  73                         If this method is not implemented the RequestPinCode
  74                         method will be used instead.
  75
  76                         This is used during the pairing process of keyboards
  77                         that don't support Bluetooth 2.1 Secure Simple Pairing,
  78                         in contrast to DisplayPasskey which is used for those
  79                         that do.
  80
  81                         This method will only ever be called once since
  82                         older keyboards do not support typing notification.
  83
  84                         Note that the PIN will always be a 6-digit number,
  85                         zero-padded to 6 digits. This is for harmony with
  86                         the later specification.
  87
  88                 void RequestConfirmation(object device, uint32 passkey)
  89
  90                         This method gets called when the service daemon
  91                         needs to confirm a passkey for an authentication.
  92
  93                         To confirm the value it should return an empty reply
  94                         or an error in case the passkey is invalid.
  95
  96                         Note that the passkey will always be a 6-digit number,
  97                         so the display should be zero-padded at the start if
  98                         the value contains less than 6 digits.
  99
 100                         Possible errors: org.bluez.Error.Rejected
 101                                          org.bluez.Error.Canceled
 102
 103                 void Authorize(object device, string uuid)
 104
 105                         This method gets called when the service daemon
 106                         needs to authorize a connection/service request.
 107
 108                         Possible errors: org.bluez.Error.Rejected
 109                                          org.bluez.Error.Canceled
 110
 111                 void ConfirmModeChange(string mode)
 112
 113                         This method gets called if a mode change is requested
 114                         that needs to be confirmed by the user. An example
 115                         would be leaving flight mode.
 116
 117                         Possible errors: org.bluez.Error.Rejected
 118                                          org.bluez.Error.Canceled
 119
 120                 void Cancel()
 121
 122                         This method gets called to indicate that the agent
 123                         request failed before a reply was returned.