summaryrefslogtreecommitdiffstats
path: root/doc/device-api.txt
blob: fbe6bdfa62c4e3e7d650c361bdb99f8df7670cb6 (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
BlueZ D-Bus Device API description
**********************************

Copyright (C) 2004-2008  Marcel Holtmann <marcel@holtmann.org>
Copyright (C) 2005-2006  Johan Hedberg <johan.hedberg@nokia.com>
Copyright (C) 2005-2006  Claudio Takahasi <claudio.takahasi@indt.org.br>
Copyright (C) 2006-2007  Luiz von Dentz <luiz.dentz@indt.org.br>


Device hierarchy
================

Service		org.bluez
Interface	org.bluez.Device
Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX

Methods		dict GetProperties()

			Returns all properties for the adapter. See the
			properties section for available properties.

			Possible Errors: org.bluez.Error.DoesNotExist
					 org.bluez.Error.InvalidArguments

		void SetProperty(string name, variant value)

			Changes the value of the specified property. Only
			properties that are listed a read-write are changeable.
			On success this will emit a PropertyChanged signal.

			Possible Errors: org.bluez.Error.DoesNotExist
					 org.bluez.Error.InvalidArguments

		dict DiscoverServices(string pattern)

			This method starts the service discovery to retrieve
			remote service records. The pattern parameter can
			be used to specific specific UUIDs.

			The return value is a dictionary with the record
			handles as keys and the service record in XML format
			as values. The key is uint32 and the value a string
			for this dictionary.

			Possible errors: org.bluez.Error.NotReady
					 org.bluez.Error.Failed
					 org.bluez.Error.InProgress

		void CancelDiscovery()

			This method will cancel any previous DiscoverServices
			transaction.

			Possible errors: org.bluez.Error.NotReady
					 org.bluez.Error.Failed
					 org.bluez.Error.NotAuthorized

		void Disconnect()

			This method disconnects a specific remote device by
			terminating the low-level ACL connection. The use of
			this method should be restricted to administrator
			use.

			A DisconnectRequested signal will be sent and the
			actual disconnection will only happen 2 seconds later.
			This enables upper-level applications to terminate
			their connections gracefully before the ACL connection
			is terminated.

			Possible errors: org.bluez.Error.NotConnected

		array{object} ListNodes()

			Returns list of device node object paths.

			Possible errors: org.bluez.Error.InvalidArguments
					 org.bluez.Error.Failed
					 org.bluez.Error.OutOfMemory

		object CreateNode(string uuid)

			Creates a persistent device node binding with a
			remote device. The actual support for the specified
			UUID depends if the device driver has support for
			persistent binding. At the moment only RFCOMM TTY
			nodes are supported.

			Possible errors: org.bluez.Error.InvalidArguments
					 org.bluez.Error.NotSupported

		void RemoveNode(object node)

			Removes a persistent device node binding.

			Possible errors: org.bluez.Error.InvalidArguments
					 org.bluez.Error.DoesNotExist

Signals		PropertyChanged(string name, variant value)

			This signal indicates a changed value of the given
			property.

		DisconnectRequested()

			This signal will be sent when a low level
			disconnection to a remote device has been requested.
			The actual disconnection will happen 2 seconds later.

		NodeCreated(object node)

			Parameter is object path of created device node.

		NodeRemoved(object node)

			Parameter is object path of removed device node.

Properties	string Address [readonly]

			The Bluetooth device address of the remote device.

		string Name [readonly]

			The Bluetooth remote name. This value can not be
			changed. Use the Alias property instead.

		string Icon [readonly]

			Proposed icon name according to the freedesktop.org
			icon naming specification.

		uint32 Class [readonly]

			The Bluetooth class of device of the remote device.

		array{string} UUIDs [readonly]

			List of 128-bit UUIDs that represents the available
			remote services.

		boolean Paired [readonly]

			Indicates if the remote device is paired.

		boolean Connected [readonly]

			Indicates if the remote device is currently connected.
			A PropertyChanged signal indicate changes to this
			status.

		boolean Trusted [readwrite]

			Indicates if the remote is seen as trusted. This
			setting can be changed by the application.

		string Alias [readwrite]

			The name alias for the remote device. The alias can
			be used to have a different friendly name for the
			remote device.

			In case no alias is set, it will return the remote
			device name. Setting an empty string as alias will
			convert it back to the remote device name.

			When reseting the alias with an empty string, the
			emitted PropertyChanged signal will show the remote
			name again.

		array{object} Nodes [readonly]

			List of device node object paths.

		object Adapter [readonly]

			The object path of the adpater the device belongs to.

		boolean LegacyPairing [readonly]

			Set to true if the device only supports the pre-2.1
			pairing mechanism. This property is useful in the
			Adapter.DeviceFound signal to anticipate whether
			legacy or secure simple pairing will occur.

			Note that this property can exhibit false-positives
			in the case of Bluetooth 2.1 (or newer) devices that
			have disabled Extend Inquiry Response support.