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)
  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
  58
  59                                 Filter by service UUIDs, empty means match
  60                                 _any_ UUID.
  61
  62                                 When a remote device is found that advertises
  63                                 any UUID from UUIDs, it will be reported if:
  64                                 - Pathloss and RSSI are both empty.
  65                                 - only Pathloss param is set, device advertise
  66                                   TX pwer, and computed pathloss is less than
  67                                   Pathloss param.
  68                                 - only RSSI param is set, and received RSSI is
  69                                   higher than RSSI param.
  70
  71                         int16 RSSI
  72
  73                                 RSSI threshold value.
  74
  75                                 PropertiesChanged signals will be emitted
  76                                 for already existing Device objects, with
  77                                 updated RSSI value. If one or more discovery
  78                                 filters have been set, the RSSI delta-threshold,
  79                                 that is imposed by StartDiscovery by default,
  80                                 will not be applied.
  81
  82                         uint16 Pathloss
  83
  84                                 Pathloss threshold value.
  85
  86                                 PropertiesChanged signals will be emitted
  87                                 for already existing Device objects, with
  88                                 updated Pathloss value.
  89
  90                         string Transport (Default "auto")
  91
  92                                 Transport parameter determines the type of
  93                                 scan.
  94
  95                                 Possible values:
  96                                         "auto"  - interleaved scan
  97                                         "bredr" - BR/EDR inquiry
  98                                         "le"    - LE scan only
  99
 100                                 If "le" or "bredr" Transport is requested,
 101                                 and the controller doesn't support it,
 102                                 org.bluez.Error.Failed error will be returned.
 103                                 If "auto" transport is requested, scan will use
 104                                 LE, BREDR, or both, depending on what's
 105                                 currently enabled on the controller.
 106
 107                         bool DuplicateData (Default: true)
 108
 109                                 Disables duplicate detection of advertisement
 110                                 data.
 111
 112                                 When enabled PropertiesChanged signals will be
 113                                 generated for either ManufacturerData and
 114                                 ServiceData everytime they are discovered.
 115
 116                         When discovery filter is set, Device objects will be
 117                         created as new devices with matching criteria are
 118                         discovered regardless of they are connectable or
 119                         discoverable which enables listening to
 120                         non-connectable and non-discoverable devices.
 121
 122                         When multiple clients call SetDiscoveryFilter, their
 123                         filters are internally merged, and notifications about
 124                         new devices are sent to all clients. Therefore, each
 125                         client must check that device updates actually match
 126                         its filter.
 127
 128                         When SetDiscoveryFilter is called multiple times by the
 129                         same client, last filter passed will be active for
 130                         given client.
 131
 132                         SetDiscoveryFilter can be called before StartDiscovery.
 133                         It is useful when client will create first discovery
 134                         session, to ensure that proper scan will be started
 135                         right after call to StartDiscovery.
 136
 137                         Possible errors: org.bluez.Error.NotReady
 138                                          org.bluez.Error.NotSupported
 139                                          org.bluez.Error.Failed
 140
 141                 array{string} GetDiscoveryFilters()
 142
 143                         Return available filters that can be given to
 144                         SetDiscoveryFilter.
 145
 146                         Possible errors: None
 147
 148                 object ConnectDevice(dict properties) [experimental]
 149
 150                         This method connects to device without need of
 151                         performing General Discovery. Connection mechanism is
 152                         similar to Connect method from Device1 interface with
 153                         exception that this method returns success when physical
 154                         connection is established. After this method returns,
 155                         services discovery will continue and any supported
 156                         profile will be connected. There is no need for calling
 157                         Connect on Device1 after this call. If connection was
 158                         successful this method returns object path to created
 159                         device object.
 160
 161                         Parameters that may be set in the filter dictionary
 162                         include the following:
 163
 164                         string Address
 165
 166                                 The Bluetooth device address of the remote
 167                                 device. This parameter is mandatory.
 168
 169                         string AddressType
 170
 171                                 The Bluetooth device Address Type. This is
 172                                 address type that should be used for initial
 173                                 connection. If this parameter is not present
 174                                 BR/EDR device is created.
 175
 176                                 Possible values:
 177                                         "public" - Public address
 178                                         "random" - Random address
 179
 180                         Possible errors: org.bluez.Error.InvalidArguments
 181                                          org.bluez.Error.AlreadyExists
 182                                          org.bluez.Error.NotSupported
 183                                          org.bluez.Error.NotReady
 184                                          org.bluez.Error.Failed
 185
 186 #ifdef TIZEN_FEATURE_BLUEZ_MODIFY
 187                 void StartCustomDiscovery(string pattern)
 188
 189                         This method starts the device discovery session with
 190                         parameter. The valid paramter strings are "BREDR",
 191                         "LE" or "LE_BREDR" which will perform the inquiry for
 192                         appropriate types. This includes an inquiry procedure
 193                         and remote device name resolving. Use StopDiscovery
 194                         to release the sessions acquired.
 195
 196                         This process will start creating Device objects as
 197                         new devices are discovered.
 198
 199                         Possible errors: org.bluez.Error.NotReady
 200                                          org.bluez.Error.Failed
 201
 202                 void StartLEDiscovery()
 203
 204                         This method starts the LE device discovery session.
 205                         General discovery and active scan is default.
 206                         Use StopLEDiscovery to release the sessions
 207                         acquired.
 208
 209                         This process will start emitting DeviceFound and
 210                         PropertyChanged "LEDiscovering" signals.
 211
 212                         Possible errors: org.bluez.Error.NotReady
 213                                          org.bluez.Error.Failed
 214
 215                 void StopLEDiscovery()
 216
 217                         This method will cancel any previous StartLEDiscovery
 218                         transaction.
 219
 220                         Note that a discovery procedure is shared between all
 221                         discovery sessions thus calling StopLEDiscovery will only
 222                         release a single session.
 223
 224                         Possible errors: org.bluez.Error.NotReady
 225                                          org.bluez.Error.Failed
 226                                          org.bluez.Error.NotAuthorized
 227
 228                 void SetAdvertising(boolean enable)
 229
 230                         This method is used to set LE advertising on a
 231                         controller that supports it.
 232
 233                         This process will emit PropertyChanged "Advertising"
 234                         signal.
 235
 236                         Possible errors: org.bluez.Error.NotReady
 237                                         org.bluez.Error.InvalidArguments
 238                                         org.bluez.Error.Failed
 239
 240                 void SetAdvertisingParameters(uint32 interval_min,
 241                                                 uint32 interval_max, uint32 filter_policy,
 242                                                 uint32 type, int32 tx_power_level, int32 slot_id)
 243
 244                         This method allows for setting the Low Energy
 245                         advertising interval and advertising filter policy.
 246                         It is only supported on controller with LE support.
 247
 248                         Possible errors: org.bluez.Error.NotReady
 249                                         org.bluez.Error.Failed
 250
 251                 void SetAdvertisingData(array{byte} value)
 252
 253                         This method is used to set LE advertising data on a
 254                         controller that supports it.
 255
 256                         Possible errors: org.bluez.Error.NotReady
 257                                         org.bluez.Error.InvalidArguments
 258                                         org.bluez.Error.Failed
 259
 260                 void SetScanParameters(uint32 type, uint32 interval, uint32 window)
 261
 262                         This method allows for setting the Low Energy
 263                         scan interval and window.
 264                         It is only supported on controller with LE support.
 265
 266                         Possible errors: org.bluez.Error.NotReady
 267                                         org.bluez.Error.Failed
 268
 269                 void SetScanRespData(array{byte} value)
 270
 271                         This method is used to set LE scan response data on
 272                         a controller that supports it.
 273
 274                         Possible errors: org.bluez.Error.NotReady
 275                                         org.bluez.Error.InvalidArguments
 276                                         org.bluez.Error.Failed
 277
 278                 void AddDeviceWhiteList(string address, uint32 address_type)
 279
 280                         This method is used to add LE device to White List for given
 281                         address.
 282
 283                         Possible errors: org.bluez.Error.NotReady
 284                                         org.bluez.Error.InvalidArguments
 285                                         org.bluez.Error.Failed
 286
 287                 void RemoveDeviceWhiteList(string address, uint32 address_type)
 288
 289                         This method is used to remove LE device to White List for given
 290                         address.
 291
 292                         Possible errors: org.bluez.Error.NotReady
 293                                         org.bluez.Error.InvalidArguments
 294                                         org.bluez.Error.Failed
 295
 296                 void ClearDeviceWhiteList()
 297
 298                         This method is used to clear LE device to White List
 299
 300                         Possible errors: org.bluez.Error.NotReady
 301                                         org.bluez.Error.Failed
 302
 303                 void SetLePrivacy(boolean enable_privacy)
 304
 305                         This method is used to set/reset LE privacy feature for the local
 306                         adapter when it supports the feature.
 307
 308                         Possible errors: org.bluez.Error.NotReady
 309                                         org.bluez.Error.InvalidArguments
 310                                         org.bluez.Error.Failed
 311
 312                 void SetLeStaticRandomAddress(boolean enable_random_address)
 313
 314                         This method is used to set/reset LE static random address for the local
 315                         adapter when it supports the feature.
 316
 317                         Possible errors: org.bluez.Error.NotReady
 318                                         org.bluez.Error.InvalidArguments
 319                                         org.bluez.Error.Failed
 320
 321                 void SetManufacturerData(array{byte} value)
 322
 323                         This method is used to set Manufacturer data on a
 324                         controller that supports it.
 325
 326                         Possible errors: org.bluez.Error.NotReady
 327                                         org.bluez.Error.InvalidArguments
 328                                         org.bluez.Error.Failed
 329
 330                 void CreateDevice(string address)
 331
 332                         Creates a new object path for a remote device. This
 333                         method will connect to the remote device and retrieve
 334                         all SDP records.
 335
 336                         Possible errors: org.bluez.Error.InvalidArguments
 337 #endif
 338
 339 Properties      string Address [readonly]
 340
 341                         The Bluetooth device address.
 342
 343                 string AddressType [readonly]
 344
 345                         The Bluetooth  Address Type. For dual-mode and BR/EDR
 346                         only adapter this defaults to "public". Single mode LE
 347                         adapters may have either value. With privacy enabled
 348                         this contains type of Identity Address and not type of
 349                         address used for connection.
 350
 351                         Possible values:
 352                                 "public" - Public address
 353                                 "random" - Random address
 354
 355                 string Name [readonly]
 356
 357                         The Bluetooth system name (pretty hostname).
 358
 359                         This property is either a static system default
 360                         or controlled by an external daemon providing
 361                         access to the pretty hostname configuration.
 362
 363                 string Alias [readwrite]
 364
 365                         The Bluetooth friendly name. This value can be
 366                         changed.
 367
 368                         In case no alias is set, it will return the system
 369                         provided name. Setting an empty string as alias will
 370                         convert it back to the system provided name.
 371
 372                         When resetting the alias with an empty string, the
 373                         property will default back to system name.
 374
 375                         On a well configured system, this property never
 376                         needs to be changed since it defaults to the system
 377                         name and provides the pretty hostname. Only if the
 378                         local name needs to be different from the pretty
 379                         hostname, this property should be used as last
 380                         resort.
 381
 382                 uint32 Class [readonly]
 383
 384                         The Bluetooth class of device.
 385
 386                         This property represents the value that is either
 387                         automatically configured by DMI/ACPI information
 388                         or provided as static configuration.
 389
 390                 boolean Powered [readwrite]
 391
 392                         Switch an adapter on or off. This will also set the
 393                         appropriate connectable state of the controller.
 394
 395                         The value of this property is not persistent. After
 396                         restart or unplugging of the adapter it will reset
 397                         back to false.
 398
 399                 boolean Discoverable [readwrite]
 400
 401                         Switch an adapter to discoverable or non-discoverable
 402                         to either make it visible or hide it. This is a global
 403                         setting and should only be used by the settings
 404                         application.
 405
 406                         If the DiscoverableTimeout is set to a non-zero
 407                         value then the system will set this value back to
 408                         false after the timer expired.
 409
 410                         In case the adapter is switched off, setting this
 411                         value will fail.
 412
 413                         When changing the Powered property the new state of
 414                         this property will be updated via a PropertiesChanged
 415                         signal.
 416
 417                         For any new adapter this settings defaults to false.
 418
 419                 boolean Pairable [readwrite]
 420
 421                         Switch an adapter to pairable or non-pairable. This is
 422                         a global setting and should only be used by the
 423                         settings application.
 424
 425                         Note that this property only affects incoming pairing
 426                         requests.
 427
 428                         For any new adapter this settings defaults to true.
 429
 430                 uint32 PairableTimeout [readwrite]
 431
 432                         The pairable timeout in seconds. A value of zero
 433                         means that the timeout is disabled and it will stay in
 434                         pairable mode forever.
 435
 436                         The default value for pairable timeout should be
 437                         disabled (value 0).
 438
 439                 uint32 DiscoverableTimeout [readwrite]
 440
 441                         The discoverable timeout in seconds. A value of zero
 442                         means that the timeout is disabled and it will stay in
 443                         discoverable/limited mode forever.
 444
 445                         The default value for the discoverable timeout should
 446                         be 180 seconds (3 minutes).
 447
 448                 boolean Discovering [readonly]
 449
 450                         Indicates that a device discovery procedure is active.
 451
 452                 array{string} UUIDs [readonly]
 453
 454                         List of 128-bit UUIDs that represents the available
 455                         local services.
 456
 457                 string Modalias [readonly, optional]
 458
 459                         Local Device ID information in modalias format
 460                         used by the kernel and udev.
 461 #ifdef TIZEN_FEATURE_BLUEZ_MODIFY
 462                 boolean LEDiscovering [readonly]
 463
 464                         Indicates that a device LE discovery procedure is active.
 465
 466                 string Version [readonly]
 467
 468                          The Bluetooth version.
 469 #endif