utils/audio/audio-api.txt

   1 Bluetooth audio service API description
   2 ***************************************
   3
   4 Copyright (C) 2004-2007  Marcel Holtmann <marcel@holtmann.org>
   5 Copyright (C) 2005-2007  Johan Hedberg <johan.hedberg@nokia.com>
   6 Copyright (C) 2005-2006  Brad Midgley <bmidgley@xmission.com>
   7
   8
   9 org.bluez.audio.Manager interface
  10 =================================
  11
  12 This interface is for managing remote audio devices. It provides methods for
  13 creating and removing D-Bus objects representing remote audio devices. These
  14 objects implement one or more of the other interfaces listed in this document.
  15
  16 Object path     /org/bluez/audio
  17
  18 Methods
  19                 string CreateDevice(string address) [experimental]
  20
  21                         Creates a new audio device object. If not yet done,
  22                         this method will perform a SDP query on the remote
  23                         device and return first when the query is complete,
  24                         so be sure to call this method asynchronously.
  25
  26                         The return parameter is the object path of the newly
  27                         created object.
  28
  29                 void RemoveDevice(string path) [experimental]
  30
  31                         Removes a device from the device tree. If there are
  32                         any connections open to the device they will be closed.
  33
  34                 array{string} ListDevices() [experimental]
  35
  36                         Retuns an array of strings indicating the object paths
  37                         of available devices.
  38
  39                 string DefaultDevice()
  40
  41                         Returns the object path for the default device.
  42
  43                 void ChangeDefaultDevice(string path)
  44
  45                         Changes the default device.
  46
  47                 array{string} ListHeadsets()
  48
  49                         Returns list of headset objects that are configured.
  50
  51                 string FindDeviceByAddress(string address) [experimental]
  52
  53                         Searches the list of available devices and returns the
  54                         object path of the first device which matchess address.
  55                         If no device is found returns a DoesNotExist error.
  56
  57                 string DefaultHeadset()
  58
  59                         Returns the object path for the default headset device.
  60
  61                 void ChangeDefaultHeadset(string path)
  62
  63                         Changes the default headset.
  64
  65                 string CreateHeadset(string address)
  66
  67                         Create a new headset device and returns its object path
  68                         on return.
  69
  70                 void RemoveHeadset(string path)
  71
  72                         Removes a headset object and all information
  73                         related to it.
  74
  75 Signals
  76                 void DeviceCreated(string path) [experimental]
  77
  78                         Sent when a new device object has been created.
  79
  80                 void DeviceRemoved(string path) [experimental]
  81
  82                         Sent when a device object has been removed.
  83
  84                 void HeadsetCreated(string path)
  85
  86                         Sent when a new headset object has been created.
  87
  88                 void HeadsetRemoved(string path)
  89
  90                         Sent when a headset object has been removed.
  91
  92                 void DefaultHeadsetChanged(string path)
  93
  94                         Sent when the default headset has changed.
  95
  96
  97 org.bluez.audio.Device interface
  98 ================================
  99
 100 This interface is implemented by all remote device objects.
 101
 102 Object path(s)  /org/bluez/audio/device*
 103
 104 Methods         string GetAddress() [experimental]
 105
 106                         Returns the Bluetooth address of the remote device.
 107
 108                 string GetAdapter() [experimental]
 109
 110                         Returns the address of the local adapter that the
 111                         device is associated with.
 112
 113                 string GetName() [experimental]
 114
 115                         Returns a friendly name for the device.
 116
 117                 array{string} GetConnectedInterfaces() [experimental]
 118
 119                         Returns a string list of interfaces that are in a
 120                         connected state.
 121
 122
 123 org.bluez.audio.Headset interface
 124 =================================
 125
 126 This interface provides access to headsets that implement the HSP and/or HFP
 127 profiles.
 128
 129 Object path(s)  /org/bluez/audio/device*
 130
 131 Methods         void Connect()
 132
 133                         Connect to the HSP/HFP service on the remote device.
 134
 135                 void Disconnect()
 136
 137                         Disconnect from the HSP/HFP service on the remote
 138                         device.
 139
 140                 boolean IsConnected()
 141
 142                         Returns TRUE if there is a active connection to the
 143                         HSP/HFP connection on the remote device.
 144
 145                 void IndicateCall()
 146
 147                         Indicate an incoming call on the headset
 148                         connected to the stream. Will continue to
 149                         ring the headset about every 3 seconds.
 150
 151                 void CancelCall()
 152
 153                         Cancel the incoming call indication.
 154
 155                 void Play()
 156
 157                         Open the audio connection to the headset.
 158
 159                 void Stop()
 160
 161                         Close the audio connection.
 162
 163                 boolean IsPlaying()
 164
 165                         Returns true if an audio connection to the headset
 166                         is active.
 167
 168                 uint16 GetSpeakerGain()
 169
 170                         Returns the current speaker gain if available,
 171                         otherwise returns the error NotAvailable.
 172
 173                 uint16 GetMicrophoneGain()
 174
 175                         Returns the current microphone gain if available,
 176                         otherwise returns the error NotAvailable.
 177
 178                 void SetSpeakerGain(uint16 gain)
 179
 180                         Changes the current speaker gain if possible.
 181
 182                 void SetMicrophoneGain(uint16 gain)
 183
 184                         Changes the current speaker gain if possible.
 185
 186                 void SetupCall(string value) [experimental]
 187
 188                         Sets up an call with the connected HFP. The value can
 189                         be "incoming", "outgoing" or "remote" to indicate
 190                         incoming call, outgoing call and remote party alerted
 191                         respectively.
 192
 193                 void IdentifyCall(string phone_number, int32 type) [experimental]
 194
 195                         Enables a called subscriber to get the calling
 196                         line identity (CLI) of the calling party when
 197                         receiving a call. The value of type shud be
 198                         the same as provided by the GSM stack.
 199
 200 Signals         void AnswerRequested()
 201
 202                         Sent when the answer button is pressed on the headset
 203
 204                 void Connected()
 205
 206                         Sent when the device has been connected to.
 207
 208                 void Disconnected()
 209
 210                         Sent when the device has been disconnected from.
 211
 212                 void Stopped()
 213
 214                         Sent when the audio connection is closed
 215
 216                 void Playing()
 217
 218                         Sent when the audio connection is opened
 219
 220                 void SpeakerGainChanged(uint16 gain)
 221
 222                         The speaker gain changed.
 223
 224                 void MicrophoneGainChanged(uint16 gain)
 225
 226                         The microphone gain changed.
 227
 228                 void CallTerminated()
 229
 230                         Sent when an ongoing call is terminated.
 231
 232
 233 org.bluez.audio.Gateway interface
 234 =================================
 235
 236 [not yet implemented]
 237
 238 This interface is available for remote devices which can function in the Audio
 239 Gateway role of the HSP and/or HFP profiles.
 240
 241 Object path(s)  /org/bluez/audio/device*
 242
 243
 244 org.bluez.audio.Sink interface
 245 ==============================
 246
 247 This interface is available for remote devices which contain a A2DP Sink.
 248
 249 Object path(s)  /org/bluez/audio/device*
 250
 251 Methods         void Connect()
 252
 253                         Connect and setup a stream to a A2DP sink on the
 254                         remote device.
 255
 256                 void Disconnect()
 257
 258                         Disconnect from the remote device.
 259
 260                 boolean IsConnected()
 261
 262                         Returns TRUE if a stream is setup to a A2DP sink on
 263                         the remote device.
 264
 265 Signals         void Connected()
 266
 267                         Sent when a successful connection has been made to the
 268                         remote A2DP Sink
 269
 270                 void Disconnected()
 271
 272                         Sent when the device has been disconnected from.
 273
 274                 void Playing()
 275
 276                         Sent when a stream with remote device is started.
 277
 278                 void Stopped()
 279
 280                         Sent when a stream with remote device is suspended.
 281
 282
 283 org.bluez.audio.Source interface
 284 ================================
 285
 286 [not yet implemented]
 287
 288 This interface is available for remote devices which implement a A2DP source.
 289
 290 Object path(s)  /org/bluez/audio/device*
 291
 292
 293 org.bluez.audio.Control interface
 294 =================================
 295
 296 This interface is available for remote devices which implement support for a
 297 AVRCP controller.
 298
 299 Object path(s)  /org/bluez/audio/device*
 300
 301 Methods         boolean IsConnected()
 302
 303                         Returns TRUE if AVRCP is connected.
 304
 305                 void Connect()
 306
 307                         Connect to AVRCP on the remote device.
 308
 309                         NOTE: Most remote devices do not allow AVRCP without
 310                         A2DP, so this is intended for testing purposes.
 311
 312                 void Disconnect()
 313
 314                         Disconnect from the remote device.
 315
 316                         NOTE: Most remote devices do not allow AVRCP without
 317                         A2DP, so this is intended for testing purposes.
 318
 319 Signals         void Connected()
 320
 321                         Sent when a successful AVRCP connection has been made.
 322
 323                 void Disconnected()
 324
 325                         Sent when the AVRCP connection has been disconnected.