doc/audio-api.txt

   1 BlueZ D-Bus Audio API description
   2 *********************************
   3
   4 Copyright (C) 2004-2010  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 Audio hierarchy
   9 ===============
  10
  11 Service         org.bluez
  12 Interface       org.bluez.Audio
  13 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
  14
  15 This is a generic audio interface that abstracts the different audio profiles.
  16
  17 Methods         void Connect()
  18
  19                         Connect all supported audio profiles on the device.
  20
  21                 void Disconnect()
  22
  23                         Disconnect all audio profiles on the device
  24
  25                 dict GetProperties()
  26
  27                         Returns all properties for the interface. See the
  28                         properties section for available properties.
  29
  30 Signals         void PropertyChanged(string name, variant value)
  31
  32                         This signal indicates a changed value of the given
  33                         property.
  34
  35 Properties      string State
  36
  37                         Possible values: "disconnected", "connecting",
  38                         "connected"
  39
  40                         "disconnected" -> "connecting"
  41                                 Either an incoming or outgoing connection
  42                                 attempt ongoing.
  43
  44                         "connecting" -> "disconnected"
  45                                 Connection attempt failed
  46
  47                         "connecting" -> "connected"
  48                                 Successfully connected
  49
  50                         "connected" -> "disconnected"
  51                                 Disconnected from the remote device
  52
  53 Headset hierarchy
  54 =================
  55
  56 Service         org.bluez
  57 Interface       org.bluez.Headset
  58 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
  59
  60 Methods         void Connect()
  61
  62                         Connect to the HSP/HFP service on the remote device.
  63
  64                 void Disconnect()
  65
  66                         Disconnect from the HSP/HFP service on the remote
  67                         device.
  68
  69                 boolean IsConnected() {deprecated}
  70
  71                         Returns TRUE if there is a active connection to the
  72                         HSP/HFP connection on the remote device.
  73
  74                 void IndicateCall()
  75
  76                         Indicate an incoming call on the headset
  77                         connected to the stream. Will continue to
  78                         ring the headset about every 3 seconds.
  79
  80                 void CancelCall()
  81
  82                         Cancel the incoming call indication.
  83
  84                 void Play() {deprecated}
  85
  86                         Open the audio connection to the headset.
  87
  88                 void Stop()
  89
  90                         Close the audio connection.
  91
  92                 boolean IsPlaying() {deprecated}
  93
  94                         Returns true if an audio connection to the headset
  95                         is active.
  96
  97                 uint16 GetSpeakerGain() {deprecated}
  98
  99                         Returns the current speaker gain if available,
 100                         otherwise returns the error NotAvailable.
 101
 102                 uint16 GetMicrophoneGain() {deprecated}
 103
 104                         Returns the current microphone gain if available,
 105                         otherwise returns the error NotAvailable.
 106
 107                 void SetSpeakerGain(uint16 gain) {deprecated}
 108
 109                         Changes the current speaker gain if possible.
 110
 111                 void SetMicrophoneGain(uint16 gain) {deprecated}
 112
 113                         Changes the current speaker gain if possible.
 114
 115                 dict GetProperties()
 116
 117                         Returns all properties for the interface. See the
 118                         properties section for available properties.
 119
 120                         Possible Errors: org.bluez.Error.InvalidArguments
 121
 122                 void SetProperty(string name, variant value)
 123
 124                         Changes the value of the specified property. Only
 125                         properties that are listed a read-write are changeable.
 126                         On success this will emit a PropertyChanged signal.
 127
 128                         Possible Errors: org.bluez.Error.DoesNotExist
 129                                          org.bluez.Error.InvalidArguments
 130 __TIZEN_PATCH__
 131                 void SetVoiceDial(boolean)
 132
 133                         Sends enable/disable Voice Recognition to headset.
 134 __TIZEN_PATCH__
 135
 136 Signals         void AnswerRequested()
 137
 138                         Sent when the answer button is pressed on the headset
 139
 140                 void Connected() {deprecated}
 141
 142                         Sent when the device has been connected to.
 143
 144                 void Disconnected() {deprecated}
 145
 146                         Sent when the device has been disconnected from.
 147
 148                 void Stopped() {deprecated}
 149
 150                         Sent when the audio connection is closed
 151
 152                 void Playing() {deprecated}
 153
 154                         Sent when the audio connection is opened
 155
 156                 void SpeakerGainChanged(uint16 gain) {deprecated}
 157
 158                         The speaker gain changed.
 159
 160                 void MicrophoneGainChanged(uint16 gain) {deprecated}
 161
 162                         The microphone gain changed.
 163
 164                 PropertyChanged(string name, variant value)
 165
 166                         This signal indicates a changed value of the given
 167                         property.
 168
 169 properties      string State [readonly]
 170
 171                         Possible values: "disconnected", "connecting",
 172                         "connected", "playing"
 173
 174                         "disconnected" -> "connecting"
 175                                 Either an incoming or outgoing connection
 176                                 attempt ongoing.
 177
 178                         "connecting" -> "disconnected"
 179                                 Connection attempt failed
 180
 181                         "connecting" -> "connected"
 182                                 Successfully connected
 183
 184                         "connected" -> "playing"
 185                                 SCO audio connection successfully opened
 186
 187                         "playing" -> "connected"
 188                                 SCO audio connection closed
 189
 190                         "connected" -> "disconnected"
 191                         "playing" -> "disconnected"
 192                                 Disconnected from the remote device
 193
 194                 boolean Connected [readonly]
 195
 196                         Indicates if there is a active connection to the
 197                         HSP/HFP connection on the remote device.
 198
 199                 boolean Playing  [readonly]
 200
 201                         Indicates if an audio connection to the headset
 202                         is active.
 203
 204                 uint16 SpeakerGain  [readwrite]
 205
 206                         The speaker gain when available.
 207
 208                 uint16 MicrophoneGain  [readwrite]
 209
 210                         The speaker gain when available.
 211
 212
 213 AudioSink hierarchy
 214 ===================
 215
 216 Service         org.bluez
 217 Interface       org.bluez.AudioSink
 218 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
 219
 220 Methods         void Connect()
 221
 222                         Connect and setup a stream to a A2DP sink on the
 223                         remote device.
 224
 225                 void Disconnect()
 226
 227                         Disconnect from the remote device.
 228
 229                 boolean IsConnected() {deprecated}
 230
 231                         Returns TRUE if a stream is setup to a A2DP sink on
 232                         the remote device.
 233
 234                 dict GetProperties()
 235
 236                         Returns all properties for the interface. See the
 237                         properties section for available properties.
 238
 239                         Possible Errors: org.bluez.Error.InvalidArguments
 240
 241 Signals         void Connected() {deprecated}
 242
 243                         Sent when a successful connection has been made to the
 244                         remote A2DP Sink
 245
 246                 void Disconnected() {deprecated}
 247
 248                         Sent when the device has been disconnected from.
 249
 250                 void Playing() {deprecated}
 251
 252                         Sent when a stream with remote device is started.
 253
 254                 void Stopped() {deprecated}
 255
 256                         Sent when a stream with remote device is suspended.
 257
 258                 PropertyChanged(string name, variant value)
 259
 260                         This signal indicates a changed value of the given
 261                         property.
 262
 263 properties      string State [readonly]
 264
 265                         Possible values: "disconnected", "connecting",
 266                         "connected", "playing"
 267
 268                         "disconnected" -> "connecting"
 269                                 Either an incoming or outgoing connection
 270                                 attempt ongoing.
 271
 272                         "connecting" -> "disconnected"
 273                                 Connection attempt failed
 274
 275                         "connecting" -> "connected"
 276                                 Successfully connected
 277
 278                         "connected" -> "playing"
 279                                 Audio stream active
 280
 281                         "playing" -> "connected"
 282                                 Audio stream suspended
 283
 284                         "connected" -> "disconnected"
 285                         "playing" -> "disconnected"
 286                                 Disconnected from the remote device
 287
 288                 boolean Connected [readonly]
 289
 290                         Indicates if a stream is setup to a A2DP sink on
 291                         the remote device.
 292
 293                 boolean Playing  [readonly]
 294
 295                         Indicates if a stream is active to a A2DP sink on
 296                         the remote device.
 297
 298 AudioSource hierarchy
 299 =====================
 300
 301 Service         org.bluez
 302 Interface       org.bluez.AudioSource
 303 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
 304
 305 Methods         void Connect()
 306
 307                         Connect and setup a stream to a A2DP source on the
 308                         remote device.
 309
 310                 void Disconnect()
 311
 312                         Disconnect from the remote device.
 313
 314                 dict GetProperties()
 315
 316                         Returns all properties for the interface. See the
 317                         properties section for available properties.
 318
 319                         Possible Errors: org.bluez.Error.InvalidArguments
 320
 321 Signals         PropertyChanged(string name, variant value)
 322
 323                         This signal indicates a changed value of the given
 324                         property.
 325
 326 properties      string State [readonly]
 327
 328                         Possible values: "disconnected", "connecting",
 329                         "connected", "playing"
 330
 331                         "disconnected" -> "connecting"
 332                                 Either an incoming or outgoing connection
 333                                 attempt ongoing.
 334
 335                         "connecting" -> "disconnected"
 336                                 Connection attempt failed
 337
 338                         "connecting" -> "connected"
 339                                 Successfully connected
 340
 341                         "connected" -> "playing"
 342                                 Audio stream active
 343
 344                         "playing" -> "connected"
 345                                 Audio stream suspended
 346
 347                         "connected" -> "disconnected"
 348                         "playing" -> "disconnected"
 349                                 Disconnected from the remote device
 350
 351
 352 HeadsetGateway hierarchy
 353 ========================
 354
 355 Service         org.bluez
 356 Interface       org.bluez.HeadsetGateway
 357 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
 358
 359 This interface is available for remote devices which can function in the Audio
 360 Gateway role of the HFP profiles.
 361
 362 Methods         void Connect()
 363
 364                         Connect to the AG service on the remote device.
 365
 366                 void Disconnect()
 367
 368                         Disconnect from the AG service on the remote device
 369
 370                 void AnswerCall()
 371
 372                         It has to called only after Ring signal received.
 373
 374                 void TerminateCall()
 375
 376                         Terminate call which is running or reject an incoming
 377                         call. This has nothing with any 3-way situation incl.
 378                         RaH. Just plain old PDH.
 379
 380                 void Call(string number)
 381
 382                         Dial a number 'number'. No number processing is done
 383                         thus if AG would reject to dial it don't blame me :)
 384
 385                 string GetOperatorName()
 386
 387                         Find out the name of the currently selected network
 388                         operator by AG.
 389
 390                 void SendDTMF(string digits)
 391
 392                         Will send each digit in the 'digits' sequentially. Would
 393                         send nothing if there is non-dtmf digit.
 394
 395                 string GetSubscriberNumber()
 396
 397                         Get the voicecall subscriber number of AG
 398
 399                 dict GetProperties()
 400
 401                         Returns all properties for the interface. See the
 402                         properties section for available properties.
 403
 404 Signals         void Ring(string number)
 405
 406                         Someone's calling from 'number'.
 407                         Caller number is provided as received from AG.
 408
 409                 void CallTerminated()
 410
 411                         Call failed to set up. It means that we tried to call
 412                         someone or someone tried to call us but call was not
 413                         accepted.
 414
 415                 void CallStarted()
 416
 417                         Call set up successfully.
 418
 419                 void CallEnded()
 420
 421                         Call was started and now ended. In contrast with
 422                         CallTerminated where call didn't started
 423
 424                 PropertyChanged(string name, variant value)
 425
 426                         This signal indicates a changed value of the given
 427                         property.
 428
 429 properties      boolean Connected [readonly]
 430
 431                         Indicates if there is an active connection to the
 432                         AG service on the remote device.
 433
 434                 uint16 RegistrationStatus [readonly]
 435
 436                         Service availability indicator of AG, where:
 437                         0 implies no service. No Home/Roam network available.
 438                         1 implies presence of service. Home/Roam network
 439                         available.
 440
 441                 uint16 SignalStrength [readonly]
 442
 443                         Signal strength indicator of AG, the value ranges from
 444                         0 to 5.
 445
 446                 uint16 RoamingStatus [readonly]
 447
 448                         Roaming status indicator of AG, where:
 449                         0 means roaming is not active
 450                         1 means a roaming is active
 451
 452                 uint16 BatteryCharge [readonly]
 453
 454                         Battery Charge indicator of AG, the value ranges from
 455                         0 to 5.
 456
 457                 uint16 SpeakerGain  [readonly]
 458
 459                         The speaker gain when available.
 460
 461                 uint16 MicrophoneGain  [readonly]
 462
 463                         The speaker gain when available.