From a4256940da049f91bbbea5e53e469a59ea9c10f7 Mon Sep 17 00:00:00 2001
From: Sjoerd Simons <sjoerd@luon.net>
Date: Fri, 25 Oct 2013 21:20:58 +0200
Subject: Imported Upstream version 0.9.8.8

---
 introspection/nm-secret-agent.xml | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

(limited to 'introspection/nm-secret-agent.xml')

diff --git a/introspection/nm-secret-agent.xml b/introspection/nm-secret-agent.xml
index 81a1321b..48dde703 100644
--- a/introspection/nm-secret-agent.xml
+++ b/introspection/nm-secret-agent.xml
@@ -17,7 +17,11 @@
         <method name="GetSecrets">
             <tp:docstring>
                 Retrieve and return stored secrets, if any, or request new
-                secrets from the agent's user.
+                secrets from the agent's user.  If user interaction is allowed
+                and the user enters new secrets, the agent is expected to save
+                the new secrets to persistent storage (if the secret's flags
+                include AGENT_OWNED) as NetworkManager will not send these
+                secrets back to the same agent via a SaveSecrets() call.
             </tp:docstring>
             <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_get_secrets"/>
             <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
@@ -46,7 +50,9 @@
                     Array of strings of key names in the requested setting for
                     which NetworkManager thinks a secrets may be required,
                     and/or well-known identifiers and data that may be useful
-                    to the client in processing the secrets request. The Agent
+                    to the client in processing the secrets request.  Note that
+                    it's not always possible to determine which secret is
+                    required, so in some cases no hints may be given.  The Agent
                     should return any secrets it has, or that it thinks are
                     required, regardless of what hints NetworkManager sends
                     in this request.
@@ -109,14 +115,17 @@
         <method name="CancelGetSecrets">
             <tp:docstring>
                 Cancel a pending GetSecrets request for secrets of the given
-                connection.  Any matching request should be canceled.
+                connection.  Any GetSecrets request with the same
+                'connection_path' and 'setting_name' that are given in a
+                CancelGetSecrets request should be canceled.
             </tp:docstring>
             <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_cancel_get_secrets"/>
             <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
             <arg name="connection_path" type="o" direction="in">
                 <tp:docstring>
-                    Object path of the connection for which, if secrets are being
-                    requested, the request should be canceled.
+                    Object path of the connection for which, if secrets for
+                    the given 'setting_name' are being requested, the request
+                    should be canceled.
                 </tp:docstring>
             </arg>
             <arg name="setting_name" type="s" direction="in">
-- 
cgit 1.3.0-6-gf8a5