From 3fca534d2f71febdf9f4d6399a7e1b610bac90f6 Mon Sep 17 00:00:00 2001
From: Stef Walter <stefw@collabora.co.uk>
Date: Tue, 1 Mar 2011 13:25:57 +0100
Subject: Allow specifying an alias in the CreateCollection() method.

This creates the collection with the given alias, or returns an already
existing collection in a race free manner.
---
 secret-service/org.freedesktop.Secrets.xml | 15 +++++++++++++++
 secret-service/specification.xml           | 24 ++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml
index 6a9e495..7d23c78 100644
--- a/secret-service/org.freedesktop.Secrets.xml
+++ b/secret-service/org.freedesktop.Secrets.xml
@@ -121,6 +121,21 @@ properties = { "Label": "MyCollection" }
                         </para>
                     </tp:docstring>
                 </arg>
+                <arg name="alias" type="s" direction="in">
+                    <tp:docstring xmlns:docbook="http://docbook.org/ns/docbook">
+                        <para>
+                            If creating this connection for a well known alias then a string like
+                            <literal>default</literal>. If an collection with this well-known alias already
+                            exists, then that collection will be returned instead of creating a new
+                            collection. Any readwrite properties provided to this function will be set on
+                            the collection.
+                        </para>
+                        <para>
+                            Set this to an empty string if the new collection should not be associated with a
+                            well known alias.
+                        </para>
+                    </tp:docstring>
+                </arg>
                 <arg name="collection" type="o" direction="out">
                     <tp:docstring>The new collection object, or '/' if prompting is necessary.</tp:docstring>
                 </arg>
diff --git a/secret-service/specification.xml b/secret-service/specification.xml
index 65045d6..a0a293b 100644
--- a/secret-service/specification.xml
+++ b/secret-service/specification.xml
@@ -157,7 +157,31 @@
 			information. In this case, a <link linkend='prompts'>prompt object</link> is returned. It
 			must be <link linkend='org.freedesktop.Secret.Prompt.Prompt'>acted upon</link> in order for
 			the collection to be deleted.</para>
+		</chapter>
 
+		<chapter xml:id="aliases">
+			<title>Aliases</title>
+
+			<para>Collections may be accessed via well known aliases. For example an alias
+			called <literal>default</literal> tells applications which is the default
+			collection to store secrets.</para>
+
+			<para>The aliased collections will be available at a
+			<link linkend='object-paths'>well-known DBus object path</link>.</para>
+
+			<para>If an application needs to create a collection with a given alias, this can
+			be done in a race free fashion by specifying the alias parameter of the
+			<link linkend='org.freedesktop.Secret.Service.CreateCollection'>CreateCollection()</link>
+			method on the service interface. If a collection with that alias already exists,
+			then it will be returned instead of creating a new one.</para>
+
+			<para>For applications like password managers it can be useful to allow the user to
+			configure which collection is associated with which well known alias. To alias or
+			unalias a collection use the
+			<link linkend='org.freedesktop.Secret.Service.SetAlias'>SetAlias()</link> method on the
+			service interface. Use the
+			<link linkend='org.freedesktop.Secret.Service.ReadAlias'>ReadAlias()</link> method on the
+			service interface to discover which collection is associated with a given alias.</para>
 		</chapter>
 
 		<chapter xml:id="lookup-attributes">
-- 
cgit v1.2.3-70-g09d2