summaryrefslogtreecommitdiffstats
path: root/hcid/dbus-api.txt
blob: be6116ace03a24e78fd9a397370315023a1b4463 (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
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
D-Bus API description for BlueZ
*******************************

Copyright (C) 2004-2007  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) 2005-2006  Eduardo Rocha <eduardo.rocha@indt.org.br>


Constant definitions
====================

The class of device definition from the Bluetooth specification divides into
three different parts. It the major class, the minor class and the service
classes. The D-Bus interface will always use string constants to identify
any of these classes.

Service classes		positioning, networking, rendering, capturing,
			object transfer, audio, telephony, information

Major classes		miscellaneous, computer, phone, access point,
			audio/video, peripheral, imaging, wearable, toy,
			uncategorized

Minor classes computer	uncategorized, desktop, server, laptop, handheld,
			palm, wearable

Minor classes phone	uncategorized, cellular, cordless, smart phone,
			modem, isdn

Minor classes access point	fully, 1-17 percent, 17-33 percent,
			33-50 percent, 50-67 percent, 67-83 percent,
			83-99 percent, not available

Minor classes audio video	uncategorized, headset, handsfree,microphone,
			loudspeaker, headphones, portable audio, car audio,
			set-top box, hifi audio, vcr, video camera, camcorder,
			video monitor, video display and loudspeaker,
			video conferencing, gaming/toy, unknown

Minor classes peripheral	uncategorized, keyboard, pointing, combo

Minor classes imaging	display, camera, scanner, printer

Minor classes wearable	wrist watch, pager, jacket, helmet, glasses

Minor classes toy	robot, vehicle, doll, controller, game

Error hierarchy
===============

Interface	org.bluez.Error

Errors		Failed

			An unknown error occured. The error messages is
			taken from the strerror(errno) function.

		InvalidArguments

			Error returned when the argument list is invalid or
			out of specification for the method.

		NotAuthorized

			Error returned when the caller of a method is not
			authorized. This might happen if a caller tries to
			terminate a connection that it hasn't created.

		OutOfMemory

			Error returned when a memory allocation via malloc()
			fails. This error is similar to ENOMEM.

		NoSuchAdapter

			Error returned when the requested adapter doesn't
			exists. This error is similar to ENODEV.

		NotReady

			Error returned when the adapter is DOWN.

		NotAvailable

			Error returned when a specified record is not
			available.

		NotConnected

			Error returned when the remote device isn't connected
			at the moment.

		ConnectionAttemptFailed

		AlreadyExists

			Error returned if a record for a specific procedure
			already exists and it has been tried create a new
			one. The error message however should indicate the
			procedure that fails. For example "Bonding already
			exists"

		DoesNotExist

			Error returned if a record for a specifc procedure
			doesn't exist. The error message however should
			indicate the procedure that fails. For example
			"Bonding does not exist".

		InProgress

			Error returned if an operation is in progress. Since
			this is a generic error that can be used in various
			situations, the error message should be more clear
			about what is in progress. For example "Bonding in
			progress".

		NotSupported
			The feature is not supported by the remote device

		AuthenticationFailed

		AuthenticationTimeout

		AuthenticationRejected

		AuthenticationCanceled

		UnsupportedMajorClass


Manager hierarchy
=================

Service		org.bluez
Interface	org.bluez.Manager
Object path	/org/bluez

Methods		uint32 InterfaceVersion()

			Returns the current interface version. At the moment
			only version 0 is supported.

			Possible errors: org.bluez.Error.InvalidArguments

		string DefaultAdapter()

			Returns object path for the default adapter.

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

		string FindAdapter(string pattern)

			Returns object path for the specified adapter. Valid
			patterns are "hci0" or "00:11:22:33:44:55".

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

		array{string} ListAdapters()

			Returns list of adapter object paths under /org/bluez

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

		string FindService(string pattern)

			Returns object path for the specified service. Valid
			patterns are the unqiue identifier or a bus name.

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

		array{string} ListServices()

			Returns list of object paths of current services.

			Possible errors: org.bluez.Error.InvalidArguments

		string ActivateService(string pattern)

			Returns the unqiue bus id of the specified service.
			Valid patterns are the same as for FindService(). If
			the service is not running it will be started.

Signals		void AdapterAdded(string path)

			Parameter is object path of added adapter.

		void AdapterRemoved(string path)

			Parameter is object path of removed adapter.

		void DefaultAdapterChanged(string path)

			Parameter is object path of the new default adapter.

		void ServiceAdded(string path)

			Parameter is object path of registered service agent.

		void ServiceRemoved(string path)

			Parameter is object path of unregistered service agent.


Database hierarchy
==================

Service		org.bluez
Interface	org.bluez.Database
Object path	/org/bluez or /org/bluez/{hci0,hci1,...}

Methods		void RegisterService(string identifier, string name, string description)

			This method registers a new service specified by
			its unique identifier. This is only needed for
			services that are not started through the
			Bluetooth daemon.

		void UnregisterService(string identifier)

			This method unregisters a service specified by
			its unique identifier.

		uint32 AddServiceRecord(array{byte})

			Adds a new service record and returns the assigned
			record handle.

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

		uint32 AddServiceRecordFromXML(string record)

			Adds a new service record and returns the assigned
			record handle.

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

		void UpdateServiceRecord(uint32 handle, array{byte})

			Updates a given service record.

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

		void UpdateServiceRecordFromXML(uint32 handle, string record)

			Updates a given service record provided in the
			XML format.

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

		void RemoveServiceRecord(uint32 handle)

			Remove a service record identified by its handle.

			It is only possible to remove service records that
			where added by the current connection.

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

		void RequestAuthorization(string address, string uuid)

			This method gets called when a service wants to check
			if a remote device is authorized to perform some
			action. The authorization request is forwarded to an
			authorization agent.

			The address parameter is the Bluetooth address of the
			remote device and the uuid is the identifier of the
			profile requesting the authorization. This parameter
			can also be left blank.

		void CancelAuthorizationRequest(string address, string uuid)

			This method cancels an authorization process requested
			by a previous call to RequestAuthorization(). The
			address and uuid parameters must match.


Adapter hierarchy
=================

Service		org.bluez
Interface	org.bluez.Adapter
Object path	/org/bluez/{hci0,hci1,...}

Methods		dict GetInfo()

			Returns the properties of the local adapter.

		string GetAddress()

			Returns the device address for a given path.

			Example: "00:11:22:33:44:55"

			Possible errors: none

		string GetVersion()

			Returns the version of the Bluetooth chip. This version
			is compiled from the LMP version. In case of EDR the
			features attribute must be checked.

			Example: "Bluetooth 2.0 + EDR"

			Possible errors: none

		string GetRevision()

			Returns the revision of the Bluetooth chip. This is a
			vendor specific value and in most cases it represents
			the firmware version. This might derive from the HCI
			revision and LMP subversion values or via extra vendor
			specific commands.

			In case the revision of a chip is not available. This
			method should return the LMP subversion value as a
			string.

			Example: "HCI 19.2"

			Possible errors: org.bluez.Error.Failed

		string GetManufacturer()

			Returns the manufacturer of the Bluetooth chip. If
			the company id is not know the sting "Company ID %d"
			where %d should be replaced with the numeric value
			from the manufacturer field.

			Example: "Cambridge Silicon Radio"

			Possible errors: org.bluez.Error.Failed

		string GetCompany()

			Returns the company name from the OUI database of the
			Bluetooth device address. This function will need a
			valid and up-to-date oui.txt from the IEEE. This value
			will be different from the manufacturer string in the
			most cases.

			If the oui.txt file is not present or the OUI part of
			the BD_ADDR is not listed, it should return the
			string "OUI %s" where %s is the actual OUI.

			Example: "Apple Computer"

			Possible errors: org.bluez.Error.Failed

		array{string} ListAvailableModes()

			Returns a list of available modes the adapter can
			be switched into.

		string GetMode()

			Returns the current mode of a adapter.

			Valid modes: "off", "connectable", "discoverable",
					"limited".

			Possible errors: none

		void SetMode(string mode)

			Sets mode of the adapter. See GetMode for valid strings
			for the mode parameter.

			Possible errors: org.bluez.Error.NoSuchAdapter
					 org.bluez.Error.Failed

		uint32 GetDiscoverableTimeout()

			Returns the discoverable timeout in seconds. A value
			of zero means that the timeout is disabled and it will
			stay in discoverable/limited mode forever.

			The default value for the discoverable timeout should
			be 180 seconds (3 minutes).

			Possible errors: none

		void SetDiscoverableTimeout(uint32 timeout)

			Sets the discoverable timeout in seconds. A value of
			zero disables the timeout and the adapter would be
			always discoverable/limited.

			Changing this value doesn't set the adapter into
			discoverable/limited mode. The SetMode method must be used.

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

		boolean IsConnectable()

			Returns true if the local adapter is connectable and
			false if it is switched off.

			It is also possible to use GetMode to retrieve this
			information.

			Possible errors: none

		boolean IsDiscoverable()

			Returns true if the local adapter is discoverable/limited
			and false if it is only connectable or switched off.

			It is also possible to use GetMode to retrieve this
			information.

			Possible errors: none

		boolean IsConnected(string address)

			Return true if the local adapter is connected to
			the remote device.

			Possible errors: org.bluez.Error.InvalidArguments

		array{string} ListConnections()

			Returns a list with addresses of currently connected
			remote devices.

			Possible errors: none

		string GetMajorClass()

			Returns the current major class value for this
			system. Currently, only "computer" is supported.
			For the other values, unsupported major class
			error is returned.

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

		array{string} ListAvailableMinorClasses()

			Returns a list of available minor classes for the
			currently used major class. At the moment this should
			only return a list of minor classes if the major
			class is set to "computer".

			If the major class is not "computer" an error should
			be returned.

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

		string GetMinorClass()

			Returns the current minor class value for this
			system where the default major class is "computer".

			If the major class is not "computer" an error should
			be returned.

			Valid values: "uncategorized", "desktop", "server",
			              "laptop", "handheld", "palm", "wearable"

			The default value is "uncategorized".

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

		void SetMinorClass(string minor)

			Sets the local minor class and on success it sends
			a MinorClassChanged signal.

			If the major class is not "computer" an error should
			be returned.

			Possible errors: org.bluez.Error.NotReady
					 org.bluez.Error.InvalidArguments
					 org.bluez.Error.NoSuchAdapter
					 org.bluez.Error.Failed
					 org.bluez.Error.UnsupportedMajorClass

		array{string} GetServiceClasses()

			Returns the current set of service classes.

			In the case no service classes are set (when no
			service has been registered) an empty list should
			be returned.

			Valid values: "positioning", "networking", "rendering",
			              "capturing", "object transfer", "audio",
			              "telephony", "information"

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

		string GetName()

			Returns the local adapter name (friendly name) in UTF-8.

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

		void SetName(string name)

			Sets the local adapter name. If EIR is supported by
			the local hardware this modifies also the extended
			response data value.

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

			Questions: What to do (in case of EIR) if one
			           low-level API call fails.

		dict GetRemoteInfo(string address)

			Returns the properties for a remote device.

		string GetRemoteVersion(string address)

			Get the version info for a remote device. This request
			returns always this information based on its cached
			data. The base for this string is the LMP version
			value and the features for EDR support.

			Not available can be received if the remote device was
			not contacted(connected) previously. Remote data is
			automatically retrieved in the first connection.

			Example: "Bluetooth 2.0 + EDR"

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

		string GetRemoteRevision(string address)

			Get the revision of the Bluetooth chip. This is a
			vendor specific value and in most cases it represents
			the firmware version. This derives only from the LMP
			subversion value.

			Example: "HCI 19.2"

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

		string GetRemoteManufacturer(string address)

			Get the manufacturer of the chip for a remote device.

			Example: "Nokia Mobile Phones"

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

		string GetRemoteCompany(string address)

			Get the company name from the OUI database of the
			Bluetooth device address. This function will need a
			valid and up-to-date oui.txt from the IEEE. This value
			will be different from the manufacturer string in the
			most cases.

			Example: "Microsoft Corporation"

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

		string GetRemoteMajorClass(string address)

			Get the major device class of the specified device.

			Example: "computer"

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

		string GetRemoteMinorClass(string address)

			Get the minor device class of the specified device.

			Example: "laptop"

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

		array{string} GetRemoteServiceClasses(string address)

			Get the service classes of the specified device.

			Example: ["networking", "object transfer"]

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

		uint32 GetRemoteClass(string address)

			Get the remote major, minor, and service classes
			encoded as 32 bit integer.

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

		array{byte} GetRemoteFeatures(string address)

			Get the remote features encoded as bit mask.

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

		string GetRemoteName(string address)

			Get the remote device's name. This request returns always
			a cached name. The service daemon is responsible for
			updating the cache.

			NotAvailable error is returned if the name is not in
			the cache. But if there is a discovery running, then
			this function will return RequestDeferred.  In this
			case the service daemon will queue the request and
			it will try to resolve the name at the next possible
			opportunity. On success a RemoteNameUpdated signal will
			be send and if a failure happens it will be indicated by
			a RemoteNameFailed signal.

			If this is an empty string, the UI might want to
			display the BD_ADDR instead.

			Example: "00:11:22:33:44:55", "Nokia 770"

			Possible errors: org.bluez.Error.InvalidArguments
					 org.bluez.Error.NotAvailable
					 org.bluez.Error.NotReady
					 org.bluez.Error.RequestDeferred

		string GetRemoteAlias(string address)

			Returns alias name for remote device. If this is
			an empty string value, the UI should show the
			remote name instead.

			An alias should supersede the remote name.

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

		void SetRemoteAlias(string address, string alias)

			Sets alias name for remote device. If alias name is
			empty, then no alias is set.

			On success the SetRemoteAlias method will produce a
			RemoteAliasChanged signal which applications can use
			to update their current display of the remote device
			name.

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

		void ClearRemoteAlias(string address)

			Resets alias name for remote device. If there is no
			alias set for the device this method will silently
			succeed, but no RemoteAliasCleared signal has to be
			sent in this case.

			On success the ClearRemoteAlias method will produce
			a RemoteAliasCleared signal.

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

		string LastSeen(string address)

			Returns the date and time when the adapter has been
			seen by a discover procedure.

			Example: "2006-02-08 12:00:00 GMT"

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

			Question: Can we find a better name?

		string LastUsed(string address)

			Returns the date and time of the last time when the
			adapter has been connected.

			Example: "2006-02-08 12:00:00 GMT"

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

			Question: Can we find a better name?

		void DisconnectRemoteDevice(string address)

			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 RemoteDeviceDisconnectRequested 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.NotReady
					 org.bluez.Error.Failed
					 org.bluez.Error.NoSuchAdapter
					 org.bluez.Error.InvalidArguments
					 org.bluez.Error.NotConnected
					 org.bluez.Error.InProgress

		void CreateBonding(string address)

			This method creates a bonding with a remote device.

			If a link key for this adapter already exists, this
			procedure should fail instead of trying to create a
			new pairing.

			If no connection to the remote device exists, a
			low-level ACL connection must be created.

			This function will block and the calling application
			should take care of setting are higher timeout. This
			might be needed in case of a page timeout from the
			low-level HCI commands.

			In case of success it will send a BondingCreated
			signal.

			Possible errors: org.bluez.Error.NotReady
					 org.bluez.Error.Failed
					 org.bluez.Error.InvalidArguments
					 org.bluez.Error.AlreadyExists
					 org.bluez.Error.InProgress
					 org.bluez.Error.NoSuchAdapter
					 org.bluez.Error.ConnectionAttemptFailed
					 org.bluez.Error.AuthenticationFailed
					 org.bluez.Error.AuthenticationTimeout
					 org.bluez.Error.AuthenticationRejected
					 org.bluez.Error.AuthenticationCanceled

		void CancelBondingProcess(string address)

			This method will cancel the CreateBonding process.

			The CreateBonding method will return
			AuthenticationCanceled to signal that an attempt to
			create a bonding has been canceled.

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

		void RemoveBonding(string address)

			This method removes the bonding with a remote device.

			For security reasons this includes removing the actual
			link key and also disconnecting any open connections
			for the remote device.

			If the link key was stored on the Bluetooth chip, it
			must be removed from there, too.

			After deleting the link key this method will send a
			BondingRemoved signal.

			Possible errors: org.bluez.Error.NotReady
					 org.bluez.Error.Failed
					 org.bluez.Error.InvalidArguments
					 org.bluez.Error.NoSuchAdapter
					 org.bluez.Error.DoesNotExist

		boolean HasBonding(string address)

			Returns true if the remote device is bonded and false
			if no link key is available.

			Possible errors: org.bluez.Error.InvalidArguments

		array{string} ListBondings()

			List device addresses of currently bonded adapter.

			Possible errors: none

		uint8 GetPinCodeLength(string address)

			Returns the PIN code length that was used in the
			pairing process.

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

		uint8 GetEncryptionKeySize(string address)

			Returns the currently used encryption key size.

			This method will fail if no connection to the address
			has been established.

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

		void SetTrusted(string address)

			Marks the remote device as trusted. Authorization
			request will automatically succeed.

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

		boolean IsTrusted(string address)

			Returns true if the user is trusted or false otherwise.
			The address parameter must match one of the remote
			devices of the service.

			Possible errors: org.bluez.Error.InvalidArguments

		void RemoveTrust(string address)

			Marks the remote device as not trusted.

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

		array{string} ListTrusts()

			Returns a list of remote devices that are trusted.

		void DiscoverDevices()

			This method starts the device discovery procedure. This
			includes an inquiry procedure and remote device name
			resolving.

			On start up this process will generate a DiscoveryStarted
			signal and then return RemoteDeviceFound and also
			RemoteNameUpdated signals. If the procedure has been
			finished an DiscoveryCompleted signal will be sent.

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

		void DiscoverDevicesWithoutNameResolving()

			This method starts the device discovery procedure. This
			includes an inquiry and an optional remote device name
			resolving. The remote names can be retrieved with
			GetRemoteName and in the case a name doesn't exist it
			will be queued for later resolving and GetRemoteName
			will return an error.

			While this procedure is running every found device
			will be returned with RemoteDeviceFound. While
			DiscoverDevices() automatically resolves unknown
			devices names and sends RemoteNameUpdated in this
			case it will only happen if GetRemoteName has been
			called and no previously stored name is available.

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

		void CancelDiscovery()

			This method will cancel any previous DiscoverDevices
			or DiscoverDevicesWithoutNameResolving actions.

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

		void StartPeriodicDiscovery()

			This method starts a periodic discovery.

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

		void StopPeriodicDiscovery()

			This method stops a periodic discovery. If the
			adapter is not in the periodic inquiry mode an
			error(not authorized) is returned. Everyone can
			request exit from this mode, it is not restricted
			to start requestor.

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

		boolean IsPeriodicDiscovery()

			Returns true if the periodic inquiry is active and
			false if it is switched off.

			Possible errors: none

		void SetPeriodicDiscoveryNameResolving(boolean resolve_names)

			Enable or disable automatic remote name resolving for
			periodic discovery.

			Possible errors: org.bluez.Error.InvalidArguments

		boolean GetPeriodicDiscoveryNameResolving()

			Check if automatic remote name resolving is enabled or not
			for periodic discovery.

			Possible error: org.bluez.Error.InvalidArguments

		array{uint32} GetRemoteServiceHandles(string address, string match)

			This method will request the SDP database of a remote
			device and retrieve the service record handles. To
			request service browse send an empty match string.

			Possible errors: org.bluez.Error.InvalidArguments
					 org.bluez.Error.InProgress
					 org.bluez.Error.ConnectionAttemptFailed
					 org.bluez.Error.Failed

		array{byte} GetRemoteServiceRecord(string address, uint32 handle)

			This method will request the SDP database of a remote
			device for a service record and return the binary
			stream of it.

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

		string GetRemoteServiceRecordAsXML(string address, uint32 handle)

			This method will request the SDP database of a remote
			device for a service record and return its data in XML
			format.

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

		array{string} GetRemoteServiceIdentifiers(string address)

			This method will request the SDP database of a remote
			device for all supported services. The identifiers are
			returned in UUID 128 string format.

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

		void FinishRemoteServiceTransaction(string address)

			This method will finish all SDP transaction for that
			given address. In general this call is not needed,
			but in cases of resources restricted devices it
			is useful to call this to finish the SDP transaction
			before proceeded with profile specific connections.

		array{string} ListRemoteDevices()

			List addresses of all known remote devices (bonded,
			trusted and used).

			Possible errors: none

		array{string} ListRecentRemoteDevices(string date)

			List addresses of all bonded, trusted, seen or used remote
			devices since date. Bonded and trusted devices are always
			included(the date informed is not applied).

			date format is "YYYY-MM-DD HH:MM:SS GMT"

			Possible errors: none

Signals		void ModeChanged(string mode)

			If the current mode is changed with SetMode this signal
			will inform about the new mode.

			This signal can also be triggered by low-level HCI
			commands.

		void DiscoverableTimeoutChanged(uint32 timeout)

			After changing the discoverable timeout this signal
			provide the new timeout value.

		void MinorClassChanged(string minor)

			After changing the minor class with SetMinorClass this
			signal will provide the new class value.

		void NameChanged(string name)

			After changing the local adapter name with SetName this
			signal will provide the new name.

			This signal can also be triggered by low-level HCI
			commands.

		void DiscoveryStarted()

			This signal indicates that a device discovery
			procedure has been started.

		void DiscoveryCompleted()

			This signal indicates that a device discovery
			procedure has been completed.

		void PeriodicDiscoveryStarted()

			This signal indicates that a periodic discovery
			procedure has been started.

		void PeriodicDiscoveryStopped()

			This signal indicates that a periodic discovery
			procedure has been completed.

		void RemoteDeviceFound(string address, uint32 class, int16 rssi)

			This signal will be send every time an inquiry result
			has been found by the service daemon. In general they
			only appear during a device discovery.

		void RemoteDeviceDisappeared(string address)

			This signal will be send when an inquiry session for
			a periodic discovery finishes and previously found
			devices are no longer in range or visible.

		void RemoteClassUpdated(string address, uint32 class)

			This signal will be send every time the remote class
			of device has been changed. This happens for example
			after a remote connection attempt. This signal will
			not be send if the class of device hasn't changed
			compared to cached one.

		void RemoteNameUpdated(string address, string name)

			This signal will be send every time the service daemon
			detect a new name for a remote device.

		void RemoteIdentifiersUpdated(string address, array{string identifiers})

			This signal is sent to indicate the provided services of a given
			remote device. It will be sent after GetRemoteServiceIdentifiers
			calls. This signal has at least one identifier and it does not
			contain repeated entries.

		void RemoteNameFailed(string address)

			This signal will be sent every time the service daemon
			tries to resolve a remote and this fails.

		void RemoteNameRequested(string address)

			This signal will be sent every time the service daemon
			tries to resolve a remote name during discovery.

		void RemoteAliasChanged(string address, string alias)

			After changing an alias with SetRemoteAlias this
			signal will indicate the new alias.

		void RemoteAliasCleared(string address)

			After removing an alias with ClearRemoteAlias this
			signal will indicate that the alias is no longer
			valid.

		void RemoteDeviceConnected(string address)

			This signal will be send if a low level connection
			between two devices has been created.

		void RemoteDeviceDisconnectRequested(string address)

			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.

		void RemoteDeviceDisconnected(string address)

			This signal will be send if a low level connection
			between two devices has been terminated.

		void BondingCreated(string address)

			Signals that a successful bonding has been created.

		void BondingRemoved(string address)

			Signals that a bonding was removed.

		void TrustAdded(string address)
			
			Sent when SetTrusted() is called.

		void TrustRemoved(string address)

			Sent when RemoveTrust() is called.

Service hierarchy
=================

Service		org.bluez
Interface	org.bluez.Service
Object path	path from org.bluez.Manager.ListServices()

Methods		dict GetInfo()

			Returns the service properties.

		string GetIdentifier()

			This method returns the service identifier.

		string GetName()

			This method returns the service name.

		string GetDescription()

			This method returns the service description.

		string GetBusName() [experimental]

			Returns the unique bus name of the service if it has
			been started.

			Possible errors: org.bluez.Error.NotAvailable

		void Start()

			This method tells the system to start the
			service.

		void Stop()

			This method tells the system to stop the
			service.

		boolean IsRunning()

			Returns true if the service has been started and
			is currently active. Otherwise, it returns false.

		boolean IsExternal()

			Returns true if the service was registered using the
			Database.RegisterService method instead of a .service
			file. The Start and Stop methods are not applicable to
			external services and will return an error.

		array{string} ListTrusts() [experimental]

			Returns a list of remote devices that are trusted
			for the service.

		void SetTrusted(string address) [experimental]

			Marks the user as trusted.

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

		boolean IsTrusted(string address) [experimental]

			Returns true if the user is trusted or false otherwise.
			The address parameter must match one of the
			current users of the service.

			Possible errors: org.bluez.Error.InvalidArguments

		void RemoveTrust(string address) [experimental]

			Marks the user as not trusted.

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

Signals		void Started()

			The object path of this signal contains which service
			was started.

		void Stopped()

			The object path of this signal contains which service
			was stopped.

		void TrustAdded(string address)
			
			Sent when SetTrusted() is called.

		void TrustRemoved(string address)

			Sent when RemoveTrust() is called.


Security hierarchy
==================

Service		org.bluez
Interface	org.bluez.Security
Object path	/org/bluez or /org/bluez/{hci0,hci1,...}

Methods		void RegisterDefaultPasskeyAgent(string path)

			This registers the default passkey agent. It can
			register a passkey for all adapters or for a
			specific device depending on with object path has
			been used.

			The path parameter defines the object path of the
			passkey agent that will be called when a passkey
			needs to be entered.

			If an application disconnects from the bus all
			registered passkey agent will be removed.

			Possible errors: org.bluez.Error.AlreadyExists

		void UnregisterDefaultPasskeyAgent(string path)

			This unregisters a default passkey agent that has
			been previously registered. The object path and
			the path parameter must match the same values that
			has been used on registration.

			Possible errors: org.bluez.Error.DoesNotExist

		void RegisterPasskeyAgent(string path, string address)

			This registers the application passkey agent that
			will be used for any application specific passkey
			tasks.

			The path parameter defines the object path of the
			passkey agent that will be called when a passkey
			needs to be entered. The address defines the remote
			device that it will answer passkey requests for.

			If an application disconnects from the bus all
			registered passkey agent will be removed. It will
			also be unregistered after a timeout and if the
			pairing succeeds or fails. The application has to
			take care of that it reregisters the passkey agent.

			Possible errors: org.bluez.Error.AlreadyExists

		void UnregisterPasskeyAgent(string path, string address)

			This unregisters a passkey agent that has been
			previously registered. The object path and the path
			and address parameter must match the same values
			that has been used on registration.

			The method is actually only needed if an application
			wants to removed the passkey agent and don't wanna
			wait for the automatic timeout.

			Possible errors: org.bluez.Error.DoesNotExist

		void RegisterDefaultAuthorizationAgent(string path)

			This registers the default authorization agent. It can
			register an authorization agent for all adapters or
			for a specific one depending on which object path has
			been used.

			The path parameter defines the object path of the
			authorization agent that will be called when an
			authorization request needs to be answered.

		void UnregisterDefaultAuthorizationAgent(string path)

			This unregisters a default authorization agent that has
			been previously registered. The path parameter must
			match the same value that has been used on
			registration.


PasskeyAgent hierarchy
======================

Service		unique name
Interface	org.bluez.PasskeyAgent
Object path	freely definable

Methods		string Request(string path, string address, boolean numeric)

			This method gets called when the service daemon
			needs to get the passkey for an authentication. The
			return value is actual passkey.

			The first argument contains the path of the local
			adapter and the second one the remote address. The
			third argument signals if a numeric PIN code is
			expected or not. The default is a 1 to 16 byte PIN
			code in UTF-8 format.

			Possible errors: org.bluez.Error.Rejected
			                 org.bluez.Error.Canceled

		void Confirm(string path, string address, string value)

			This method gets called when the service daemon
			needs to verify a passkey. The verification is
			done by showing the value to the passkey agent
			and returning means a successful confirmation.
			In case the values don't match an error must
			be returned.

			Possible errors: org.bluez.Error.Rejected
			                 org.bluez.Error.Canceled

		void Display(string path, string address, string value)

			This method gets called when the service daemon
			needs to display the passkey value. No return
			value is needed. A successful paring will be
			indicated by the Complete method and a failure
			will be signaled with Cancel.

		void Keypress(string path, string address)

			This method indicates keypresses from the remote
			device. This can happen when pairing with a keyboard.

		void Complete(string path, string address)

			This method gets called to indicate that the
			authentication has been completed.

		void Cancel(string path, string address)

			This method gets called to indicate that the
			authentication request failed before a reply was
			returned by the Request method.

		void Release()

			This method gets called when the service daemon
			unregisters a passkey agent. An agent can use
			it to do cleanup tasks. There is no need to
			unregister the agent, because when this method
			gets called it has already been unregistered.


AuthorizationAgent hierarchy (experimental)
===========================================

Service		unique name
Interface	org.bluez.AuthorizationAgent
Object path	freely definable

Methods		void Authorize(string adapter_path, string address,
					string service_path, string uuid)

			This method gets called when the service daemon wants
			to get an authorization for accessing a service. This
			method should return if the remote user is granted
			access or an error otherwise.

			The adapter_path parameter is the object path of the
			local adapter. The address, service_path and action
			parameters correspond to the remote device address,
			the object path of the service and the uuid of the
			profile.

			Possible errors: org.bluez.Error.Rejected
			                 org.bluez.Error.Canceled

		void Cancel(string adapter_path, string address,
					string service_path, string uuid)

			This method cancels a previous authorization request.
			The adapter_path, address, service_path and uuid
			parameters must match the same values that have been
			used when the Authorize() method was called.

		void Release()

			This method gets called when the service daemon
			unregisters an authorization agent. An agent can
			use it to do cleanup tasks. There is no need to
			unregister the agent, because when this method
			gets called it has already been unregistered.