summaryrefslogtreecommitdiffstats
path: root/audio/audio-api.txt
blob: cba20699074ebac36116f5874b4f02ee6fa49c0e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
Bluetooth audio service API description
***************************************

Copyright (C) 2004-2007  Marcel Holtmann <marcel@holtmann.org>
Copyright (C) 2005-2007  Johan Hedberg <johan.hedberg@nokia.com>
Copyright (C) 2005-2006  Brad Midgley <bmidgley@xmission.com>


org.bluez.audio.Manager interface
=================================

This interface is for managing remote audio devices. It provides methods for
creating and removing D-Bus objects representing remote audio devices. These
objects implement one or more of the other interfaces listed in this document.

Object path	/org/bluez/audio

Methods
		string CreateDevice(string address) [experimental]

			Creates a new audio device object. If not yet done,
			this method will perform a SDP query on the remote
			device and return first when the query is complete,
			so be sure to call this method asynchronously.

			The return parameter is the object path of the newly
			created object.

		void RemoveDevice(string path) [experimental]

			Removes a device from the device tree. If there are
			any connections open to the device they will be closed.

		array{string} ListDevices() [experimental]

			Retuns an array of strings indicating the object paths
			of available devices.

		string DefaultDevice()

			Returns the object path for the default device.

		void ChangeDefaultDevice(string path)

			Changes the default device.

		array{string} ListHeadsets()

			Returns list of headset objects that are configured.

		string FindDeviceByAddress(string address) [experimental]

			Searches the list of available devices and returns the
			object path of the first device which matchess address.
			If no device is found returns a DoesNotExist error.

		string DefaultHeadset()

			Returns the object path for the default headset device.

		void ChangeDefaultHeadset(string path)

			Changes the default headset.

		string CreateHeadset(string address)

			Create a new headset device and returns its object path
			on return.

		void RemoveHeadset(string path)

			Removes a headset object and all information
			related to it.

Signals
		void DeviceCreated(string path) [experimental]

			Sent when a new device object has been created.

		void DeviceRemoved(string path) [experimental]

			Sent when a device object has been removed.

		void HeadsetCreated(string path)

			Sent when a new headset object has been created.

		void HeadsetRemoved(string path)

			Sent when a headset object has been removed.

		void DefaultHeadsetChanged(string path)

			Sent when the default headset has changed.


org.bluez.audio.Device interface
================================

This interface is implemented by all remote device objects.

Object path(s)	/org/bluez/audio/device*

Methods		string GetAddress() [experimental]

			Returns the Bluetooth address of the remote device.

		string GetAdapter() [experimental]

			Returns the address of the local adapter that the
			device is associated with.

		string GetName() [experimental]

			Returns a friendly name for the device.

		array{string} GetConnectedInterfaces() [experimental]

			Returns a string list of interfaces that are in a
			connected state.


org.bluez.audio.Headset interface
=================================

This interface provides access to headsets that implement the HSP and/or HFP
profiles.

Object path(s)	/org/bluez/audio/device*

Methods		void Connect()

			Connect to the HSP/HFP service on the remote device.

		void Disconnect()

			Disconnect from the HSP/HFP service on the remote
			device.

		boolean IsConnected()

			Returns TRUE if there is a active connection to the
			HSP/HFP connection on the remote device.

		void IndicateCall()

			Indicate an incoming call on the headset
			connected to the stream. Will continue to
			ring the headset about every 3 seconds.

		void CancelCall()

			Cancel the incoming call indication.

		void Play()

			Open the audio connection to the headset.

		void Stop()

			Close the audio connection.

		boolean IsPlaying()

			Returns true if an audio connection to the headset
			is active.

		uint16 GetSpeakerGain()

			Returns the current speaker gain if available,
			otherwise returns the error NotAvailable.

		uint16 GetMicrophoneGain()

			Returns the current microphone gain if available,
			otherwise returns the error NotAvailable.

		void SetSpeakerGain(uint16 gain)

			Changes the current speaker gain if possible.

		void SetMicrophoneGain(uint16 gain)

			Changes the current speaker gain if possible.

                void SetupCall(string value) [experimental]

			Sets up an call with the connected HFP. The value can
			be "incoming", "outgoing" or "remote" to indicate
			incoming call, outgoing call and remote party alerted
			respectively.

                void IdentifyCall(string phone_number, int32 type) [experimental]

                        Enables a called subscriber to get the calling
                        line identity (CLI) of the calling party when
                        receiving a call. The value of type shud be
                        the same as provided by the GSM stack.

Signals		void AnswerRequested()

			Sent when the answer button is pressed on the headset

		void Connected()

			Sent when the device has been connected to.

		void Disconnected()

			Sent when the device has been disconnected from.

		void Stopped()

			Sent when the audio connection is closed

		void Playing()

			Sent when the audio connection is opened

		void SpeakerGainChanged(uint16 gain)

			The speaker gain changed.

		void MicrophoneGainChanged(uint16 gain)

			The microphone gain changed.

                void CallTerminated()

                        Sent when an ongoing call is terminated.


org.bluez.audio.Gateway interface
=================================

[not yet implemented]

This interface is available for remote devices which can function in the Audio
Gateway role of the HSP and/or HFP profiles.

Object path(s)	/org/bluez/audio/device*


org.bluez.audio.Sink interface
==============================

This interface is available for remote devices which contain a A2DP Sink.

Object path(s)	/org/bluez/audio/device*

Methods		void Connect()

			Connect and setup a stream to a A2DP sink on the
			remote device.

		void Disconnect()

			Disconnect from the remote device.

		boolean IsConnected()

			Returns TRUE if a stream is setup to a A2DP sink on
			the remote device.

Signals		void Connected()

			Sent when a successful connection has been made to the
			remote A2DP Sink

		void Disconnected()

			Sent when the device has been disconnected from.

		void Playing()

			Sent when a stream with remote device is started.

		void Stopped()

			Sent when a stream with remote device is suspended.


org.bluez.audio.Source interface
================================

[not yet implemented]

This interface is available for remote devices which implement a A2DP source.

Object path(s)	/org/bluez/audio/device*


org.bluez.audio.Control interface
=================================

This interface is available for remote devices which implement support for a
AVRCP controller.

Object path(s)	/org/bluez/audio/device*

Methods		boolean IsConnected()

			Returns TRUE if AVRCP is connected.

Signals		void Connected()

			Sent when a successful AVRCP connection has been made.

		void Disconnected()

			Sent when the AVRCP connection has been disconnected.