GNOME.org
 

[evolution-data-server] Added documentation for new Direct Read Access related apis.

commit 66def2367245febd0d5bbd3378c022a203b48b78
Author: Tristan Van Berkom <tristanvb openismus com>
Date:   Mon Feb 18 19:05:56 2013 +0900

    Added documentation for new Direct Read Access related apis.
    
    Also fixed up gtk-doc build for libedata-book to add EDataBookDirect
    to the sections, types and libedata-book-docs.sgml files.

 addressbook/libedata-book/e-data-book.c            |  229 +++++++++++++++++++-
 .../libedata-book/libedata-book-docs.sgml          |    1 +
 .../libedata-book/libedata-book-sections.txt       |   34 +++
 .../addressbook/libedata-book/libedata-book.types  |    1 +
 4 files changed, 264 insertions(+), 1 deletions(-)
---
diff --git a/addressbook/libedata-book/e-data-book.c b/addressbook/libedata-book/e-data-book.c
index 90da454..ee7879c 100644
--- a/addressbook/libedata-book/e-data-book.c
+++ b/addressbook/libedata-book/e-data-book.c
@@ -2157,6 +2157,27 @@ e_data_book_new (EBookBackend *backend,
                NULL);
 }
 
+/**
+ * e_data_book_new_direct:
+ * @registry: The #ESourceRegistry
+ * @source: The #ESource to create a book for
+ * @backend_path: The full path to the backend module to use
+ * @backend_name: The #EDataFactory type name to use from the module specified by @backend_path
+ * @config: The backend specific configuration string specified by the #EDataBookDirect
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Creates an #EDataBook for Direct Read Access, the @backend_path, @backend_name and @config
+ * parameters are fetched from an #EDataBookDirect reported over D-Bus from the server side
+ * counter part of a given backend.
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Returns: (transfer full): A newly created #EDataBook for direct read access,
+ *          otherwise %NULL is returned and @error is set.
+ *
+ * Since: 3.8
+ */
 EDataBook *
 e_data_book_new_direct (ESourceRegistry *registry,
                        ESource         *source,
@@ -2308,6 +2329,21 @@ e_data_book_open_finish (EDataBook *book,
        return res;
 }
 
+/**
+ * e_data_book_open_sync:
+ * @book: an #EDataBook
+ * @cancellable: (allow-none): optional #GCancellable object, or %NULL
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Opens the #EDataBook and it's backend.
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Returns: %TRUE on success. If %FALSE is returned, @error will be set
+ *
+ * Since: 3.8
+ */
 gboolean
 e_data_book_open_sync (EDataBook *book,
                       GCancellable *cancellable,
@@ -2366,6 +2402,21 @@ e_data_book_respond_close (EDataBook *book,
                g_error_free (error);
 }
 
+/**
+ * e_data_book_close:
+ * @book: an #EDataBook
+ * @cancellable: (allow-none): optional #GCancellable object, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback to call when the request
+ *            is satisfied
+ * @user_data: (closure): data to pass to @callback
+ *
+ * Closes the @book and its backend.
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Since: 3.8
+ */
 void
 e_data_book_close (EDataBook *book,
                   GCancellable *cancellable,
@@ -2382,6 +2433,19 @@ e_data_book_close (EDataBook *book,
        e_operation_pool_push (ops_pool, op);
 }
 
+/**
+ * e_data_book_close_finish:
+ * @book: an #EDataBook
+ * @result: a #GAsyncResult
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Finishes the operation started with e_data_book_close().  If an
+ * error occurs, then this function sets @error and returns %FALSE.
+ *
+ * Returns: %TRUE on success
+ *
+ * Since: 3.8
+ */
 gboolean
 e_data_book_close_finish (EDataBook *book,
                          GAsyncResult *result,
@@ -2398,6 +2462,21 @@ e_data_book_close_finish (EDataBook *book,
        return res;
 }
 
+/**
+ * e_data_book_close_sync:
+ * @book: an #EDataBook
+ * @cancellable: (allow-none): optional #GCancellable object, or %NULL
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Closes the @book and its backend.
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Returns: %TRUE on success. If %FALSE is returned, @error will be set
+ *
+ * Since: 3.8
+ */
 gboolean
 e_data_book_close_sync (EDataBook *book,
                        GCancellable *cancellable,
@@ -2421,6 +2500,24 @@ e_data_book_close_sync (EDataBook *book,
        return result;
 }
 
+/**
+ * e_data_book_get_contact:
+ * @book: an #EDataBook
+ * @uid: a unique string ID specifying the contact
+ * @cancellable: (allow-none): optional #GCancellable object, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback to call when the request
+ *            is satisfied
+ * @user_data: (closure): data to pass to @callback
+ *
+ * Retrieves #EContact from the @book for the gived @uid.
+ * The call is finished by e_data_book_get_contact_finish()
+ * from the @callback.
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Since: 3.8
+ */
 void
 e_data_book_get_contact (EDataBook *book,
                         const gchar *uid,
@@ -2439,6 +2536,20 @@ e_data_book_get_contact (EDataBook *book,
        op_dispatch (book, op);
 }
 
+/**
+ * e_data_book_get_contact_finish:
+ * @book: an #EDataBook
+ * @result: a #GAsyncResult
+ * @contact: return location for the fetched #EContact
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Finishes the operation started with e_data_book_get_contact().  If an
+ * error occurs, then this function sets @error and returns %FALSE.
+ *
+ * Returns: %TRUE on success
+ *
+ * Since: 3.8
+ */
 gboolean
 e_data_book_get_contact_finish (EDataBook *book,
                                GAsyncResult *result,
@@ -2463,6 +2574,23 @@ e_data_book_get_contact_finish (EDataBook *book,
        return ret_contact != NULL;
 }
 
+/**
+ * e_data_book_get_contact_sync:
+ * @book: an #EDataBook
+ * @uid: a unique string ID specifying the contact
+ * @contact: return location for the fetched #EContact
+ * @cancellable: (allow-none): optional #GCancellable object, or %NULL
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Retrieves an #EContact from the @book for the gived @uid.
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Returns: %TRUE on success. If %FALSE is returned, @error will be set
+ *
+ * Since: 3.8
+ */
 gboolean
 e_data_book_get_contact_sync (EDataBook *book,
                              const gchar *uid,
@@ -2489,6 +2617,24 @@ e_data_book_get_contact_sync (EDataBook *book,
        return result;
 }
 
+/**
+ * e_data_book_get_contacts:
+ * @book: an #EDataBook
+ * @sexp: an S-expression representing the query
+ * @cancellable: (allow-none): optional #GCancellable object, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback to call when the request
+ *            is satisfied
+ * @user_data: (closure): data to pass to @callback
+ *
+ * Query @book with @sexp, receiving a list of contacts which
+ * matched. The call is finished by e_data_book_get_contacts_finish()
+ * from the @callback.
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Since: 3.8
+ */
 void
 e_data_book_get_contacts (EDataBook *book,
                          const gchar *sexp,
@@ -2506,6 +2652,20 @@ e_data_book_get_contacts (EDataBook *book,
        op_dispatch (book, op);
 }
 
+/**
+ * e_data_book_get_contacts_finish:
+ * @book: an #EDataBook
+ * @result: a #GAsyncResult
+ * @contacts: (element-type EContact) (out): a #GSList of matched #EContacts
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Finishes the operation started with e_data_book_get_contacts(). If an
+ * error occurs, then this function sets @error and returns %FALSE.
+ *
+ * Returns: %TRUE on success
+ *
+ * Since: 3.8
+ */
 gboolean
 e_data_book_get_contacts_finish (EDataBook *book,
                                 GAsyncResult *result,
@@ -2533,6 +2693,24 @@ e_data_book_get_contacts_finish (EDataBook *book,
        return TRUE;
 }
 
+/**
+ * e_data_book_get_contacts_sync:
+ * @book: an #EDataBook
+ * @sexp: an S-expression representing the query
+ * @contacts: (element-type EContact) (out): a #GSList of matched #EContacts
+ * @cancellable: (allow-none): optional #GCancellable object, or %NULL
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Query @book with @sexp, receiving a list of contacts which
+ * matched.
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Returns: %TRUE on success. If %FALSE is returned, @error will be set
+ *
+ * Since: 3.8
+ */
 gboolean
 e_data_book_get_contacts_sync (EDataBook *book,
                               const gchar *sexp,
@@ -2558,6 +2736,24 @@ e_data_book_get_contacts_sync (EDataBook *book,
        return result;
 }
 
+/**
+ * e_data_book_get_contacts_uids:
+ * @book: an #EDataBook
+ * @sexp: an S-expression representing the query
+ * @cancellable: (allow-none): optional #GCancellable object, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback to call when the request
+ *            is satisfied
+ * @user_data: (closure): data to pass to @callback
+ *
+ * Query @book with @sexp, receiving a list of contacts UIDs which
+ * matched. The call is finished by e_data_book_get_contacts_uids_finish()
+ * from the @callback.
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Since: 3.8
+ */
 void
 e_data_book_get_contacts_uids (EDataBook *book,
                               const gchar *sexp,
@@ -2575,6 +2771,20 @@ e_data_book_get_contacts_uids (EDataBook *book,
        op_dispatch (book, op);
 }
 
+/**
+ * e_data_book_get_contacts_uids_finish:
+ * @book: an #EDataBook
+ * @result: a #GAsyncResult
+ * @contacts_uids: (element-type utf8) (out): a #GSList of matched contact UIDs stored as strings
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Finishes the operation started with e_data_book_get_contacts_uids(). If an
+ * error occurs, then this function sets @error and returns %FALSE.
+ *
+ * Returns: %TRUE on success
+ *
+ * Since: 3.8
+ */
 gboolean
 e_data_book_get_contacts_uids_finish (EDataBook *book,
                                      GAsyncResult *result,
@@ -2602,6 +2812,24 @@ e_data_book_get_contacts_uids_finish (EDataBook *book,
        return TRUE;
 }
 
+/**
+ * e_data_book_get_contacts_uids_sync:
+ * @book: an #EDataBook
+ * @sexp: an S-expression representing the query
+ * @contacts_uids: (element-type utf8) (out): a #GSList of matched contact UIDs stored as strings
+ * @cancellable: (allow-none): optional #GCancellable object, or %NULL
+ * @error: (allow-none): return location for a #GError, or %NULL
+ *
+ * Query @book with @sexp, receiving a list of contacts UIDs which
+ * matched. 
+ *
+ * <note><para>This API is intended for internal use only, if you want client side
+ * direct read access then use e_book_client_connect_direct_sync() instead</para></note>
+ *
+ * Returns: %TRUE on success. If %FALSE is returned, @error will be set
+ *
+ * Since: 3.8
+ */
 gboolean
 e_data_book_get_contacts_uids_sync (EDataBook *book,
                                    const gchar *sexp,
@@ -2626,4 +2854,3 @@ e_data_book_get_contacts_uids_sync (EDataBook *book,
 
        return result;
 }
-
diff --git a/docs/reference/addressbook/libedata-book/libedata-book-docs.sgml 
b/docs/reference/addressbook/libedata-book/libedata-book-docs.sgml
index 5f5f9db..88aac6b 100644
--- a/docs/reference/addressbook/libedata-book/libedata-book-docs.sgml
+++ b/docs/reference/addressbook/libedata-book/libedata-book-docs.sgml
@@ -19,6 +19,7 @@
     <xi:include href="xml/e-book-backend-summary.xml"/>
     <xi:include href="xml/e-book-backend-sync.xml"/>
     <xi:include href="xml/e-data-book.xml"/>
+    <xi:include href="xml/e-data-book-direct.xml"/>
     <xi:include href="xml/e-data-book-factory.xml"/>
     <xi:include href="xml/e-data-book-view.xml"/>
     <xi:include href="xml/ximian-vcard.xml"/>
diff --git a/docs/reference/addressbook/libedata-book/libedata-book-sections.txt 
b/docs/reference/addressbook/libedata-book/libedata-book-sections.txt
index 854a7a9..2561c98 100644
--- a/docs/reference/addressbook/libedata-book/libedata-book-sections.txt
+++ b/docs/reference/addressbook/libedata-book/libedata-book-sections.txt
@@ -40,6 +40,8 @@ e_book_backend_notify_error
 e_book_backend_notify_property_changed
 e_book_backend_sync
 e_book_backend_set_is_removed
+e_book_backend_get_direct_book
+e_book_backend_configure_direct
 <SUBSECTION Deprecated>
 CLIENT_BACKEND_PROPERTY_OPENED
 CLIENT_BACKEND_PROPERTY_OPENING
@@ -283,6 +285,20 @@ e_data_book_respond_get_contact_list_uids
 e_data_book_report_error
 e_data_book_report_backend_property_changed
 e_data_book_string_slist_to_comma_string
+e_data_book_new_direct
+e_data_book_open_sync
+e_data_book_close
+e_data_book_close_finish
+e_data_book_close_sync
+e_data_book_get_contact
+e_data_book_get_contact_finish
+e_data_book_get_contact_sync
+e_data_book_get_contacts
+e_data_book_get_contacts_finish
+e_data_book_get_contacts_sync
+e_data_book_get_contacts_uids
+e_data_book_get_contacts_uids_finish
+e_data_book_get_contacts_uids_sync
 <SUBSECTION Deprecated>
 e_data_book_respond_set_backend_property
 e_data_book_report_opened
@@ -309,6 +325,24 @@ e_data_book_error_quark
 </SECTION>
 
 <SECTION>
+<FILE>e-data-book-direct</FILE>
+<TITLE>EDataBookDirect</TITLE>
+EDataBookDirect
+EDataBookDirectClass
+e_data_book_direct_new
+e_data_book_direct_register_gdbus_object
+<SUBSECTION Standard>
+EDataBookDirectPrivate
+E_DATA_BOOK_DIRECT
+E_DATA_BOOK_DIRECT_CLASS
+E_DATA_BOOK_DIRECT_GET_CLASS
+E_IS_DATA_BOOK_DIRECT
+E_IS_DATA_BOOK_DIRECT_CLASS
+E_TYPE_DATA_BOOK_DIRECT
+e_data_book_direct_get_type
+</SECTION>
+
+<SECTION>
 <FILE>e-data-book-factory</FILE>
 <TITLE>EDataBookFactory</TITLE>
 EDS_ADDRESS_BOOK_MODULES
diff --git a/docs/reference/addressbook/libedata-book/libedata-book.types 
b/docs/reference/addressbook/libedata-book/libedata-book.types
index 1d821ba..b9949ae 100644
--- a/docs/reference/addressbook/libedata-book/libedata-book.types
+++ b/docs/reference/addressbook/libedata-book/libedata-book.types
@@ -7,4 +7,5 @@ e_book_backend_sexp_get_type
 e_book_backend_summary_get_type
 e_book_backend_sync_get_type
 e_data_book_get_type
+e_data_book_direct_get_type
 e_data_book_view_get_type
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]