[RFC v1 1/9] adapter: fix setting of discoverable timeout

[RFC v1 1/9] adapter: fix setting of discoverable timeout

[Gustavo Padovan]

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

The mgmt_cp_set_discoverable struct was getting reset for no reason after
we set up the discoverable timeout value.
---
 src/adapter.c | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/src/adapter.c b/src/adapter.c
index 1250966..af3e3ea 100644
--- a/src/adapter.c
+++ b/src/adapter.c
@@ -1907,9 +1907,6 @@ static void property_set_mode(struct btd_adapter *adapter, uint32_t setting,
 		goto failed;
 	}
 
-	memset(&cp, 0, sizeof(cp));
-	cp.val = (enable == TRUE) ? 0x01 : 0x00;
-
 	DBG("sending %s command for index %u", mgmt_opstr(opcode),
 							adapter->dev_id);
 
-- 
1.8.1.4

[RFC v1 2/9] adapter: remove unused toggle_discoverable

[Gustavo Padovan]

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

---
 src/adapter.c | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/adapter.c b/src/adapter.c
index af3e3ea..5f01edf 100644
--- a/src/adapter.c
+++ b/src/adapter.c
@@ -172,7 +172,6 @@ struct btd_adapter {
 	struct btd_device *connect_le;	/* LE device waiting to be connected */
 	sdp_list_t *services;		/* Services associated to adapter */
 
-	bool toggle_discoverable;	/* discoverable needs to be changed */
 	gboolean initialized;
 
 	GSList *pin_callbacks;
-- 
1.8.1.4

[RFC v1 3/9] adapter: rename discovery_client to watch_client

[Gustavo Padovan]

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

Rename to a more generic name since we will have different uses for this.
---
 src/adapter.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/adapter.c b/src/adapter.c
index 5f01edf..0277057 100644
--- a/src/adapter.c
+++ b/src/adapter.c
@@ -105,7 +105,7 @@ static uint8_t mgmt_revision = 0;
 
 static GSList *adapter_drivers = NULL;
 
-struct discovery_client {
+struct watch_client {
 	struct btd_adapter *adapter;
 	char *owner;
 	guint watch;
@@ -1480,7 +1480,7 @@ static void stop_discovery_complete(uint8_t status, uint16_t length,
 
 static int compare_discovery_sender(gconstpointer a, gconstpointer b)
 {
-	const struct discovery_client *client = a;
+	const struct watch_client *client = a;
 	const char *sender = b;
 
 	return g_strcmp0(client->owner, sender);
@@ -1522,7 +1522,7 @@ static gboolean remove_temp_devices(gpointer user_data)
 
 static void discovery_destroy(void *user_data)
 {
-	struct discovery_client *client = user_data;
+	struct watch_client *client = user_data;
 	struct btd_adapter *adapter = client->adapter;
 
 	DBG("owner %s", client->owner);
@@ -1560,7 +1560,7 @@ static void discovery_destroy(void *user_data)
 
 static void discovery_disconnect(DBusConnection *conn, void *user_data)
 {
-	struct discovery_client *client = user_data;
+	struct watch_client *client = user_data;
 	struct btd_adapter *adapter = client->adapter;
 	struct mgmt_cp_stop_discovery cp;
 
@@ -1604,7 +1604,7 @@ static DBusMessage *start_discovery(DBusConnection *conn,
 {
 	struct btd_adapter *adapter = user_data;
 	const char *sender = dbus_message_get_sender(msg);
-	struct discovery_client *client;
+	struct watch_client *client;
 	GSList *list;
 
 	DBG("sender %s", sender);
@@ -1621,7 +1621,7 @@ static DBusMessage *start_discovery(DBusConnection *conn,
 	if (list)
 		return btd_error_busy(msg);
 
-	client = g_new0(struct discovery_client, 1);
+	client = g_new0(struct watch_client, 1);
 
 	client->adapter = adapter;
 	client->owner = g_strdup(sender);
@@ -1648,7 +1648,7 @@ static DBusMessage *stop_discovery(DBusConnection *conn,
 	struct btd_adapter *adapter = user_data;
 	const char *sender = dbus_message_get_sender(msg);
 	struct mgmt_cp_stop_discovery cp;
-	struct discovery_client *client;
+	struct watch_client *client;
 	GSList *list;
 
 	DBG("sender %s", sender);
@@ -4264,7 +4264,7 @@ static void adapter_stop(struct btd_adapter *adapter)
 	cancel_passive_scanning(adapter);
 
 	while (adapter->discovery_list) {
-		struct discovery_client *client;
+		struct watch_client *client;
 
 		client = adapter->discovery_list->data;
 
-- 
1.8.1.4

[RFC v1 4/9] adapter: rename compare_discovery_sender

[Gustavo Padovan]

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

The new name "compare_sender" is more generic and will be used for more
than one purpose.
---
 src/adapter.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/adapter.c b/src/adapter.c
index 0277057..bb5737e 100644
--- a/src/adapter.c
+++ b/src/adapter.c
@@ -1478,7 +1478,7 @@ static void stop_discovery_complete(uint8_t status, uint16_t length,
 	}
 }
 
-static int compare_discovery_sender(gconstpointer a, gconstpointer b)
+static int compare_sender(gconstpointer a, gconstpointer b)
 {
 	const struct watch_client *client = a;
 	const char *sender = b;
@@ -1617,7 +1617,7 @@ static DBusMessage *start_discovery(DBusConnection *conn,
 	 * already started a discovery then return an error.
 	 */
 	list = g_slist_find_custom(adapter->discovery_list, sender,
-						compare_discovery_sender);
+						compare_sender);
 	if (list)
 		return btd_error_busy(msg);
 
@@ -1657,7 +1657,7 @@ static DBusMessage *stop_discovery(DBusConnection *conn,
 		return btd_error_not_ready(msg);
 
 	list = g_slist_find_custom(adapter->discovery_list, sender,
-						compare_discovery_sender);
+						compare_sender);
 	if (!list)
 		return btd_error_failed(msg, "No discovery started");
 
-- 
1.8.1.4

[RFC v1 5/9] doc: add RequestPairingSession() and ReleasePairingSession()

[Gustavo Padovan]

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

Those methods improve the tracking of the Discoverable and Pairable
properties for Pairing purposes. One could call RequestPairingSession()
to get a Pairing session.

ReleasePairingSession() releases a session. If the client exits without
calling the ReleasePairingSession() the session is also released.
When the last session is released both Discoverable and Pairing goes back
the their original value.

The Pairing property tracks if the there is a ongoing Pairing session.
---
 doc/adapter-api.txt | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt
index 74d235a..4d205f2 100644
--- a/doc/adapter-api.txt
+++ b/doc/adapter-api.txt
@@ -35,6 +35,37 @@ Methods		void StartDiscovery()
 					 org.bluez.Error.Failed
 					 org.bluez.Error.NotAuthorized
 
+		void RequestPairingSession()
+
+			This method starts a Pairing session, it enables both
+			Discoverable and Pairable properties and tracks the
+			lifetime of the client that requested it. The client can
+			release the session by calling ReleasePairingSession().
+			The session is also released if the clients exits
+			unexpectedly.
+
+			Many sessions can be created by different clients. When
+			last session is released Discoverable and Pairable are
+			set back to wherever value they had before the request
+			of the first session.
+
+			The Pairing property show if there is a ongoing session
+			or not.
+
+			Possible errors: org.bluez.Error.NotReady
+					 org.bluez.Error.Failed
+
+		void ReleasePairingSession()
+
+			This method removes a Pairing session. When called
+			it will remove the session and if it is the last session
+			Discoverable and Pairable will be set to the value they
+			had before the beginning of the first session.
+
+			Possible errors: org.bluez.Error.NotReady
+					 org.bluez.Error.Failed
+					 org.bluez.Error.NotAuthorized
+
 		void RemoveDevice(object device)
 
 			This removes the remote device object at the given
@@ -111,6 +142,9 @@ Properties	string Address [readonly]
 
 			For any new adapter this settings defaults to false.
 
+			This property will become readonly if a Pairing session
+			is ongoing.
+
 		boolean Pairable [readwrite]
 
 			Switch an adapter to pairable or non-pairable. This is
@@ -122,6 +156,9 @@ Properties	string Address [readonly]
 
 			For any new adapter this settings defaults to true.
 
+			This property will become readonly if a Pairing session
+			is ongoing.
+
 		uint32 PairableTimeout [readwrite]
 
 			The pairable timeout in seconds. A value of zero
@@ -131,6 +168,9 @@ Properties	string Address [readonly]
 			The default value for pairable timeout should be
 			disabled (value 0).
 
+			This property will become readonly if a Pairing session
+			is ongoing.
+
 		uint32 DiscoverableTimeout [readwrite]
 
 			The discoverable timeout in seconds. A value of zero
@@ -140,10 +180,17 @@ Properties	string Address [readonly]
 			The default value for the discoverable timeout should
 			be 180 seconds (3 minutes).
 
+			This property will become readonly if a Pairing session
+			is ongoing.
+
 		boolean Discovering [readonly]
 
 			Indicates that a device discovery procedure is active.
 
+		boolean Pairing [readonly]
+
+			Indicates that one or more pairing session is active.
+
 		array{string} UUIDs [readonly]
 
 			List of 128-bit UUIDs that represents the available
-- 
1.8.1.4

[RFC v1 6/9] adapter: add RequestPairingSession() and ReleasePairingSession()

[Gustavo Padovan]

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

With those two methods BlueZ is now aware of client lifetime and can set
Discoverable and Pairable back to their original values when all session
are released.

A session is released either by calling ReleasePairingSession() or if the
client exits unexpectedly. Many session can exist in a given time.
---
 src/adapter.c | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)

diff --git a/src/adapter.c b/src/adapter.c
index bb5737e..5e8c675 100644
--- a/src/adapter.c
+++ b/src/adapter.c
@@ -169,6 +169,8 @@ struct btd_adapter {
 	GSList *connections;		/* Connected devices */
 	GSList *devices;		/* Devices structure pointers */
 	GSList *connect_list;		/* Devices to connect when found */
+	uint32_t pairing_settings;	/* settings before pairing session*/
+	GSList *pairing_list;		/* list of pairing sessions */
 	struct btd_device *connect_le;	/* LE device waiting to be connected */
 	sdp_list_t *services;		/* Services associated to adapter */
 
@@ -1699,6 +1701,129 @@ static DBusMessage *stop_discovery(DBusConnection *conn,
 	return dbus_message_new_method_return(msg);
 }
 
+static void discoverable_destroy(void *user_data)
+{
+	struct watch_client *client = user_data;
+	struct btd_adapter *adapter = client->adapter;
+
+	DBG("owner %s", client->owner);
+
+	adapter->pairing_list = g_slist_remove(adapter->pairing_list,
+								client);
+
+	g_free(client->owner);
+	g_free(client);
+}
+
+static void discoverable_disconnect(DBusConnection *conn, void *user_data)
+{
+	struct watch_client *client = user_data;
+	struct btd_adapter *adapter = client->adapter;
+
+	DBG("owner %s", client->owner);
+
+	adapter->pairing_list = g_slist_remove(adapter->pairing_list,
+								client);
+
+	if (adapter->pairing_list)
+		return;
+
+	set_discoverable(adapter,0x01, adapter->discoverable_timeout);
+	if (!(adapter->pairing_settings & MGMT_SETTING_DISCOVERABLE))
+		set_discoverable(adapter,0x00, 0);
+
+	if (!(adapter->pairing_settings & MGMT_SETTING_PAIRABLE))
+		set_mode(adapter, MGMT_OP_SET_PAIRABLE, 0x00);
+}
+
+static DBusMessage *request_pairing_session(DBusConnection *conn,
+					DBusMessage *msg, void *user_data)
+{
+	struct btd_adapter *adapter = user_data;
+	const char *sender = dbus_message_get_sender(msg);
+	struct watch_client *client;
+	bool first;
+
+	DBG("sender %s", sender);
+
+	if (!(adapter->current_settings & MGMT_SETTING_POWERED))
+		return btd_error_not_ready(msg);
+
+	/*
+	 * Every client can only start one pairable session, if the client
+	 * already started a pairable session then return an error.
+	 */
+	if (g_slist_find_custom(adapter->pairing_list, sender,
+						compare_sender))
+		return btd_error_busy(msg);
+
+	client = g_new0(struct watch_client, 1);
+
+	client->adapter = adapter;
+	client->owner = g_strdup(sender);
+	client->watch = g_dbus_add_disconnect_watch(dbus_conn, sender,
+						discoverable_disconnect, client,
+						discoverable_destroy);
+
+	first = (adapter->pairing_list == NULL);
+
+	adapter->pairing_list = g_slist_prepend(adapter->pairing_list,
+								client);
+
+	if (!first)
+		return dbus_message_new_method_return(msg);
+
+	adapter->pairing_settings = adapter->current_settings &
+		(MGMT_SETTING_DISCOVERABLE | MGMT_SETTING_PAIRABLE);
+
+	set_discoverable(adapter,0x01, 0);
+
+	if (!(adapter->pairing_settings & MGMT_SETTING_PAIRABLE))
+		set_mode(adapter, MGMT_OP_SET_PAIRABLE, 0x01);
+
+	return dbus_message_new_method_return(msg);
+}
+
+static DBusMessage *release_pairing_session(DBusConnection *conn,
+					DBusMessage *msg, void *user_data)
+{
+	struct btd_adapter *adapter = user_data;
+	const char *sender = dbus_message_get_sender(msg);
+	struct watch_client *client;
+	GSList *list;
+
+	DBG("sender %s", sender);
+
+	if (!(adapter->current_settings & MGMT_SETTING_POWERED))
+		return btd_error_not_ready(msg);
+
+	list = g_slist_find_custom(adapter->pairing_list, sender,
+						compare_sender);
+	if (!list)
+		return btd_error_failed(msg, "No pairing session started");
+
+	client = list->data;
+
+	/*
+	 * The destroy function will cleanup the client information and
+	 * also remove it from the list of pairing clients.
+	 */
+	g_dbus_remove_watch(dbus_conn, client->watch);
+
+	/* If it is the last pairing session */
+	if (adapter->pairing_list)
+		return dbus_message_new_method_return(msg);
+
+	set_discoverable(adapter,0x01, adapter->discoverable_timeout);
+	if (!(adapter->pairing_settings & MGMT_SETTING_DISCOVERABLE))
+		set_discoverable(adapter,0x00, 0);
+
+	if (!(adapter->pairing_settings & MGMT_SETTING_PAIRABLE))
+		set_mode(adapter, MGMT_OP_SET_PAIRABLE, 0x00);
+
+	return dbus_message_new_method_return(msg);
+}
+
 static gboolean property_get_address(const GDBusPropertyTable *property,
 					DBusMessageIter *iter, void *user_data)
 {
@@ -2153,6 +2278,10 @@ static DBusMessage *remove_device(DBusConnection *conn,
 static const GDBusMethodTable adapter_methods[] = {
 	{ GDBUS_METHOD("StartDiscovery", NULL, NULL, start_discovery) },
 	{ GDBUS_METHOD("StopDiscovery", NULL, NULL, stop_discovery) },
+	{ GDBUS_METHOD("RequestPairingSession", NULL, NULL,
+						request_pairing_session) },
+	{ GDBUS_METHOD("ReleasePairingSession", NULL, NULL,
+						release_pairing_session) },
 	{ GDBUS_ASYNC_METHOD("RemoveDevice",
 			GDBUS_ARGS({ "device", "o" }), NULL, remove_device) },
 	{ }
-- 
1.8.1.4

[RFC v1 7/9] adapter: add Pairing property to report ongoing Pairing Session

[Gustavo Padovan]

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

Pairing is a readonly property that will be true whenever on or more
Pairing Sessions are running.
---
 src/adapter.c | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/src/adapter.c b/src/adapter.c
index 5e8c675..f4b0892 100644
--- a/src/adapter.c
+++ b/src/adapter.c
@@ -169,8 +169,11 @@ struct btd_adapter {
 	GSList *connections;		/* Connected devices */
 	GSList *devices;		/* Devices structure pointers */
 	GSList *connect_list;		/* Devices to connect when found */
+
+	bool pairing;			/* pairing property state */
 	uint32_t pairing_settings;	/* settings before pairing session*/
 	GSList *pairing_list;		/* list of pairing sessions */
+
 	struct btd_device *connect_le;	/* LE device waiting to be connected */
 	sdp_list_t *services;		/* Services associated to adapter */
 
@@ -1734,6 +1737,11 @@ static void discoverable_disconnect(DBusConnection *conn, void *user_data)
 
 	if (!(adapter->pairing_settings & MGMT_SETTING_PAIRABLE))
 		set_mode(adapter, MGMT_OP_SET_PAIRABLE, 0x00);
+
+	adapter->pairing = false;
+
+	g_dbus_emit_property_changed(dbus_conn, adapter->path,
+					ADAPTER_INTERFACE, "Pairing");
 }
 
 static DBusMessage *request_pairing_session(DBusConnection *conn,
@@ -1781,6 +1789,11 @@ static DBusMessage *request_pairing_session(DBusConnection *conn,
 	if (!(adapter->pairing_settings & MGMT_SETTING_PAIRABLE))
 		set_mode(adapter, MGMT_OP_SET_PAIRABLE, 0x01);
 
+	adapter->pairing = true;
+
+	g_dbus_emit_property_changed(dbus_conn, adapter->path,
+					ADAPTER_INTERFACE, "Pairing");
+
 	return dbus_message_new_method_return(msg);
 }
 
@@ -1821,6 +1834,11 @@ static DBusMessage *release_pairing_session(DBusConnection *conn,
 	if (!(adapter->pairing_settings & MGMT_SETTING_PAIRABLE))
 		set_mode(adapter, MGMT_OP_SET_PAIRABLE, 0x00);
 
+	adapter->pairing = false;
+
+	g_dbus_emit_property_changed(dbus_conn, adapter->path,
+					ADAPTER_INTERFACE, "Pairing");
+
 	return dbus_message_new_method_return(msg);
 }
 
@@ -2175,6 +2193,17 @@ static void property_set_pairable_timeout(const GDBusPropertyTable *property,
 	trigger_pairable_timeout(adapter);
 }
 
+static gboolean property_get_pairing(const GDBusPropertyTable *property,
+					DBusMessageIter *iter, void *user_data)
+{
+	struct btd_adapter *adapter = user_data;
+	dbus_bool_t pairing = adapter->pairing;
+
+	dbus_message_iter_append_basic(iter, DBUS_TYPE_BOOLEAN, &pairing);
+
+	return TRUE;
+}
+
 static gboolean property_get_discovering(const GDBusPropertyTable *property,
 					DBusMessageIter *iter, void *user_data)
 {
@@ -2300,6 +2329,7 @@ static const GDBusPropertyTable adapter_properties[] = {
 	{ "Pairable", "b", property_get_pairable, property_set_pairable },
 	{ "PairableTimeout", "u", property_get_pairable_timeout,
 					property_set_pairable_timeout },
+	{ "Pairing", "b", property_get_pairing },
 	{ "Discovering", "b", property_get_discovering },
 	{ "UUIDs", "as", property_get_uuids },
 	{ "Modalias", "s", property_get_modalias, NULL,
-- 
1.8.1.4

[RFC v1 8/9] adapter: forbid properties to be set during Pairing Session

[Gustavo Padovan]

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

If one or more pairing session is ongoing the following properties can't
be set: Pairable, PairableTimeout, Discoverable and DiscoverableTimeout.
---
 src/adapter.c | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/src/adapter.c b/src/adapter.c
index f4b0892..ee6e2d9 100644
--- a/src/adapter.c
+++ b/src/adapter.c
@@ -2108,6 +2108,13 @@ static void property_set_discoverable(const GDBusPropertyTable *property,
 {
 	struct btd_adapter *adapter = user_data;
 
+	if (adapter->pairing) {
+		g_dbus_pending_property_error(id,
+					ERROR_INTERFACE ".PermissionDenied",
+					"Pairing session ongoing");
+		return;
+	}
+
 	property_set_mode(adapter, MGMT_SETTING_DISCOVERABLE, iter, id);
 }
 
@@ -2131,6 +2138,13 @@ static void property_set_discoverable_timeout(
 	struct btd_adapter *adapter = user_data;
 	dbus_uint32_t value;
 
+	if (adapter->pairing) {
+		g_dbus_pending_property_error(id,
+					ERROR_INTERFACE ".PermissionDenied",
+					"Pairing session ongoing");
+		return;
+	}
+
 	dbus_message_iter_get_basic(iter, &value);
 
 	adapter->discoverable_timeout = value;
@@ -2160,6 +2174,13 @@ static void property_set_pairable(const GDBusPropertyTable *property,
 {
 	struct btd_adapter *adapter = user_data;
 
+	if (adapter->pairing) {
+		g_dbus_pending_property_error(id,
+					ERROR_INTERFACE ".PermissionDenied",
+					"Pairing session ongoing");
+		return;
+	}
+
 	property_set_mode(adapter, MGMT_SETTING_PAIRABLE, iter, id);
 }
 
@@ -2182,6 +2203,13 @@ static void property_set_pairable_timeout(const GDBusPropertyTable *property,
 	struct btd_adapter *adapter = user_data;
 	dbus_uint32_t value;
 
+	if (adapter->pairing) {
+		g_dbus_pending_property_error(id,
+					ERROR_INTERFACE ".PermissionDenied",
+					"Pairing session ongoing");
+		return;
+	}
+
 	dbus_message_iter_get_basic(iter, &value);
 
 	adapter->pairable_timeout = value;
-- 
1.8.1.4

[RFC v1 9/9] test: add pairing command to test-adapter

[Gustavo Padovan]

From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

It creates and then release the Pairing Session after 20 seconds.
---
 test/test-adapter | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/test/test-adapter b/test/test-adapter
index 5deeda4..b424b16 100755
--- a/test/test-adapter
+++ b/test/test-adapter
@@ -136,6 +136,14 @@ if (args[0] == "discoverabletimeout"):
 		adapter.Set("org.bluez.Adapter1", "DiscoverableTimeout", to)
 	sys.exit(0)
 
+if (args[0] == "pairing"):
+	adapter1 = dbus.Interface(bus.get_object("org.bluez", adapter_path),
+					"org.bluez.Adapter1")
+	adapter1.RequestPairingSession()
+	time.sleep(20);
+	adapter1.ReleasePairingSession()
+	sys.exit(0)
+
 if (args[0] == "discovering"):
 	discovering = adapter.Get("org.bluez.Adapter1", "Discovering")
 	print(discovering)
-- 
1.8.1.4

Re: [RFC v1 5/9] doc: add RequestPairingSession() and ReleasePairingSession()

[Marcel Holtmann]

Hi Gustavo,

> Those methods improve the tracking of the Discoverable and Pairable
> properties for Pairing purposes. One could call RequestPairingSession()
> to get a Pairing session.
> 
> ReleasePairingSession() releases a session. If the client exits without
> calling the ReleasePairingSession() the session is also released.
> When the last session is released both Discoverable and Pairing goes back
> the their original value.
> 
> The Pairing property tracks if the there is a ongoing Pairing session.
> ---
> doc/adapter-api.txt | 47 +++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 47 insertions(+)
> 
> diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt
> index 74d235a..4d205f2 100644
> --- a/doc/adapter-api.txt
> +++ b/doc/adapter-api.txt
> @@ -35,6 +35,37 @@ Methods		void StartDiscovery()
> 					 org.bluez.Error.Failed
> 					 org.bluez.Error.NotAuthorized
> 
> +		void RequestPairingSession()

my current thinking is that naming these EnablePairing and DisablePairing is a bit simple and more intuitive and fits better with StartDiscovery and StopDiscovery.

> +
> +			This method starts a Pairing session, it enables both
> +			Discoverable and Pairable properties and tracks the
> +			lifetime of the client that requested it. The client can
> +			release the session by calling ReleasePairingSession().
> +			The session is also released if the clients exits
> +			unexpectedly.
> +
> +			Many sessions can be created by different clients. When
> +			last session is released Discoverable and Pairable are
> +			set back to wherever value they had before the request
> +			of the first session.
> +
> +			The Pairing property show if there is a ongoing session
> +			or not.

Make sure to note the effect on the Pairable and Discoverable properties.

> +
> +			Possible errors: org.bluez.Error.NotReady
> +					 org.bluez.Error.Failed
> +
> +		void ReleasePairingSession()
> +
> +			This method removes a Pairing session. When called
> +			it will remove the session and if it is the last session
> +			Discoverable and Pairable will be set to the value they
> +			had before the beginning of the first session.
> +
> +			Possible errors: org.bluez.Error.NotReady
> +					 org.bluez.Error.Failed
> +					 org.bluez.Error.NotAuthorized
> +
> 		void RemoveDevice(object device)
> 
> 			This removes the remote device object at the given
> @@ -111,6 +142,9 @@ Properties	string Address [readonly]
> 
> 			For any new adapter this settings defaults to false.
> 
> +			This property will become readonly if a Pairing session
> +			is ongoing.
> +
> 		boolean Pairable [readwrite]
> 
> 			Switch an adapter to pairable or non-pairable. This is
> @@ -122,6 +156,9 @@ Properties	string Address [readonly]
> 
> 			For any new adapter this settings defaults to true.
> 
> +			This property will become readonly if a Pairing session
> +			is ongoing.
> +
> 		uint32 PairableTimeout [readwrite]
> 
> 			The pairable timeout in seconds. A value of zero
> @@ -131,6 +168,9 @@ Properties	string Address [readonly]
> 			The default value for pairable timeout should be
> 			disabled (value 0).
> 
> +			This property will become readonly if a Pairing session
> +			is ongoing.
> +
> 		uint32 DiscoverableTimeout [readwrite]
> 
> 			The discoverable timeout in seconds. A value of zero
> @@ -140,10 +180,17 @@ Properties	string Address [readonly]
> 			The default value for the discoverable timeout should
> 			be 180 seconds (3 minutes).
> 
> +			This property will become readonly if a Pairing session
> +			is ongoing.
> +
> 		boolean Discovering [readonly]
> 
> 			Indicates that a device discovery procedure is active.
> 
> +		boolean Pairing [readonly]
> +
> +			Indicates that one or more pairing session is active.
> +

Not super happy with the name, but I could live with it.

Regards

Marcel

Re: [RFC v1 5/9] doc: add RequestPairingSession() and ReleasePairingSession()

[Bastien Nocera]

On Tue, 2013-06-11 at 01:03 +0100, Gustavo Padovan wrote:
> From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>
> 
> Those methods improve the tracking of the Discoverable and Pairable
> properties for Pairing purposes. One could call RequestPairingSession()
> to get a Pairing session.
> 
> ReleasePairingSession() releases a session. If the client exits without
> calling the ReleasePairingSession() the session is also released.
> When the last session is released both Discoverable and Pairing goes back
                                                          ^^^^^^^
Paired. Though Pairing does go back to its original "False" value...

> the their original value.
> 
> The Pairing property tracks if the there is a ongoing Pairing session.

I agree with Marcel that "Pairing" is a confusing name. PairingMode?

Re: [RFC v1 5/9] doc: add RequestPairingSession() and ReleasePairingSession()

[Gustavo Padovan]

* Bastien Nocera <hadess@hadess.net> [2013-06-11 12:00:15 +0200]:

> On Tue, 2013-06-11 at 01:03 +0100, Gustavo Padovan wrote:
> > From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>
> > 
> > Those methods improve the tracking of the Discoverable and Pairable
> > properties for Pairing purposes. One could call RequestPairingSession()
> > to get a Pairing session.
> > 
> > ReleasePairingSession() releases a session. If the client exits without
> > calling the ReleasePairingSession() the session is also released.
> > When the last session is released both Discoverable and Pairing goes back
>                                                           ^^^^^^^
> Paired. Though Pairing does go back to its original "False" value...

Actually it is "Pairable". The original value is the one before start the
first Pairing Session. Maybe I should rewrite this part.

> 
> > the their original value.
> > 
> > The Pairing property tracks if the there is a ongoing Pairing session.
> 
> I agree with Marcel that "Pairing" is a confusing name. PairingMode?

The I would to rename the methods to EnablePairingMode() and so on.

	Gustavo

Re: [RFC v1 5/9] doc: add RequestPairingSession() and ReleasePairingSession()

[Bastien Nocera]

On Tue, 2013-06-11 at 11:07 +0100, Gustavo Padovan wrote:
> * Bastien Nocera <hadess@hadess.net> [2013-06-11 12:00:15 +0200]:
> 
> > On Tue, 2013-06-11 at 01:03 +0100, Gustavo Padovan wrote:
> > > From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>
> > > 
> > > Those methods improve the tracking of the Discoverable and Pairable
> > > properties for Pairing purposes. One could call RequestPairingSession()
> > > to get a Pairing session.
> > > 
> > > ReleasePairingSession() releases a session. If the client exits without
> > > calling the ReleasePairingSession() the session is also released.
> > > When the last session is released both Discoverable and Pairing goes back
> >                                                           ^^^^^^^
> > Paired. Though Pairing does go back to its original "False" value...
> 
> Actually it is "Pairable".

Replaced the error by another error. Time for more coffee!

>  The original value is the one before start the
> first Pairing Session. Maybe I should rewrite this part.