[evolution-data-server/cursor-staging: 8/19] Adding D-Bus API for cursor related APIs

[Tristan Van Berkom <tvb src gnome org>]

commit 5a2a62da6fa0fa4c4baff5a6ebff84cd62892b80
Author: Tristan Van Berkom <tristanvb openismus com>
Date:   Mon May 20 16:08:35 2013 +0900

    Adding D-Bus API for cursor related APIs
    
      o org.freedesktop.locale1
    
        We generate a GDBus object to deal with the "org.freedesktop.locale1" interface
        on the system bus, specifically we are interested in system wide locale change
        notifications.
    
      o org.gnome.evolution.AddressBook
    
        Added the "Locale" property and added a method
        to create a cursor.
    
      o org.gnome.evolution.dataserver.AddressBookCursor
    
        The new D-Bus interface to interact with cursors.

 private/Makefile.am                                |   32 ++++++
 private/org.freedesktop.locale1.xml                |   17 ++++
 .../org.gnome.evolution.dataserver.AddressBook.xml |    8 ++
 ...nome.evolution.dataserver.AddressBookCursor.xml |  100 ++++++++++++++++++++
 4 files changed, 157 insertions(+), 0 deletions(-)
---
diff --git a/private/Makefile.am b/private/Makefile.am
index 8a834c8..f8c2ccf 100644
--- a/private/Makefile.am
+++ b/private/Makefile.am
@@ -1,5 +1,13 @@
 NULL =
 
+$(GENERATED_DBUS_LOCALE) : Makefile.am org.freedesktop.locale1.xml
+       $(AM_V_GEN) gdbus-codegen \
+       --interface-prefix org.freedesktop. \
+       --c-namespace E_DBus \
+       --generate-c-code e-dbus-localed \
+       $(top_srcdir)/private/org.freedesktop.locale1.xml \
+       $(NULL)
+
 $(GENERATED_DBUS_SOURCE) : Makefile.am org.gnome.evolution.dataserver.Source.xml
        $(AM_V_GEN) gdbus-codegen \
        --interface-prefix org.gnome.evolution.dataserver. \
@@ -37,6 +45,15 @@ $(GENERATED_DBUS_ADDRESS_BOOK) : Makefile.am org.gnome.evolution.dataserver.Addr
        $(top_srcdir)/private/org.gnome.evolution.dataserver.AddressBook.xml \
        $(NULL)
 
+$(GENERATED_DBUS_ADDRESS_BOOK_CURSOR) : Makefile.am org.gnome.evolution.dataserver.AddressBookCursor.xml
+       $(AM_V_GEN) gdbus-codegen \
+       --interface-prefix org.gnome.evolution.dataserver \
+       --c-namespace E_DBus \
+       --generate-c-code e-dbus-address-book-cursor \
+       --generate-docbook e-dbus-address-book-cursor \
+       $(top_srcdir)/private/org.gnome.evolution.dataserver.AddressBookCursor.xml \
+       $(NULL)
+
 $(GENERATED_DBUS_DIRECT_BOOK) : Makefile.am org.gnome.evolution.dataserver.DirectBook.xml
        $(AM_V_GEN) gdbus-codegen \
        --interface-prefix org.gnome.evolution.dataserver \
@@ -82,6 +99,11 @@ $(GENERATED_DBUS_USER_PROMPTER) : Makefile.am org.gnome.evolution.dataserver.Use
        $(top_srcdir)/private/org.gnome.evolution.dataserver.UserPrompter.xml \
        $(NULL)
 
+GENERATED_DBUS_LOCALE = \
+       e-dbus-localed.c \
+       e-dbus-localed.h \
+       $(NULL)
+
 GENERATED_DBUS_SOURCE = \
        e-dbus-source.c \
        e-dbus-source.h \
@@ -117,6 +139,12 @@ GENERATED_DBUS_ADDRESS_BOOK = \
        e-dbus-address-book-org.gnome.evolution.dataserver.AddressBook.xml \
        $(NULL)
 
+GENERATED_DBUS_ADDRESS_BOOK_CURSOR = \
+       e-dbus-address-book-cursor.c \
+       e-dbus-address-book-cursor.h \
+       e-dbus-address-book-cursor-org.gnome.evolution.dataserver.AddressBookCursor.xml \
+       $(NULL)
+
 GENERATED_DBUS_DIRECT_BOOK = \
        e-dbus-direct-book.c \
        e-dbus-direct-book.h \
@@ -142,10 +170,12 @@ GENERATED_DBUS_CALENDAR_FACTORY = \
        $(NULL)
 
 BUILT_SOURCES = \
+       $(GENERATED_DBUS_LOCALE) \
        $(GENERATED_DBUS_SOURCE) \
        $(GENERATED_DBUS_SOURCE_MANAGER) \
        $(GENERATED_DBUS_AUTHENTICATOR) \
        $(GENERATED_DBUS_ADDRESS_BOOK) \
+       $(GENERATED_DBUS_ADDRESS_BOOK_CURSOR) \
        $(GENERATED_DBUS_DIRECT_BOOK) \
        $(GENERATED_DBUS_ADDRESS_BOOK_FACTORY) \
        $(GENERATED_DBUS_CALENDAR) \
@@ -183,10 +213,12 @@ libedbus_private_la_LDFLAGS = \
        $(NULL)
 
 EXTRA_DIST = \
+       org.freedesktop.locale1.xml     \
        org.gnome.evolution.dataserver.Source.xml \
        org.gnome.evolution.dataserver.SourceManager.xml \
        org.gnome.evolution.dataserver.Authenticator.xml \
        org.gnome.evolution.dataserver.AddressBook.xml \
+       org.gnome.evolution.dataserver.AddressBookCursor.xml \
        org.gnome.evolution.dataserver.DirectBook.xml \
        org.gnome.evolution.dataserver.AddressBookFactory.xml \
        org.gnome.evolution.dataserver.Calendar.xml \
diff --git a/private/org.freedesktop.locale1.xml b/private/org.freedesktop.locale1.xml
new file mode 100644
index 0000000..d415e43
--- /dev/null
+++ b/private/org.freedesktop.locale1.xml
@@ -0,0 +1,17 @@
+<!DOCTYPE node PUBLIC
+"-//freedesktop//DTD D-Bus Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd";>
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd";>
+
+  <!--
+      Here we generate a proxy to handle the 'localed' system entity,
+      we only generate the 'Locale' property as that's all we're interested in.
+      the object should be present at the path '/org/freedesktop/locale1'
+
+      See: http://www.freedesktop.org/wiki/Software/systemd/localed
+  -->
+<interface name="org.freedesktop.locale1">
+
+  <property name="Locale" type="as" access="read"/>
+
+</interface>
diff --git a/private/org.gnome.evolution.dataserver.AddressBook.xml 
b/private/org.gnome.evolution.dataserver.AddressBook.xml
index bc60632..60a15d1 100644
--- a/private/org.gnome.evolution.dataserver.AddressBook.xml
+++ b/private/org.gnome.evolution.dataserver.AddressBook.xml
@@ -14,6 +14,7 @@
 
   <property name="Online" type="b" access="read"/>
   <property name="Revision" type="s" access="read"/>
+  <property name="Locale" type="s" access="read"/>
   <property name="Writable" type="b" access="read"/>
 
   <!-- These properties are static. -->
@@ -66,4 +67,11 @@
     <arg name="object_path" direction="out" type="o"/>
   </method>
 
+  <method name="GetCursor">
+    <arg name="query" direction="in" type="s"/>
+    <arg name="sort_keys" direction="in" type="as"/>
+    <arg name="sort_types" direction="in" type="as"/>
+    <arg name="object_path" direction="out" type="o"/>
+  </method>
+
 </interface>
diff --git a/private/org.gnome.evolution.dataserver.AddressBookCursor.xml 
b/private/org.gnome.evolution.dataserver.AddressBookCursor.xml
new file mode 100644
index 0000000..ad60cc4
--- /dev/null
+++ b/private/org.gnome.evolution.dataserver.AddressBookCursor.xml
@@ -0,0 +1,100 @@
+<!DOCTYPE node PUBLIC
+"-//freedesktop//DTD D-Bus Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd";>
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd";>
+
+<!--
+    org.gnome.evolution.dataserver.AddressBookCursor:
+    @short_description: Address book cursor objects
+    @since: 3.10
+
+    This interface allows for interaction with an address book cursor backend.
+-->
+<interface name="org.gnome.evolution.dataserver.AddressBookCursor">
+
+  <!--
+      Total:
+
+      The total number of contacts for this cursor query
+  -->
+  <property name="Total" type="u" access="read"/>
+
+  <!--
+      Position:
+
+      The current cursor position in the cursor query
+  -->
+  <property name="Position" type="u" access="read"/>
+
+  <!--
+      Step:
+      @revision_guard: The expected revision of the addressbook
+      @flags: The #EBookCursorStepFlags
+      @origin: The #EBookCursorOrigin
+      @count: The number of contacts to try and fetch, negative values step the cursor in reverse
+      @n_results: The number contacts actually traversed in this step.
+      @vcards: The returned contact list
+      @new_total: The total amount of contacts after moving the cursor
+      @new_position: The cursor position after moving
+
+      Step the cursor by @count contacts from @origin
+
+      This will also result in changes of the Position and Total properties
+
+      The @revision_guard will be checked against the current addressbook
+      revision, if the revisions differ then %E_CLIENT_ERROR_OUT_OF_SYNC
+      will be reported.
+  -->
+  <method name="Step">
+    <arg name="revision_guard" direction="in" type="s"/>
+    <arg name="flags" direction="in" type="i"/>
+    <arg name="origin" direction="in" type="i"/>
+    <arg name="count" direction="in" type="i"/>
+    <arg name="n_results" direction="out" type="i"/>
+    <arg name="vcards" direction="out" type="as"/>
+    <arg name="new_total" direction="out" type="u"/>
+    <arg name="new_position" direction="out" type="u"/>
+  </method>
+
+  <!--
+      SetAlphabeticIndex:
+      @index: The alphabetic index to set
+      @locale: The locale for which @index is known to be valid
+
+      Sets the cursor's alphabetic index, the index must be valid for @locale
+      and @locale is expected to be the current locale of the addressbook.
+
+      If the addressbook's locale has changed and doesnt match the @locale
+      argument then an error will be returned and the call should be retried.
+
+      This will also result in changes of the Position and Total properties
+  -->
+  <method name="SetAlphabeticIndex">
+    <arg name="index" direction="in" type="u"/>
+    <arg name="locale" direction="in" type="s"/>
+    <arg name="new_total" direction="out" type="u"/>
+    <arg name="new_position" direction="out" type="u"/>
+  </method>
+
+  <!--
+      SetQuery:
+      @query: The new query for this cursor
+
+      Changes the query for the given cursor
+
+      This will also result in changes of the Position and Total properties
+  -->
+  <method name="SetQuery">
+    <arg name="query" direction="in" type="s"/>
+    <arg name="new_total" direction="out" type="u"/>
+    <arg name="new_position" direction="out" type="u"/>
+  </method>
+
+  <!--
+      Dispose
+
+      Delete the server side resources for this cursor
+  -->
+  <method name="Dispose"/>
+
+</interface>