summaryrefslogtreecommitdiff
path: root/doc/handsfree-audio-api.txt
blob: 87d51cf5fb03f080148f8bb831caac6bfd6fc267 (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
Handsfree Audio Manager hierarchy [experimental]
=================================

Service		org.ofono
Interface	org.ofono.HandsfreeAudioManager
Object path	/

Methods		array{object,dict} GetCards()

			Get an array of card objects and properties
			that represent the currently attached devices.

			This method call should only be used once when an
			application starts up. Further device additions
			and removal shall be monitored via CardAdded and
			CardRemoved signals.

		void Register(object path, array{byte})

			Registers a Handsfree Audio agent with a specific
			path (freely selectable by the audio subsystem) and
			list of supported codecs.  Available codec
			identifiers:

				1	CVSD
				2	mSBC

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.InUse

		void Unregister(object path)

			Unregisters a Handsfree Audio agent registered
			through the Register method.

			Possible Errors: [service].Error.NotFound
					 [service].Error.InvalidArguments
					 [service].Error.NotAllowed

Signals		CardAdded(object path, dict properties)

			Signal that is sent when a new card is added.  It
			contains the object path of new card and its
			properties.

		CardRemoved(object path)

			Signal that is sent when a card has been removed.
			The object path is no longer accessible after this
			signal and only emitted for reference.


Handsfree Audio Card hierarchy [experimental]
==============================

Service		org.ofono
Interface	org.ofono.HandsfreeAudioCard
Object path	/{device0,device1,...}

Methods		dict GetProperties()

			Returns properties for the device object. See
			the properties section for available properties.

		void Connect()

			Attempts to establish the SCO audio connection.
			The Agent NewConnection() method will be called
			whenever the SCO audio link has been established.  If
			the audio connection could not be established, this
			method will return an error.

			Possible Errors: [service].Error.InProgress
					 [service].Error.Failed
					 [service].Error.NotAvailable
					 [service].Error.NotImplemented
					 [service].Error.NotAllowed

		fd, byte Acquire()

			Attempts to establish the SCO audio connection
			returning the filedescriptor of the connection and the
			codec in use.

			Note: Contrary to Connect this does not call
			NewConnection so it can be called in a blocking
			manner.

			Possible Errors: [service].Error.InProgress
					 [service].Error.Failed
					 [service].Error.NotAvailable
					 [service].Error.NotImplemented
					 [service].Error.NotAllowed

Signals		PropertyChanged(string name, variant value)

			This signal indicates a changed value of the given
			property.

Properties	string RemoteAddress [readonly]

			Bluetooth address of the remote peer.

		string LocalAddress [readonly]

			Bluetooth address of the local adapter.

		string Type [readonly]

			Type of the card. Valid values are "gateway" or
			"handsfree".

Handsfree Audio Agent hierarchy [experimental]
===============================

Service		<freely defined>
Interface	org.ofono.HandsfreeAudioAgent
Object		<freely defined>

Methods		void NewConnection(object card, fd sco, byte codec)

			Notifies the handler that a new SCO connection is
			available. Returning an error will cause oFono to
			disconnect the SCO connection.

		void Release()

			Notifies the Agent that it is no longer registered
			to oFono.