doc/device-api.txt

   1 BlueZ D-Bus Device 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 Copyright (C) 2005-2006  Claudio Takahasi <claudio.takahasi@indt.org.br>
   7 Copyright (C) 2006-2007  Luiz von Dentz <luiz.dentz@indt.org.br>
   8
   9
  10 Device hierarchy
  11 ================
  12
  13 Service         org.bluez
  14 Interface       org.bluez.Device
  15 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
  16
  17 Methods         dict GetProperties()
  18
  19                         Returns all properties for the device. See the
  20                         properties section for available properties.
  21
  22                         Possible Errors: org.bluez.Error.DoesNotExist
  23                                          org.bluez.Error.InvalidArguments
  24
  25                 void SetProperty(string name, variant value)
  26
  27                         Changes the value of the specified property. Only
  28                         properties that are listed a read-write are changeable.
  29                         On success this will emit a PropertyChanged signal.
  30
  31                         Possible Errors: org.bluez.Error.DoesNotExist
  32                                          org.bluez.Error.InvalidArguments
  33
  34                 dict DiscoverServices(string pattern)
  35
  36                         This method starts the service discovery to retrieve
  37                         remote service records. The pattern parameter can
  38                         be used to specify specific UUIDs. And empty string
  39                         will look for the public browse group.
  40
  41                         The return value is a dictionary with the record
  42                         handles as keys and the service record in XML format
  43                         as values. The key is uint32 and the value a string
  44                         for this dictionary.
  45
  46                         Possible errors: org.bluez.Error.NotReady
  47                                          org.bluez.Error.Failed
  48                                          org.bluez.Error.InProgress
  49
  50                 void CancelDiscovery()
  51
  52                         This method will cancel any previous DiscoverServices
  53                         transaction.
  54
  55                         Possible errors: org.bluez.Error.NotReady
  56                                          org.bluez.Error.Failed
  57                                          org.bluez.Error.NotAuthorized
  58
  59                 void Disconnect()
  60
  61                         This method disconnects a specific remote device by
  62                         terminating the low-level ACL connection. The use of
  63                         this method should be restricted to administrator
  64                         use.
  65
  66                         A DisconnectRequested signal will be sent and the
  67                         actual disconnection will only happen 2 seconds later.
  68                         This enables upper-level applications to terminate
  69                         their connections gracefully before the ACL connection
  70                         is terminated.
  71
  72                         Possible errors: org.bluez.Error.NotConnected
  73
  74                 array{object} ListNodes()
  75
  76                         Returns list of device node object paths.
  77
  78                         Possible errors: org.bluez.Error.InvalidArguments
  79                                          org.bluez.Error.Failed
  80                                          org.bluez.Error.OutOfMemory
  81
  82                 object CreateNode(string uuid)
  83
  84                         Creates a persistent device node binding with a
  85                         remote device. The actual support for the specified
  86                         UUID depends if the device driver has support for
  87                         persistent binding. At the moment only RFCOMM TTY
  88                         nodes are supported.
  89
  90                         Possible errors: org.bluez.Error.InvalidArguments
  91                                          org.bluez.Error.NotSupported
  92
  93                 void RemoveNode(object node)
  94
  95                         Removes a persistent device node binding.
  96
  97                         Possible errors: org.bluez.Error.InvalidArguments
  98                                          org.bluez.Error.DoesNotExist
  99
 100 Signals         PropertyChanged(string name, variant value)
 101
 102                         This signal indicates a changed value of the given
 103                         property.
 104
 105                 DisconnectRequested()
 106
 107                         This signal will be sent when a low level
 108                         disconnection to a remote device has been requested.
 109                         The actual disconnection will happen 2 seconds later.
 110
 111                 NodeCreated(object node)
 112
 113                         Parameter is object path of created device node.
 114
 115                 NodeRemoved(object node)
 116
 117                         Parameter is object path of removed device node.
 118
 119 Properties      string Address [readonly]
 120
 121                         The Bluetooth device address of the remote device.
 122
 123                 string Name [readonly]
 124
 125                         The Bluetooth remote name. This value can not be
 126                         changed. Use the Alias property instead.
 127
 128                 uint16 Vendor [readonly]
 129
 130                         Vendor unique numeric identifier.
 131
 132                 uint16 Product [readonly]
 133
 134                         Product unique numeric identifier.
 135
 136                 uint16 Version [readonly]
 137
 138                         Version unique numeric identifier.
 139
 140                 string Icon [readonly]
 141
 142                         Proposed icon name according to the freedesktop.org
 143                         icon naming specification.
 144
 145                 uint32 Class [readonly]
 146
 147                         The Bluetooth class of device of the remote device.
 148
 149                 array{string} UUIDs [readonly]
 150
 151                         List of 128-bit UUIDs that represents the available
 152                         remote services.
 153
 154                 array{object} Services [readonly]
 155
 156                         List of characteristics based services.
 157
 158                 boolean Paired [readonly]
 159
 160                         Indicates if the remote device is paired.
 161
 162                 boolean Connected [readonly]
 163
 164                         Indicates if the remote device is currently connected.
 165                         A PropertyChanged signal indicate changes to this
 166                         status.
 167
 168                 boolean Trusted [readwrite]
 169
 170                         Indicates if the remote is seen as trusted. This
 171                         setting can be changed by the application.
 172
 173                 boolean Blocked [readwrite]
 174
 175                         If set to true any incoming connections from the
 176                         device will be immediately rejected. Any device
 177                         drivers will also be removed and no new ones will
 178                         be probed as long as the device is blocked.
 179
 180                 string Alias [readwrite]
 181
 182                         The name alias for the remote device. The alias can
 183                         be used to have a different friendly name for the
 184                         remote device.
 185
 186                         In case no alias is set, it will return the remote
 187                         device name. Setting an empty string as alias will
 188                         convert it back to the remote device name.
 189
 190                         When reseting the alias with an empty string, the
 191                         emitted PropertyChanged signal will show the remote
 192                         name again.
 193
 194                 array{object} Nodes [readonly]
 195
 196                         List of device node object paths.
 197
 198                 object Adapter [readonly]
 199
 200                         The object path of the adapter the device belongs to.
 201
 202                 boolean LegacyPairing [readonly]
 203
 204                         Set to true if the device only supports the pre-2.1
 205                         pairing mechanism. This property is useful in the
 206                         Adapter.DeviceFound signal to anticipate whether
 207                         legacy or simple pairing will occur.
 208
 209                         Note that this property can exhibit false-positives
 210                         in the case of Bluetooth 2.1 (or newer) devices that
 211                         have disabled Extended Inquiry Response support.