api: update SecretAgent API with allowed errors for GetSecrets reply

1 files changed, 44 insertions, 2 deletions

diff --git a/introspection/nm-secret-agent.xml b/introspection/nm-secret-agent.xml
index 48dde703c5..fa85cb6c65 100644
--- a/introspection/nm-secret-agent.xml
+++ b/introspection/nm-secret-agent.xml
@@ -11,7 +11,8 @@
             itself and should not expect its SaveSecrets() method to be called.
             SaveSecrets() will be called eg if some program other than the
             agent itself (like a connection editor) changes the secrets out of
-            band.
+            band.  The agent should implement this D-Bus interface on an object
+            with the path /org/freedesktop/NetworkManager/SecretAgent.
         </tp:docstring>
 
         <method name="GetSecrets">
@@ -21,7 +22,9 @@
                 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.
+                secrets back to the same agent via a SaveSecrets() call.  If
+                the user canceled any interaction, the agent should return the
+                UserCanceled error (see below).
             </tp:docstring>
             <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_secret_agent_get_secrets"/>
             <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
@@ -75,6 +78,45 @@
                     the setting, and one or more secrets.
                 </tp:docstring>
             </arg>
+
+            <tp:possible-errors>
+              <tp:error name="org.freedesktop.NetworkManager.SecretAgent.NotAuthorized">
+                  <tp:docstring>
+                      Should be returned when the process requesting secrets is
+                      not authorized to do so (like if the caller is not root
+                      or not NetworkManager).
+                  </tp:docstring>
+              </tp:error>
+              <tp:error name="org.freedesktop.NetworkManager.SecretAgent.InvalidConnection">
+                  <tp:docstring>
+                      Should be returned if the 'connection' argument is invalid.
+                  </tp:docstring>
+              </tp:error>
+              <tp:error name="org.freedesktop.NetworkManager.SecretAgent.UserCanceled">
+                  <tp:docstring>
+                      Should be returned when the user has canceled the request.
+                  </tp:docstring>
+              </tp:error>
+              <tp:error name="org.freedesktop.NetworkManager.SecretAgent.AgentCanceled">
+                  <tp:docstring>
+                      Should be returned when NetworkManager has requested that
+                      the agent cancel the request.
+                  </tp:docstring>
+              </tp:error>
+              <tp:error name="org.freedesktop.NetworkManager.SecretAgent.InternalError">
+                  <tp:docstring>
+                      Should be returned if the agent has encountered some internal
+                      error processing the request.
+                  </tp:docstring>
+              </tp:error>
+              <tp:error name="org.freedesktop.NetworkManager.SecretAgent.NoSecrets">
+                  <tp:docstring>
+                      Should be returned if there are no available secrets, for
+                      example if user interaction is not allowed and there are
+                      no secrets stored by the agent for this connection.
+                  </tp:docstring>
+              </tp:error>
+            </tp:possible-errors>
         </method>
 
         <tp:flags name="NM_SECRET_AGENT_GET_SECRETS_FLAGS" value-prefix="NM_SECRET_AGENT_GET_SECRETS_FLAG" type="u">