doc/adapter-api.txt

   1 BlueZ D-Bus Adapter API description
   2 ***********************************
   3
   4
   5 Adapter hierarchy
   6 =================
   7
   8 Service         org.bluez
   9 Interface       org.bluez.Adapter1
  10 Object path     [variable prefix]/{hci0,hci1,...}
  11
  12 Methods         void StartDiscovery()
  13
  14                         This method starts the device discovery session. This
  15                         includes an inquiry procedure and remote device name
  16                         resolving. Use StopDiscovery to release the sessions
  17                         acquired.
  18
  19                         This process will start creating Device objects as
  20                         new devices are discovered.
  21
  22                         During discovery RSSI delta-threshold is imposed.
  23
  24                         Possible errors: org.bluez.Error.NotReady
  25                                          org.bluez.Error.Failed
  26
  27                 void StopDiscovery()
  28
  29                         This method will cancel any previous StartDiscovery
  30                         transaction.
  31
  32                         Note that a discovery procedure is shared between all
  33                         discovery sessions thus calling StopDiscovery will only
  34                         release a single session.
  35
  36                         Possible errors: org.bluez.Error.NotReady
  37                                          org.bluez.Error.Failed
  38                                          org.bluez.Error.NotAuthorized
  39
  40                 void RemoveDevice(object device)
  41
  42                         This removes the remote device object at the given
  43                         path. It will remove also the pairing information.
  44
  45                         Possible errors: org.bluez.Error.InvalidArguments
  46                                          org.bluez.Error.Failed
  47
  48                 void SetDiscoveryFilter(dict filter) [Experimental]
  49
  50                         This method sets the device discovery filter for the
  51                         caller. When this method is called with no filter
  52                         parameter, filter is removed.
  53
  54                         Parameters that may be set in the filter dictionary
  55                         include the following:
  56
  57                         array{string} UUIDs     : filtered service UUIDs
  58                         int16         RSSI      : RSSI threshold value
  59                         uint16        Pathloss  : Pathloss threshold value
  60                         string        Transport : type of scan to run
  61
  62                         When a remote device is found that advertises any UUID
  63                         from UUIDs, it will be reported if:
  64                         - Pathloss and RSSI are both empty,
  65                         - only Pathloss param is set, device advertise TX pwer,
  66                           and computed pathloss is less than Pathloss param,
  67                         - only RSSI param is set, and received RSSI is higher
  68                           than RSSI param,
  69
  70                         Transport parameter determines the type of scan:
  71                                 "auto"  - interleaved scan, default value
  72                                 "bredr" - BR/EDR inquiry
  73                                 "le"    - LE scan only
  74
  75                         If "le" or "bredr" Transport is requested, and the
  76                         controller doesn't support it, org.bluez.Error.Failed
  77                         error will be returned. If "auto" transport is
  78                         requested, scan will use LE, BREDR, or both, depending
  79                         on what's currently enabled on the controller.
  80
  81                         When discovery filter is set, Device objects will be
  82                         created as new devices with matching criteria are
  83                         discovered. PropertiesChanged signals will be emitted
  84                         for already existing Device objects, with updated RSSI
  85                         value. If one or more discovery filters have been set,
  86                         the RSSI delta-threshold, that is imposed by
  87                         StartDiscovery by default, will not be applied.
  88
  89                         When multiple clients call SetDiscoveryFilter, their
  90                         filters are internally merged, and notifications about
  91                         new devices are sent to all clients. Therefore, each
  92                         client must check that device updates actually match
  93                         its filter.
  94
  95                         When SetDiscoveryFilter is called multiple times by the
  96                         same client, last filter passed will be active for
  97                         given client.
  98
  99                         SetDiscoveryFilter can be called before StartDiscovery.
 100                         It is useful when client will create first discovery
 101                         session, to ensure that proper scan will be started
 102                         right after call to StartDiscovery.
 103
 104                         Possible errors: org.bluez.Error.NotReady
 105                                          org.bluez.Error.NotSupported
 106                                          org.bluez.Error.Failed
 107
 108 #ifdef __TIZEN_PATCH__
 109                 void StartCustomDiscovery(string pattern)
 110
 111                         This method starts the device discovery session with
 112                         parameter. The valid paramter strings are "BREDR",
 113                         "LE" or "LE_BREDR" which will perform the inquiry for
 114                         appropriate types. This includes an inquiry procedure
 115                         and remote device name resolving. Use StopDiscovery
 116                         to release the sessions acquired.
 117
 118                         This process will start creating Device objects as
 119                         new devices are discovered.
 120
 121                         Possible errors: org.bluez.Error.NotReady
 122                                          org.bluez.Error.Failed
 123
 124                 void StartLEDiscovery()
 125
 126                         This method starts the LE device discovery session.
 127                         General discovery and active scan is default.
 128                         Use StopLEDiscovery to release the sessions
 129                         acquired.
 130
 131                         This process will start emitting DeviceFound and
 132                         PropertyChanged "LEDiscovering" signals.
 133
 134                         Possible errors: org.bluez.Error.NotReady
 135                                          org.bluez.Error.Failed
 136
 137                 void StopLEDiscovery()
 138
 139                         This method will cancel any previous StartLEDiscovery
 140                         transaction.
 141
 142                         Note that a discovery procedure is shared between all
 143                         discovery sessions thus calling StopLEDiscovery will only
 144                         release a single session.
 145
 146                         Possible errors: org.bluez.Error.NotReady
 147                                          org.bluez.Error.Failed
 148                                          org.bluez.Error.NotAuthorized
 149
 150                 void SetAdvertising(boolean enable)
 151
 152                         This method is used to set LE advertising on a
 153                         controller that supports it.
 154
 155                         This process will emit PropertyChanged "Advertising"
 156                         signal.
 157
 158                         Possible errors: org.bluez.Error.NotReady
 159                                         org.bluez.Error.InvalidArguments
 160                                         org.bluez.Error.Failed
 161
 162                 void SetAdvertisingParameters(uint32 interval_min,
 163                                                 uint32 interval_max, uint32 filter_policy,
 164                                                 uint32 type)
 165
 166                         This method allows for setting the Low Energy
 167                         advertising interval and advertising filter policy.
 168                         It is only supported on controller with LE support.
 169
 170                         Possible errors: org.bluez.Error.NotReady
 171                                         org.bluez.Error.Failed
 172
 173                 void SetAdvertisingData(array{byte} value)
 174
 175                         This method is used to set LE advertising data on a
 176                         controller that supports it.
 177
 178                         Possible errors: org.bluez.Error.NotReady
 179                                         org.bluez.Error.InvalidArguments
 180                                         org.bluez.Error.Failed
 181
 182                 void SetScanParameters(uint32 type, uint32 interval, uint32 window)
 183
 184                         This method allows for setting the Low Energy
 185                         scan interval and window.
 186                         It is only supported on controller with LE support.
 187
 188                         Possible errors: org.bluez.Error.NotReady
 189                                         org.bluez.Error.Failed
 190
 191                 void SetScanRespData(array{byte} value)
 192
 193                         This method is used to set LE scan response data on
 194                         a controller that supports it.
 195
 196                         Possible errors: org.bluez.Error.NotReady
 197                                         org.bluez.Error.InvalidArguments
 198                                         org.bluez.Error.Failed
 199
 200                 void AddDeviceWhiteList(string address, uint32 address_type)
 201
 202                         This method is used to add LE device to White List for given
 203                         address.
 204
 205                         Possible errors: org.bluez.Error.NotReady
 206                                         org.bluez.Error.InvalidArguments
 207                                         org.bluez.Error.Failed
 208
 209                 void RemoveDeviceWhiteList(string address, uint32 address_type)
 210
 211                         This method is used to remove LE device to White List for given
 212                         address.
 213
 214                         Possible errors: org.bluez.Error.NotReady
 215                                         org.bluez.Error.InvalidArguments
 216                                         org.bluez.Error.Failed
 217
 218                 void ClearDeviceWhiteList()
 219
 220                         This method is used to clear LE device to White List
 221
 222                         Possible errors: org.bluez.Error.NotReady
 223                                         org.bluez.Error.Failed
 224
 225                 void SetLePrivacy(boolean enable_privacy)
 226
 227                         This method is used to set/reset LE privacy feature for the local
 228                         adapter when it supports the feature.
 229
 230                         Possible errors: org.bluez.Error.NotReady
 231                                         org.bluez.Error.InvalidArguments
 232                                         org.bluez.Error.Failed
 233
 234                 void SetLeStaticRandomAddress(boolean enable_random_address)
 235
 236                         This method is used to set/reset LE static random address for the local
 237                         adapter when it supports the feature.
 238
 239                         Possible errors: org.bluez.Error.NotReady
 240                                         org.bluez.Error.InvalidArguments
 241                                         org.bluez.Error.Failed
 242
 243                 void SetManufacturerData(array{byte} value)
 244
 245                         This method is used to set Manufacturer data on a
 246                         controller that supports it.
 247
 248                         Possible errors: org.bluez.Error.NotReady
 249                                         org.bluez.Error.InvalidArguments
 250                                         org.bluez.Error.Failed
 251
 252                 void CreateDevice(string address)
 253
 254                         Creates a new object path for a remote device. This
 255                         method will connect to the remote device and retrieve
 256                         all SDP records.
 257
 258                         Possible errors: org.bluez.Error.InvalidArguments
 259 #endif
 260
 261 Properties      string Address [readonly]
 262
 263                         The Bluetooth device address.
 264
 265                 string Name [readonly]
 266
 267                         The Bluetooth system name (pretty hostname).
 268
 269                         This property is either a static system default
 270                         or controlled by an external daemon providing
 271                         access to the pretty hostname configuration.
 272
 273                 string Alias [readwrite]
 274
 275                         The Bluetooth friendly name. This value can be
 276                         changed.
 277
 278                         In case no alias is set, it will return the system
 279                         provided name. Setting an empty string as alias will
 280                         convert it back to the system provided name.
 281
 282                         When resetting the alias with an empty string, the
 283                         property will default back to system name.
 284
 285                         On a well configured system, this property never
 286                         needs to be changed since it defaults to the system
 287                         name and provides the pretty hostname. Only if the
 288                         local name needs to be different from the pretty
 289                         hostname, this property should be used as last
 290                         resort.
 291
 292                 uint32 Class [readonly]
 293
 294                         The Bluetooth class of device.
 295
 296                         This property represents the value that is either
 297                         automatically configured by DMI/ACPI information
 298                         or provided as static configuration.
 299
 300                 boolean Powered [readwrite]
 301
 302                         Switch an adapter on or off. This will also set the
 303                         appropriate connectable state of the controller.
 304
 305                         The value of this property is not persistent. After
 306                         restart or unplugging of the adapter it will reset
 307                         back to false.
 308
 309                 boolean Discoverable [readwrite]
 310
 311                         Switch an adapter to discoverable or non-discoverable
 312                         to either make it visible or hide it. This is a global
 313                         setting and should only be used by the settings
 314                         application.
 315
 316                         If the DiscoverableTimeout is set to a non-zero
 317                         value then the system will set this value back to
 318                         false after the timer expired.
 319
 320                         In case the adapter is switched off, setting this
 321                         value will fail.
 322
 323                         When changing the Powered property the new state of
 324                         this property will be updated via a PropertiesChanged
 325                         signal.
 326
 327                         For any new adapter this settings defaults to false.
 328
 329                 boolean Pairable [readwrite]
 330
 331                         Switch an adapter to pairable or non-pairable. This is
 332                         a global setting and should only be used by the
 333                         settings application.
 334
 335                         Note that this property only affects incoming pairing
 336                         requests.
 337
 338                         For any new adapter this settings defaults to true.
 339
 340                 uint32 PairableTimeout [readwrite]
 341
 342                         The pairable timeout in seconds. A value of zero
 343                         means that the timeout is disabled and it will stay in
 344                         pairable mode forever.
 345
 346                         The default value for pairable timeout should be
 347                         disabled (value 0).
 348
 349                 uint32 DiscoverableTimeout [readwrite]
 350
 351                         The discoverable timeout in seconds. A value of zero
 352                         means that the timeout is disabled and it will stay in
 353                         discoverable/limited mode forever.
 354
 355                         The default value for the discoverable timeout should
 356                         be 180 seconds (3 minutes).
 357
 358                 boolean Discovering [readonly]
 359
 360                         Indicates that a device discovery procedure is active.
 361
 362                 array{string} UUIDs [readonly]
 363
 364                         List of 128-bit UUIDs that represents the available
 365                         local services.
 366
 367                 string Modalias [readonly, optional]
 368
 369                         Local Device ID information in modalias format
 370                         used by the kernel and udev.
 371 #ifdef __TIZEN_PATCH__
 372                 boolean LEDiscovering [readonly]
 373
 374                         Indicates that a device LE discovery procedure is active.
 375
 376                 string Version [readonly]
 377
 378                          The Bluetooth version.
 379 #endif