From 2498ab2e65fb661d828f45c4921af8c43aa0fdcc Mon Sep 17 00:00:00 2001
From: Marcel Holtmann <marcel@holtmann.org>
Date: Thu, 13 Mar 2008 19:05:18 +0000
Subject: Update adapter API documentation

---
 doc/adapter-api.txt | 118 +++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 93 insertions(+), 25 deletions(-)

(limited to 'doc/adapter-api.txt')

diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt
index 0ddc1a42..259e7018 100644
--- a/doc/adapter-api.txt
+++ b/doc/adapter-api.txt
@@ -16,19 +16,17 @@ Object path	/org/bluez/{hci0,hci1,...}
 
 Methods		dict GetProperties()
 
-			TBD
+			Returns all properties for the adapter. See the
+			properties section for available properties.
 
-		void SetProperty(string name, variant value)
-
-			TBD
-
-		array{object} ListDevices()
-
-			TBD
+			Possible Errors: org.bluez.Error.DoesNotExist
+					 org.bluez.Error.InvalidArguments
 
-		object FindDevice(string address)
+		void SetProperty(string name, variant value)
 
-			Returns the object path of a device given an address.
+			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
@@ -59,52 +57,122 @@ Methods		dict GetProperties()
 					 org.bluez.Error.NotAuthorized
 					 org.bluez.Error.NoSuchAdapter
 
+		object FindDevice(string address)
+
+			Returns the object path of device for given address.
+			The device object needs to be first created via
+			CreateDevice or CreatePairedDevice.
+
+			Possible Errors: org.bluez.Error.DoesNotExist
+					 org.bluez.Error.InvalidArguments
+
+		array{object} ListDevices()
+
+			Returns list of device object paths.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.Failed
+					 org.bluez.Error.OutOfMemory
+
 		object CreateDevice(string address)
 
-			TBD
+			Creates a new object path for a remote device. This
+			method will connect to the remote device and retrieve
+			all SDP records.
 
-		object CreateDeviceWithAgent(string address, object agent)
+			If the object for the remote device already exists
+			this method will fail.
 
-			TBD
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.Failed
 
-		void RemoveDevice(object device)
+		object CreatePairedDevice(string address, object agent)
 
-			TBD
+			Creates a new object path for a remote device. This
+			method will connect to the remote device and retrieve
+			all SDP records and then initiate the pairing.
 
-Signals		DeviceCreated(object device)
+			If previously CreateDevice was used successfully,
+			this method will only initiate the pairing.
 
-			TBD
+			Compared to CreateDevice this method will fail if
+			the pairing already exists, but not if the object
+			path already has been created. This allows applications
+			to use CreateDevice first and the if needed use
+			CreatePairedDevice to initiate pairing.
 
-		DeviceRemoved(object device)
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.Failed
+
+		void RemoveDevice(object device)
+
+			This removes the remote device object at the given
+			path. It will remove also the pairing information.
 
-			TBD
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.Failed
 
-		PropertyChanged(string name, variant value)
+Signals		PropertyChanged(string name, variant value)
 
-			TBD
+			This signal indicates a changed value of the given
+			property.
 
 		DiscoveryStarted()
 
-			TBD
+			This signal indicates that a device discovery
+			procedure has been started.
 
 		DiscoveryCompleted()
 
-			TBD
+			This signal indicates that a device discovery
+			procedure has been completed.
 
 		DeviceFound(string address, dict values)
 
-			TBD
+			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.
 
 		DeviceDisappeared(string address)
 
-			TBD
+			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.
+
+		DeviceCreated(object device)
+
+			Parameter is object path of created device.
+
+		DeviceRemoved(object device)
+
+			Parameter is object path of removed device.
 
 Properties	string Address [readonly]
 
+			The Bluetooth device address.
+
 		string Name [readwrite]
 
+			The Bluetooth friendly name. This value can be
+			changed and a PropertyChanged signal will be emitted.
+
 		string Mode [readwrite]
 
+			The Bluetooth operation mode.
+
+			Valid modes: "off", "connectable",
+						"discoverable", "limited"
+
 		uint32 DiscoverableTimeout [readwrite]
 
+			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).
+
 		boolean PeriodicDiscovery [readwrite]
+
+			Is peridoic inquiry active or not. Changing this
+			property will either enable or disable it.
-- 
cgit