[gnome-keyring/dbus-api] API changes: add error codes, add Created Modified properties.

[Stefan Walter <stefw src gnome org>]

commit bc00dc5f6d1fc9d02f74a510a252827b25c7c894
Author: Stef Walter <stef memberwebs com>
Date:   Sun Jun 21 04:57:05 2009 +0000

    API changes: add error codes, add Created Modified properties.
    
    A bunch of API changes that fixed names, property orders,
    and added the missing Created/Modified properties for
    collections and items.
    
    Also added error codes and documented them.

 .../api/org.freedesktop.Secrets.Collection.xml     |   20 ++++++++++++++------
 .../secrets/api/org.freedesktop.Secrets.Item.xml   |   12 ++++++++++--
 .../api/org.freedesktop.Secrets.Service.xml        |   18 ++++++++++++++++++
 docs/reference/secrets/secrets-docs.sgml           |   17 +++++++++++------
 4 files changed, 53 insertions(+), 14 deletions(-)
---
diff --git a/daemon/secrets/api/org.freedesktop.Secrets.Collection.xml b/daemon/secrets/api/org.freedesktop.Secrets.Collection.xml
index 24381b4..6a43540 100644
--- a/daemon/secrets/api/org.freedesktop.Secrets.Collection.xml
+++ b/daemon/secrets/api/org.freedesktop.Secrets.Collection.xml
@@ -7,6 +7,14 @@
 		<annotation value="Collection of items" name="org.gtk.EggDBus.DocString.Summary"/>
 		<annotation value="A collection of items containing secrets." name="org.gtk.EggDBus.DocString"/>
 
+		<property name="Items" type="ao" access="read">
+			<annotation value="Items in this collection." name="org.gtk.EggDBus.DocString"/>
+		</property>
+		
+		<property name="Private" type="s" access="read">
+			<annotation value="Whether this is a private collection or not." name="org.gtk.EggDBus.DocString"/>
+		</property>
+
 		<property name="Label" type="s" access="readwrite">
 			<annotation value="The displayable label of this collection." name="org.gtk.EggDBus.DocString"/>
 		</property>
@@ -15,18 +23,18 @@
 			<annotation value="Whether the collection is locked and must be authenticated by the client application." name="org.gtk.EggDBus.DocString"/>
 		</property>
 		
-		<property name="Private" type="s" access="read">
-			<annotation value="Whether this is a private collection or not." name="org.gtk.EggDBus.DocString"/>
+		<property name="Created" type="t" access="read">
+			<annotation value="The unix time when the collection was created." name="org.gtk.EggDBus.DocString"/>
 		</property>
 
+		<property name="Modified" type="t" access="read">
+			<annotation value="The unix time when the collection was last modified." name="org.gtk.EggDBus.DocString"/>
+		</property>
+				
 		<method name="Delete">
 			<annotation value="Delete this collection." name="org.gtk.EggDBus.DocString"/>
 		</method>
 		
-		<property name="Items" type="ao" access="read">
-			<annotation value="Items in this collection." name="org.gtk.EggDBus.DocString"/>
-		</property>
-
 		<method name="SearchItems">
 			<annotation value="Search for items in this collection matching the lookup fields." name="org.gtk.EggDBus.DocString"/>
 			<arg name="fields" type="a{ss}" direction="in">
diff --git a/daemon/secrets/api/org.freedesktop.Secrets.Item.xml b/daemon/secrets/api/org.freedesktop.Secrets.Item.xml
index 6cc372d..ccc905d 100644
--- a/daemon/secrets/api/org.freedesktop.Secrets.Item.xml
+++ b/daemon/secrets/api/org.freedesktop.Secrets.Item.xml
@@ -33,8 +33,8 @@
 			<annotation value="Whether the item is locked and requires authentication, or not." name="org.gtk.EggDBus.DocString"/>
 		</property>
 
-		<property name="Fields" type="a{ss}" access="readwrite">
-			<annotation value="The lookup fields for this item." name="org.gtk.EggDBus.DocString"/>
+		<property name="Attributes" type="a{ss}" access="readwrite">
+			<annotation value="The lookup attributes for this item." name="org.gtk.EggDBus.DocString"/>
 		</property>
 
 		<property name="Label" type="s" access="readwrite">
@@ -46,6 +46,14 @@
 			<annotation value="Secret" name="org.gtk.EggDBus.Type"/>
 		</property>
 		
+		<property name="Created" type="t" access="read">
+			<annotation value="The unix time when the item was created." name="org.gtk.EggDBus.DocString"/>
+		</property>
+
+		<property name="Modified" type="t" access="read">
+			<annotation value="The unix time when the item was last modified." name="org.gtk.EggDBus.DocString"/>
+		</property>
+		
 		<method name="Delete">
 			<annotation value="Delete this item." name="org.gtk.EggDBus.DocString"/>
 		</method>
diff --git a/daemon/secrets/api/org.freedesktop.Secrets.Service.xml b/daemon/secrets/api/org.freedesktop.Secrets.Service.xml
index 9dc2188..8ab1b38 100644
--- a/daemon/secrets/api/org.freedesktop.Secrets.Service.xml
+++ b/daemon/secrets/api/org.freedesktop.Secrets.Service.xml
@@ -9,6 +9,24 @@
 
 <node name="/org/freedesktop/Secrets">
 
+	<annotation value="Error" name="org.gtk.EggDBus.DeclareErrorDomain">
+		<annotation value="Errors returned by the Secrets API." name="org.gtk.EggDBus.DocString"/>
+		<annotation name="org.gtk.EggDBus.DocString.Summary" value="Errors"/>
+		
+		<annotation value="org.freedesktop.Secrets.Error.AlreadyExists" name="org.gtk.EggDBus.ErrorDomain.Member">
+      			<annotation value="An object (session, collection) already exists with the same name." name="org.gtk.EggDBus.DocString"/>
+		</annotation>
+
+		<annotation value="org.freedesktop.Secrets.Error.IsLocked" name="org.gtk.EggDBus.ErrorDomain.Member">
+      			<annotation value="The object must be unlocked before this action can be carried out." name="org.gtk.EggDBus.DocString"/>
+		</annotation>
+
+		<annotation value="org.freedesktop.Secrets.Error.NotSupported" name="org.gtk.EggDBus.ErrorDomain.Member">
+      			<annotation value="The algorithm is not supported." name="org.gtk.EggDBus.DocString"/>
+		</annotation>
+
+	</annotation> 
+
 	<interface name="org.freedesktop.Secrets.Service">
 		<annotation value="Manages collections and sessions" name="org.gtk.EggDBus.DocString.Summary"/>
 		<annotation value="The Secrets service manages all the sessions and collections." name="org.gtk.EggDBus.DocString"/>
diff --git a/docs/reference/secrets/secrets-docs.sgml b/docs/reference/secrets/secrets-docs.sgml
index 27d09c5..c491b91 100644
--- a/docs/reference/secrets/secrets-docs.sgml
+++ b/docs/reference/secrets/secrets-docs.sgml
@@ -106,7 +106,9 @@
 			desire to modify a locked item, should <link linkend='authentication-unlocking'>unlock it before use</link>.</para>
 			
 			<para>The service must prevent locked collections or items from modification. On 
-			such an invalid access the [TODO: document error code] error should be raised.</para>
+			such an invalid access the 
+			<link linkend='eggdbus-constant-Error.org.freedesktop.Secrets.Error.IsLocked'>IsLocked</link>
+			 error should be raised.</para>
 			
 			<para>Client applications without special requirements should store in the default 
 			collection. Use the 
@@ -170,7 +172,9 @@
 			<link linkend='eggdbus-method-org.freedesktop.Secrets.Service.OpenSession'>OpenSession()</link>
 			method. Once established, a session is bound to calling application's connection to 
 			the DBus session bus. Generally only one session can be established per client 
-			application. Calling OpenSession() a second time results in an error [TODO: document error].</para>
+			application. Calling OpenSession() a second time results in an
+			<link linkend='eggdbus-constant-Error.org.freedesktop.Secrets.Error.AlreadyExists'>AlreadyExists</link>
+			error.</para>
 			 
 			<para>A session is closed when the client application disconnects from the DBus 
 			session bus. Alternatively the client application can call the
@@ -217,10 +221,10 @@
 				Negotiate() method specifies a set of algorithms to be used together for 
 				key agreement and encryption. The other arguments are algorithm specific.</para>
 				
-				<para>If a service does not support a specific set of algorithms, an error 
-				[TODO: Document the error code] is returned, and the client is free to try another 
-				set of algorithms. The <emphasis>PLAIN</emphasis> algorithm is almost always
-				supported.</para>
+				<para>If a service does not support a specific set of algorithms, a 
+				<link linkend='eggdbus-constant-Error.org.freedesktop.Secrets.Error.NotSupported'>NotSupported</link>
+				error is returned, and the client is free to try another set of algorithms. 
+				The <emphasis>PLAIN</emphasis> algorithm is almost always supported.</para>
 				
 				<para>An algorithm may require that the Negotiate() method is called multiple
 				times in succession to be complete. Each iteration transfers algorithm specific
@@ -387,6 +391,7 @@
 		<xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Service.xml"/>
 		<xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Session.xml"/>
 		<xi:include href="../../../daemon/secrets/api/docbook-struct-Secret.xml"/>
+		<xi:include href="../../../daemon/secrets/api/docbook-enum-Error.xml"/>
 	</part>
 
 <!--