[gcr] gcr: Fine tune dbus prompting interface

[Stefan Walter <stefw src gnome org>]

commit 6bf4da09ec89522ec1f7049976bfe503eaadaf5b
Author: Stef Walter <stefw collabora co uk>
Date:   Mon Dec 19 07:58:00 2011 +0100

    gcr: Fine tune dbus prompting interface
    
    https://bugzilla.gnome.org/show_bug.cgi?id=656954

 gcr/Makefile.am                    |    3 +-
 gcr/gcr-dbus-constants.h           |    2 +-
 gcr/gcr-system-prompt.c            |    3 +-
 gcr/gcr-system-prompter.c          |    2 +-
 gcr/org.gnome.keyring.Prompt.xml   |    6 ----
 gcr/org.gnome.keyring.Prompter.xml |   57 +++++++++++++++++++++++++++++++++++-
 6 files changed, 61 insertions(+), 12 deletions(-)
---
diff --git a/gcr/Makefile.am b/gcr/Makefile.am
index f1d1bba..79ca5d2 100644
--- a/gcr/Makefile.am
+++ b/gcr/Makefile.am
@@ -261,8 +261,7 @@ gcr-oids.c: gcr-oids.list gcr-mkoids
 gcr-oids.h: gcr-oids.c
 
 DBUS_XML_DEFINITIONS = \
-	org.gnome.keyring.Prompter.xml \
-	org.gnome.keyring.Prompt.xml
+	org.gnome.keyring.Prompter.xml
 
 gcr-dbus-generated.c: $(DBUS_XML_DEFINITIONS)
 	$(AM_V_GEN) gdbus-codegen --interface-prefix org.gnome.keyring.internal. \
diff --git a/gcr/gcr-dbus-constants.h b/gcr/gcr-dbus-constants.h
index 2d7468f..c08871e 100644
--- a/gcr/gcr-dbus-constants.h
+++ b/gcr/gcr-dbus-constants.h
@@ -49,10 +49,10 @@ G_BEGIN_DECLS
 #define GCR_DBUS_CALLBACK_METHOD_READY               "PromptReady"
 #define GCR_DBUS_CALLBACK_METHOD_DONE                "PromptDone"
 
-#define GCR_DBUS_PROMPT_TYPE_NONE                    ""
 #define GCR_DBUS_PROMPT_TYPE_PASSWORD                "password"
 #define GCR_DBUS_PROMPT_TYPE_CONFIRM                 "confirm"
 
+#define GCR_DBUS_PROMPT_REPLY_NONE                   ""
 #define GCR_DBUS_PROMPT_REPLY_YES                    "yes"
 #define GCR_DBUS_PROMPT_REPLY_NO                     "no"
 
diff --git a/gcr/gcr-system-prompt.c b/gcr/gcr-system-prompt.c
index b500fed..cae19a6 100644
--- a/gcr/gcr-system-prompt.c
+++ b/gcr/gcr-system-prompt.c
@@ -1022,7 +1022,8 @@ handle_last_response (GcrSystemPrompt *self)
 	if (g_str_equal (self->pv->last_response, GCR_DBUS_PROMPT_REPLY_YES)) {
 		response = GCR_PROMPT_REPLY_OK;
 
-	} else if (g_str_equal (self->pv->last_response, GCR_DBUS_PROMPT_REPLY_NO)) {
+	} else if (g_str_equal (self->pv->last_response, GCR_DBUS_PROMPT_REPLY_NO) ||
+	           g_str_equal (self->pv->last_response, GCR_DBUS_PROMPT_REPLY_NONE)) {
 		response = GCR_PROMPT_REPLY_CANCEL;
 
 	} else {
diff --git a/gcr/gcr-system-prompter.c b/gcr/gcr-system-prompter.c
index 034b918..2be9040 100644
--- a/gcr/gcr-system-prompter.c
+++ b/gcr/gcr-system-prompter.c
@@ -579,7 +579,7 @@ prompt_next_ready (GcrSystemPrompter *self)
 	g_assert (active == NULL);
 
 	active = active_prompt_create (self, callback);
-	prompt_send_ready (active, GCR_DBUS_PROMPT_REPLY_YES, NULL);
+	prompt_send_ready (active, GCR_DBUS_PROMPT_REPLY_NONE, NULL);
 }
 
 static void
diff --git a/gcr/org.gnome.keyring.Prompter.xml b/gcr/org.gnome.keyring.Prompter.xml
index 189b0f6..5e68ed8 100644
--- a/gcr/org.gnome.keyring.Prompter.xml
+++ b/gcr/org.gnome.keyring.Prompter.xml
@@ -2,29 +2,84 @@
  "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd";>
 
 <node>
+	<!-- 
+	 * WARNING: This is an internal interface, and not a public API. It
+	 * can change between releases.
+	 *
+	 * This can be viewed as an interface for remoting the GcrPrompt
+	 * interface.
+	 *
+	 * We use a callback interface exported from the prompting client.
+	 * The prompter calls this rather than emit signals. It does this so
+	 * that the prompter can be aware if the client returns errors or is
+	 * no longer around.
+	-->
+
 	<interface name="org.gnome.keyring.internal.Prompter">
+		<!-- 
+		 * Prompts first call BeginPrompting() with the path that. This
+		 * returns immediately. The prompter then calls PromptReady()
+		 * on the callback when it's ready for that client prompt to
+		 * start showing prompts.
+		-->
 		<method name="BeginPrompting">
+			<!-- DBus path to the client prompt callback -->
 			<arg name="callback" type="o" direction="in"/>
 		</method>
+
+		<!--
+		 * Called by client prompts to actually show a prompt. This can
+		 * only be called after the prompter calls PromptReady() on
+		 * the callback.
+		 *
+		 * This returns immediately, and PromptReady() will be called
+		 * on the callback when the prompt completes.
+		-->
 		<method name="PerformPrompt">
+			<!-- DBus path to the client prompt callback -->
 			<arg name="callback" type="o" direction="in"/>
+
+			<!-- Type of prompt: 'password' or 'confirm' -->
 			<arg name="type" type="s" direction="in"/>
+
+			<!-- GcrPrompt properties which changed since last prompt -->
 			<arg name="properties" type="a{sv}" direction="in"/>
+
+			<!-- GcrSecretExchange output from client -->
 			<arg name="exchange" type="s" direction="in"/>
 		</method>
+
+		<!--
+		 * Called by client prompts to stop prompting. If a prompt is
+		 * currently being displayed then it will be cancelled as if
+		 * the user cancelled it.
+		 *
+		 * Will call PromptDone() on the client callback.
+		-->
 		<method name="StopPrompting">
+			<!-- DBus path to the client prompt callback -->
 			<arg name="callback" type="o" direction="in"/>
 		</method>
 	</interface>
 
 	<!-- Called when ready to prompt or a prompt completes -->
 	<interface name="org.gnome.keyring.internal.Prompter.Callback">
+
+		<!--
+		 * Called by the prompter when ready to show a prompt. This
+		 * occurs when the prompter is ready for the first prompt,
+		 * and also after prompts complete.
+		-->
 		<method name="PromptReady">
 			<arg name="reply" type="s" direction="in"/>
 			<arg name="properties" type="a{sv}" direction="in"/>
 			<arg name="exchange" type="s" direction="in"/>
 		</method>
-		<method name="PromptClose">
+
+		<!--
+		 * Called when the prompter stops prompting for this callback
+		-->
+		<method name="PromptDone">
 		</method>
 	</interface>
 </node>