[evolution-data-server] Addressbook: Fixing gtk-doc comments and adding gtk-doc section headers
- From: Tristan Van Berkom <tvb src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [evolution-data-server] Addressbook: Fixing gtk-doc comments and adding gtk-doc section headers
- Date: Fri, 6 Dec 2013 10:37:04 +0000 (UTC)
commit ccebc18eed5c8f20a275532a09c6e84496f48b68
Author: Tristan Van Berkom <tristan upstairslabs com>
Date: Fri Dec 6 14:58:38 2013 +0900
Addressbook: Fixing gtk-doc comments and adding gtk-doc section headers
addressbook/libebook-contacts/e-address-western.h | 12 +
.../libebook-contacts/e-book-contacts-types.h | 113 ++++--
addressbook/libebook-contacts/e-book-query.c | 10 +
addressbook/libebook-contacts/e-contact.c | 10 +
.../libebook-contacts/e-phone-number-private.h | 9 +-
addressbook/libebook-contacts/e-vcard.c | 2 +-
addressbook/libebook/e-book-client-cursor.c | 20 +-
addressbook/libebook/e-book-client-view.c | 10 +
addressbook/libebook/e-book-client-view.h | 15 +
addressbook/libebook/e-book-client.c | 13 +-
addressbook/libebook/e-book-client.h | 9 +
addressbook/libebook/e-book-types.h | 32 ++-
addressbook/libebook/e-book-view.h | 20 +
addressbook/libebook/e-book.h | 40 ++-
addressbook/libedata-book/e-book-backend-cache.c | 25 ++
addressbook/libedata-book/e-book-backend-cache.h | 21 +
.../libedata-book/e-book-backend-db-cache.c | 37 ++
.../libedata-book/e-book-backend-db-cache.h | 4 +
addressbook/libedata-book/e-book-backend-factory.c | 9 +
addressbook/libedata-book/e-book-backend-factory.h | 20 +
addressbook/libedata-book/e-book-backend-sexp.c | 8 +
addressbook/libedata-book/e-book-backend-sexp.h | 13 +
.../libedata-book/e-book-backend-sqlitedb.c | 421 +++++++++++++++-----
.../libedata-book/e-book-backend-sqlitedb.h | 41 ++-
addressbook/libedata-book/e-book-backend-summary.c | 29 ++
addressbook/libedata-book/e-book-backend-summary.h | 23 +-
addressbook/libedata-book/e-book-backend.c | 9 +
addressbook/libedata-book/e-book-backend.h | 53 +++
addressbook/libedata-book/e-book-sqlite.c | 36 ++-
addressbook/libedata-book/e-book-sqlite.h | 2 +-
addressbook/libedata-book/e-data-book-direct.c | 14 +
addressbook/libedata-book/e-data-book-factory.c | 9 +
addressbook/libedata-book/e-data-book-view.c | 12 +
addressbook/libedata-book/e-data-book.c | 19 +
addressbook/libedata-book/e-data-book.h | 16 -
35 files changed, 964 insertions(+), 172 deletions(-)
---
diff --git a/addressbook/libebook-contacts/e-address-western.h
b/addressbook/libebook-contacts/e-address-western.h
index a4dd8de..ae2a7b8 100644
--- a/addressbook/libebook-contacts/e-address-western.h
+++ b/addressbook/libebook-contacts/e-address-western.h
@@ -9,6 +9,18 @@
G_BEGIN_DECLS
+/**
+ * EAddressWestern:
+ * @po_box: PO Box.
+ * @extended: TODO, we're not sure what this is.
+ * @street: Street name
+ * @locality: City or town
+ * @region: State or province
+ * @postal_code: Postal Code
+ * @country: Country
+ *
+ * Western address structure.
+ */
typedef struct {
/* Public */
diff --git a/addressbook/libebook-contacts/e-book-contacts-types.h
b/addressbook/libebook-contacts/e-book-contacts-types.h
index ca6b952..b8b66f1 100644
--- a/addressbook/libebook-contacts/e-book-contacts-types.h
+++ b/addressbook/libebook-contacts/e-book-contacts-types.h
@@ -21,7 +21,7 @@
/**
* E_BOOK_CLIENT_ERROR:
*
- * FIXME: Document me.
+ * Error domain for #EBookClient errors
*
* Since: 3.2
**/
@@ -49,8 +49,13 @@ typedef enum {
/**
* EBookClientError:
+ * @E_BOOK_CLIENT_ERROR_NO_SUCH_BOOK: Requested book did not exist
+ * @E_BOOK_CLIENT_ERROR_CONTACT_NOT_FOUND: Contact referred to was not found
+ * @E_BOOK_CLIENT_ERROR_CONTACT_ID_ALREADY_EXISTS: Tried to add a contact which already exists
+ * @E_BOOK_CLIENT_ERROR_NO_SUCH_SOURCE: Referred #ESource does not exist
+ * @E_BOOK_CLIENT_ERROR_NO_SPACE: Out of disk space
*
- * FIXME: Document me.
+ * Error codes returned by #EBookClient APIs, if an #EClientError was not available.
*
* Since: 3.2
**/
@@ -64,8 +69,35 @@ typedef enum {
/**
* EDataBookStatus:
+ * @E_DATA_BOOK_STATUS_SUCCESS: No error
+ * @E_DATA_BOOK_STATUS_BUSY: Backend was busy
+ * @E_DATA_BOOK_STATUS_REPOSITORY_OFFLINE: Offsite repository was not online
+ * @E_DATA_BOOK_STATUS_PERMISSION_DENIED: Permission denied
+ * @E_DATA_BOOK_STATUS_CONTACT_NOT_FOUND: Contact referred to was not found
+ * @E_DATA_BOOK_STATUS_CONTACTID_ALREADY_EXISTS: Tried to add a contact which already exists
+ * @E_DATA_BOOK_STATUS_AUTHENTICATION_FAILED: Authentication failure
+ * @E_DATA_BOOK_STATUS_AUTHENTICATION_REQUIRED: Authentication required for this operation
+ * @E_DATA_BOOK_STATUS_UNSUPPORTED_FIELD: An unsupported #EContactField was specified for a given operation
+ * @E_DATA_BOOK_STATUS_UNSUPPORTED_AUTHENTICATION_METHOD: The authentication method is unsupported
+ * @E_DATA_BOOK_STATUS_TLS_NOT_AVAILABLE: TLS was not available
+ * @E_DATA_BOOK_STATUS_NO_SUCH_BOOK: Book did not exist
+ * @E_DATA_BOOK_STATUS_BOOK_REMOVED: Book was removed
+ * @E_DATA_BOOK_STATUS_OFFLINE_UNAVAILABLE: XXX Document me
+ * @E_DATA_BOOK_STATUS_SEARCH_SIZE_LIMIT_EXCEEDED: Exceeded limit of seach size
+ * @E_DATA_BOOK_STATUS_SEARCH_TIME_LIMIT_EXCEEDED: Exceeded time limit for seach
+ * @E_DATA_BOOK_STATUS_INVALID_QUERY: Given search espression is invalid
+ * @E_DATA_BOOK_STATUS_QUERY_REFUSED: Given search espression was refused
+ * @E_DATA_BOOK_STATUS_COULD_NOT_CANCEL: Unable to cancel an operation
+ * @E_DATA_BOOK_STATUS_OTHER_ERROR: An other error occurred
+ * @E_DATA_BOOK_STATUS_INVALID_SERVER_VERSION: Invalid server version
+ * @E_DATA_BOOK_STATUS_NO_SPACE: Disk space insufficient
+ * @E_DATA_BOOK_STATUS_INVALID_ARG: Invalid argument
+ * @E_DATA_BOOK_STATUS_NOT_SUPPORTED: Unsupported operation
+ * @E_DATA_BOOK_STATUS_NOT_OPENED: Tried to access a book which is not yet open
+ * @E_DATA_BOOK_STATUS_OUT_OF_SYNC: Out of sync state
*
- * XXX Document me!
+ * Error codes for the #E_DATA_BOOK_ERROR domain, these are used
+ * in the backend.
*
* Since: 3.6
**/
@@ -98,26 +130,6 @@ typedef enum {
E_DATA_BOOK_STATUS_OUT_OF_SYNC
} EDataBookStatus;
-typedef enum {
- E_BOOK_VIEW_STATUS_OK,
- E_BOOK_VIEW_STATUS_TIME_LIMIT_EXCEEDED,
- E_BOOK_VIEW_STATUS_SIZE_LIMIT_EXCEEDED,
- E_BOOK_VIEW_ERROR_INVALID_QUERY,
- E_BOOK_VIEW_ERROR_QUERY_REFUSED,
- E_BOOK_VIEW_ERROR_OTHER_ERROR
-} EBookViewStatus;
-
-typedef enum {
- E_BOOK_CHANGE_CARD_ADDED,
- E_BOOK_CHANGE_CARD_DELETED,
- E_BOOK_CHANGE_CARD_MODIFIED
-} EBookChangeType;
-
-typedef struct {
- EBookChangeType change_type;
- EContact *contact;
-} EBookChange;
-
/**
* EBookIndexType:
* @E_BOOK_INDEX_PREFIX: An index suitable for searching contacts with a prefix pattern
@@ -189,9 +201,62 @@ GQuark e_book_client_error_quark (void) G_GNUC_CONST;
const gchar * e_book_client_error_to_string (EBookClientError code);
#ifndef EDS_DISABLE_DEPRECATED
+
+/**
+ * EBookViewStatus:
+ * @E_BOOK_VIEW_STATUS_OK: Ok
+ * @E_BOOK_VIEW_STATUS_TIME_LIMIT_EXCEEDED: Time limit exceeded
+ * @E_BOOK_VIEW_STATUS_SIZE_LIMIT_EXCEEDED: Size limit exceeded
+ * @E_BOOK_VIEW_ERROR_INVALID_QUERY: Invalid search expression
+ * @E_BOOK_VIEW_ERROR_QUERY_REFUSED: Search expression refused
+ * @E_BOOK_VIEW_ERROR_OTHER_ERROR: Another error occurred
+ *
+ * Status messages used in notifications in the deprecated #EBookView class
+ *
+ * Deprecated: 3.2: Use #EBookClientView instead.
+ */
+typedef enum {
+ E_BOOK_VIEW_STATUS_OK,
+ E_BOOK_VIEW_STATUS_TIME_LIMIT_EXCEEDED,
+ E_BOOK_VIEW_STATUS_SIZE_LIMIT_EXCEEDED,
+ E_BOOK_VIEW_ERROR_INVALID_QUERY,
+ E_BOOK_VIEW_ERROR_QUERY_REFUSED,
+ E_BOOK_VIEW_ERROR_OTHER_ERROR
+} EBookViewStatus;
+
+/**
+ * EBookChangeType:
+ * @E_BOOK_CHANGE_CARD_ADDED: A vCard was added
+ * @E_BOOK_CHANGE_CARD_DELETED: A vCard was deleted
+ * @E_BOOK_CHANGE_CARD_MODIFIED: A vCard was modified
+ *
+ * The type of change in an #EBookChange
+ *
+ * Deprecated: 3.2
+ */
+typedef enum {
+ E_BOOK_CHANGE_CARD_ADDED,
+ E_BOOK_CHANGE_CARD_DELETED,
+ E_BOOK_CHANGE_CARD_MODIFIED
+} EBookChangeType;
+
+/**
+ * EBookChange:
+ * @change_type: The #EBookChangeType
+ * @contact: The #EContact which changed
+ *
+ * This is a part of the deprecated #EBook API.
+ *
+ * Deprecated: 3.2
+ */
+typedef struct {
+ EBookChangeType change_type;
+ EContact *contact;
+} EBookChange;
+
GError * e_book_client_error_create (EBookClientError code,
const gchar *custom_msg);
-#endif /* E_BOOK_DISABLE_DEPRECATED */
+#endif /* EDS_DISABLE_DEPRECATED */
G_END_DECLS
diff --git a/addressbook/libebook-contacts/e-book-query.c b/addressbook/libebook-contacts/e-book-query.c
index d6180e3..8bbb49e 100644
--- a/addressbook/libebook-contacts/e-book-query.c
+++ b/addressbook/libebook-contacts/e-book-query.c
@@ -24,6 +24,16 @@
* Tristan Van Berkom <tristanvb openismus com>
*/
+/**
+ * SECTION: e-book-query
+ * @include: libebook-contacts/libebook-contacts.h
+ * @short_description: Querying and filtering contacts in an addressbook
+ *
+ * This utility can be used to conveniently create search expressions
+ * which can later be used to query and filter results in the #EBookClient,
+ * #EBookClientView and #EBookClientCursor interfaces.
+ **/
+
#include "e-book-query.h"
#include <config.h>
diff --git a/addressbook/libebook-contacts/e-contact.c b/addressbook/libebook-contacts/e-contact.c
index 89d9966..1638de3 100644
--- a/addressbook/libebook-contacts/e-contact.c
+++ b/addressbook/libebook-contacts/e-contact.c
@@ -23,6 +23,16 @@
* Tristan Van Berkom <tristanvb openismus com>
*/
+/**
+ * SECTION:e-contact
+ * @short_description: A convenience interface for interacting with contacts
+ * @include: libebook-contacts/libebook-contacts.h
+ *
+ * This subclass of #EVCard is a convenient interface for interacting with
+ * vCards. The #EBookClient, #EBookClientView and #EBookClientCursor return
+ * vCards in the form of an #EContact for your convenience.
+ **/
+
#if HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/addressbook/libebook-contacts/e-phone-number-private.h
b/addressbook/libebook-contacts/e-phone-number-private.h
index 0f80491..e9a855e 100644
--- a/addressbook/libebook-contacts/e-phone-number-private.h
+++ b/addressbook/libebook-contacts/e-phone-number-private.h
@@ -22,15 +22,10 @@
/* NOTE: Keeping API documentation in this header file because gtkdoc-mkdb
* explicitly only scans .h and .c files, but ignores .cpp files. */
-/**
- * SECTION: e-phone-utils
- * @include: libedataserver/libedataserver.h
- * @short_description: Phone number support
- *
+/*
* This modules provides utility functions for parsing and formatting
* phone numbers. Under the hood it uses Google's libphonenumber.
- **/
-
+ */
#if !defined (__LIBEBOOK_CONTACTS_H_INSIDE__) && !defined (LIBEBOOK_CONTACTS_COMPILATION)
#error "Only <libebook-contacts/libebook-contacts.h> should be included directly."
#endif
diff --git a/addressbook/libebook-contacts/e-vcard.c b/addressbook/libebook-contacts/e-vcard.c
index 8e3c134..f1e37d8 100644
--- a/addressbook/libebook-contacts/e-vcard.c
+++ b/addressbook/libebook-contacts/e-vcard.c
@@ -26,7 +26,7 @@
* SECTION:e-vcard
* @short_description: vCard parsing and interpretation
* @stability: Stable
- * @include: libebook-contacts/e-vcard.h
+ * @include: libebook-contacts/libebook-contacts.h
*
* #EVCard is a low-level representation of a vCard, as specified in RFCs
* 2425 and 2426 (for vCard version 3.0); this class only supports versions 2.1
diff --git a/addressbook/libebook/e-book-client-cursor.c b/addressbook/libebook/e-book-client-cursor.c
index 0249885..84ba1e7 100644
--- a/addressbook/libebook/e-book-client-cursor.c
+++ b/addressbook/libebook/e-book-client-cursor.c
@@ -26,6 +26,9 @@
* The #EBookClientCursor is an iteration based interface for browsing
* a sorted list of contacts in the addressbook.
*
+ * Aside from the documentation found here, a fully functional example
+ * progrem <link linkend="eds-cursor-example">can be found here</link>.
+ *
* <refsect2 id="cursor-sort-keys">
* <title>Sort Keys</title>
* <para>
@@ -450,23 +453,6 @@
* </para>
* </refsect2>
*
- * <refsect2 id="cursor-example-program">
- * <title>Example Contact Browser</title>
- * <para>
- * Evolution Data Server comes with an example implementation of a
- * contact browser using the cursor features, the main portion of
- * this example is included here below.
- * </para>
- * <informalexample>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
- * parse="text"
- * href="../../../../../tests/cursor-example/cursor-example.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </informalexample>
- * </refsect2>
*/
#ifdef HAVE_CONFIG_H
#include <config.h>
diff --git a/addressbook/libebook/e-book-client-view.c b/addressbook/libebook/e-book-client-view.c
index ce85774..7569d12 100644
--- a/addressbook/libebook/e-book-client-view.c
+++ b/addressbook/libebook/e-book-client-view.c
@@ -20,6 +20,16 @@
* Author: Ross Burton <ross linux intel com>
*/
+/**
+ * SECTION: e-book-client-view
+ * @include: libebook/libebook.h
+ * @short_description: Recieving change notifications on addressbooks
+ *
+ * This class provides functionality for watching for changes on a
+ * given addressbook opened with an #EBookClient. Use e_book_client_get_view()
+ * to create an #EBookClientView.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/addressbook/libebook/e-book-client-view.h b/addressbook/libebook/e-book-client-view.h
index ab37ced..0a92c06 100644
--- a/addressbook/libebook/e-book-client-view.h
+++ b/addressbook/libebook/e-book-client-view.h
@@ -64,13 +64,28 @@ struct _EBookClient;
* Since: 3.2
**/
struct _EBookClientView {
+ /*< private >*/
GObject parent;
EBookClientViewPrivate *priv;
};
+/**
+ * EBookClientViewClass:
+ * @objects_added: Signal emitted when contacts are added in the view
+ * @objects_removed: Signal emitted when contacts are removed from the view
+ * @objects_modified: Signal emitted when contacts in the view are modified
+ * @progress: Signal emitted intermittently while loading a view after calling e_book_client_view_start()
+ * @complete: Notification that loading a view has completed, after calling e_book_client_view_start()
+ *
+ * Class structure for the #EBookClient class.
+ *
+ * Since: 3.2
+ **/
struct _EBookClientViewClass {
+ /*< private >*/
GObjectClass parent_class;
+ /*< public >*/
/* Signals */
void (*objects_added) (EBookClientView *client_view,
const GSList *objects);
diff --git a/addressbook/libebook/e-book-client.c b/addressbook/libebook/e-book-client.c
index 5ed9c6e..8ab9698 100644
--- a/addressbook/libebook/e-book-client.c
+++ b/addressbook/libebook/e-book-client.c
@@ -20,6 +20,15 @@
*
*/
+/**
+ * SECTION: e-book-client
+ * @include: libebook/libebook.h
+ * @short_description: Accessing and modifying an addressbook
+ *
+ * This class is the main user facing API for accessing and modifying
+ * the addressbook.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -1121,8 +1130,8 @@ e_book_client_class_init (EBookClientClass *class)
PROP_LOCALE,
g_param_spec_string (
"locale",
- NULL,
- NULL,
+ "Locale",
+ "The currently active locale for this addressbook",
NULL,
G_PARAM_READABLE |
G_PARAM_STATIC_STRINGS));
diff --git a/addressbook/libebook/e-book-client.h b/addressbook/libebook/e-book-client.h
index f21a104..fa0d396 100644
--- a/addressbook/libebook/e-book-client.h
+++ b/addressbook/libebook/e-book-client.h
@@ -85,11 +85,20 @@ typedef struct _EBookClientPrivate EBookClientPrivate;
* Since: 3.2
**/
struct _EBookClient {
+ /*< private >*/
EClient parent;
EBookClientPrivate *priv;
};
+/**
+ * EBookClientClass:
+ *
+ * Class structure for the #EBookClient class.
+ *
+ * Since: 3.2
+ **/
struct _EBookClientClass {
+ /*< private >*/
EClientClass parent_class;
};
diff --git a/addressbook/libebook/e-book-types.h b/addressbook/libebook/e-book-types.h
index 0f55343..7e0d209 100644
--- a/addressbook/libebook/e-book-types.h
+++ b/addressbook/libebook/e-book-types.h
@@ -20,11 +20,32 @@
G_BEGIN_DECLS
+#ifndef EDS_DISABLE_DEPRECATED
+
+/**
+ * E_BOOK_ERROR:
+ *
+ * Error domain for the deprecated #EBook
+ *
+ * Deprecated: 3.2: Use #EBookClient and it's error codes instead
+ */
#define E_BOOK_ERROR e_book_error_quark()
GQuark e_book_error_quark (void) G_GNUC_CONST;
+/**
+ * EBookStatus:
+ *
+ * Error codes for the #E_BOOK_ERROR error
+ *
+ * Deprecated: 3.2: Use #EBookClient and it's error codes instead
+ */
+
+/* Marked these all as private, since they are deprecated
+ * and we just avoid gtk-doc warnings this way
+ */
typedef enum {
+ /*< private >*/
E_BOOK_ERROR_OK,
E_BOOK_ERROR_INVALID_ARG,
E_BOOK_ERROR_BUSY,
@@ -52,9 +73,16 @@ typedef enum {
E_BOOK_ERROR_NOT_SUPPORTED
} EBookStatus;
-#ifndef E_BOOK_DISABLE_DEPRECATED
+/**
+ * E_BOOK_ERROR_CORBA_EXCEPTION:
+ *
+ * A deprecated #EBookStatus
+ *
+ * Deprecated
+ */
#define E_BOOK_ERROR_CORBA_EXCEPTION E_BOOK_ERROR_DBUS_EXCEPTION
-#endif
+
+#endif /* EDS_DISABLE_DEPRECATED */
G_END_DECLS
diff --git a/addressbook/libebook/e-book-view.h b/addressbook/libebook/e-book-view.h
index b80e0a0..a6602e0 100644
--- a/addressbook/libebook/e-book-view.h
+++ b/addressbook/libebook/e-book-view.h
@@ -50,14 +50,33 @@ typedef struct _EBookViewPrivate EBookViewPrivate;
struct _EBook;
+/**
+ * EBookView:
+ *
+ * Deprecated: 3.2: Use #EBookClientView instead.
+ */
struct _EBookView {
+ /*< private >*/
GObject parent;
EBookViewPrivate *priv;
};
+/**
+ * EBookViewClass:
+ * @contacts_changed: Signal emitted when contacts in the view are modified
+ * @contacts_removed: Signal emitted when contacts are removed from the view
+ * @contacts_added: Signal emitted when contacts are added in the view
+ * @sequence_complete: Notification that loading a view has completed, after calling e_book_view_start()
+ * @view_complete: Notification that loading a view has completed, after calling e_book_view_start()
+ * @status_message: Signal emitted intermittently while loading a view after calling e_book_view_start()
+ *
+ * Deprecated: 3.2: Use #EBookClientView instead.
+ */
struct _EBookViewClass {
+ /*< private >*/
GObjectClass parent_class;
+ /*< public >*/
/* Signals */
void (*contacts_changed) (EBookView *book_view,
const GList *contacts);
@@ -73,6 +92,7 @@ struct _EBookViewClass {
void (*status_message) (EBookView *book_view,
const gchar *message);
+ /*< private >*/
/* Padding for future expansion */
void (*_ebook_reserved0) (void);
void (*_ebook_reserved1) (void);
diff --git a/addressbook/libebook/e-book.h b/addressbook/libebook/e-book.h
index fb00827..aa51ca8 100644
--- a/addressbook/libebook/e-book.h
+++ b/addressbook/libebook/e-book.h
@@ -48,6 +48,8 @@ typedef void (*EBookCallback) (EBook *book, EBookStatus status, gpointer closure
* @closure: the callback closure
*
* Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
**/
typedef void (*EBookAsyncCallback) (EBook *book, const GError *error, gpointer closure);
@@ -59,6 +61,8 @@ typedef void (*EBookAsyncCallback) (EBook *book, const GError *error, gpointer c
* @closure: the callback closure
*
* Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
**/
typedef void (*EBookOpenProgressCallback) (EBook *book,
const gchar *status_message,
@@ -78,6 +82,8 @@ typedef void (*EBookEListCallback) (EBook *book, EBookStatus status, EList *li
* @closure: the callback closure
*
* Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
**/
typedef void (*EBookIdAsyncCallback) (EBook *book, const GError *error, const gchar *id, gpointer
closure);
@@ -89,6 +95,8 @@ typedef void (*EBookIdAsyncCallback) (EBook *book, const GError *error, co
* @closure: the callback closure
*
* Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
**/
typedef void (*EBookContactAsyncCallback) (EBook *book, const GError *error, EContact *contact, gpointer
closure);
@@ -100,6 +108,8 @@ typedef void (*EBookContactAsyncCallback) (EBook *book, const GError *error, EC
* @closure: the callback closure
*
* Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
**/
typedef void (*EBookListAsyncCallback) (EBook *book, const GError *error, GList *list, gpointer closure);
@@ -111,6 +121,8 @@ typedef void (*EBookListAsyncCallback) (EBook *book, const GError *error, GL
* @closure: the callback closure
*
* Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
**/
typedef void (*EBookBookViewAsyncCallback) (EBook *book, const GError *error, EBookView *book_view, gpointer
closure);
@@ -122,18 +134,43 @@ typedef void (*EBookBookViewAsyncCallback) (EBook *book, const GError *error, EB
* @closure: the callback closure
*
* Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
**/
typedef void (*EBookEListAsyncCallback) (EBook *book, const GError *error, EList *list, gpointer closure);
+/**
+ * EBook:
+ *
+ * The deprecated API for accessing the addressbook
+ *
+ * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
+ */
struct _EBook {
- GObject parent;
/*< private >*/
+ GObject parent;
EBookPrivate *priv;
};
+/**
+ * EBookClass:
+ * @writable_status: deprecated
+ * @connection_status: deprecated
+ * @backend_died: deprecated
+ *
+ * Class structure for the deprecated API for accessing the addressbook
+ *
+ * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
+ */
struct _EBookClass {
+ /*< private >*/
GObjectClass parent;
+ /*< public >*/
/*
* Signals.
*/
@@ -141,6 +178,7 @@ struct _EBookClass {
void (* connection_status) (EBook *book, gboolean connected);
void (* backend_died) (EBook *book);
+ /*< private >*/
/* Padding for future expansion */
void (*_ebook_reserved0) (void);
void (*_ebook_reserved1) (void);
diff --git a/addressbook/libedata-book/e-book-backend-cache.c
b/addressbook/libedata-book/e-book-backend-cache.c
index 00e0206..6fee8d9 100644
--- a/addressbook/libedata-book/e-book-backend-cache.c
+++ b/addressbook/libedata-book/e-book-backend-cache.c
@@ -19,6 +19,13 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/**
+ * SECTION: e-book-backend-cache
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A utility for storing contact data and searching for contacts
+ *
+ * The #EBookBackendCache is deprecated, use #EBookSqlite instead.
+ */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -58,6 +65,8 @@ e_book_backend_cache_init (EBookBackendCache *cache)
* #EContact objects, useful for remote backends.
*
* Returns: a new #EBookBackendCache
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
EBookBackendCache *
e_book_backend_cache_new (const gchar *filename)
@@ -79,6 +88,8 @@ e_book_backend_cache_new (const gchar *filename)
* needed.
*
* Returns: A cached #EContact, or %NULL if @uid is not cached.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
EContact *
e_book_backend_cache_get_contact (EBookBackendCache *cache,
@@ -107,6 +118,8 @@ e_book_backend_cache_get_contact (EBookBackendCache *cache,
* Adds @contact to @cache.
*
* Returns: %TRUE if the contact was cached successfully, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_cache_add_contact (EBookBackendCache *cache,
@@ -139,6 +152,8 @@ e_book_backend_cache_add_contact (EBookBackendCache *cache,
* Removes the contact identified by @uid from @cache.
*
* Returns: %TRUE if the contact was found and removed, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_cache_remove_contact (EBookBackendCache *cache,
@@ -162,6 +177,8 @@ e_book_backend_cache_remove_contact (EBookBackendCache *cache,
* Checks if the contact identified by @uid exists in @cache.
*
* Returns: %TRUE if the cache contains the contact, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_cache_check_contact (EBookBackendCache *cache,
@@ -189,6 +206,8 @@ e_book_backend_cache_check_contact (EBookBackendCache *cache,
* free the list.
*
* Returns: A #GList of pointers to #EContact.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
GList *
e_book_backend_cache_get_contacts (EBookBackendCache *cache,
@@ -240,6 +259,8 @@ e_book_backend_cache_get_contacts (EBookBackendCache *cache,
* free the ID strings and the array.
*
* Returns: A #GPtrArray of pointers to contact ID strings.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
GPtrArray *
e_book_backend_cache_search (EBookBackendCache *cache,
@@ -267,6 +288,8 @@ e_book_backend_cache_search (EBookBackendCache *cache,
*
* Flags @cache as being populated - that is, it is up-to-date on the
* contents of the book it's caching.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
void
e_book_backend_cache_set_populated (EBookBackendCache *cache)
@@ -282,6 +305,8 @@ e_book_backend_cache_set_populated (EBookBackendCache *cache)
* Checks if @cache is populated.
*
* Returns: %TRUE if @cache is populated, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_cache_is_populated (EBookBackendCache *cache)
diff --git a/addressbook/libedata-book/e-book-backend-cache.h
b/addressbook/libedata-book/e-book-backend-cache.h
index ed0163a..f977d4b 100644
--- a/addressbook/libedata-book/e-book-backend-cache.h
+++ b/addressbook/libedata-book/e-book-backend-cache.h
@@ -27,6 +27,8 @@
#ifndef E_BOOK_BACKEND_CACHE_H
#define E_BOOK_BACKEND_CACHE_H
+#ifndef EDS_DISABLE_DEPRECATED
+
#include <libebook-contacts/libebook-contacts.h>
#include <libebackend/libebackend.h>
@@ -55,12 +57,29 @@ typedef struct _EBookBackendCache EBookBackendCache;
typedef struct _EBookBackendCacheClass EBookBackendCacheClass;
typedef struct _EBookBackendCachePrivate EBookBackendCachePrivate;
+/**
+ * EBookBackendCache:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
+ */
struct _EBookBackendCache {
+ /*< private >*/
EFileCache parent;
EBookBackendCachePrivate *priv;
};
+/**
+ * EBookBackendCacheClass:
+ *
+ * Class structure for the #EBookBackendCache class.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
+ */
struct _EBookBackendCacheClass {
+ /*< private >*/
EFileCacheClass parent_class;
};
@@ -92,4 +111,6 @@ GPtrArray * e_book_backend_cache_search (EBookBackendCache *cache,
G_END_DECLS
+#endif /* EDS_DISABLE_DEPRECATED */
+
#endif /* E_BOOK_BACKEND_CACHE_H */
diff --git a/addressbook/libedata-book/e-book-backend-db-cache.c
b/addressbook/libedata-book/e-book-backend-db-cache.c
index 7bebb09..fc1bc1a 100644
--- a/addressbook/libedata-book/e-book-backend-db-cache.c
+++ b/addressbook/libedata-book/e-book-backend-db-cache.c
@@ -19,6 +19,14 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/**
+ * SECTION: e-book-backend-db-cache
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A Berkeley DB cache facility for addressbooks
+ *
+ * This API is deprecated, use #EBookSqlite instead.
+ */
+
#include <config.h>
#include <stdlib.h>
#include <string.h>
@@ -65,6 +73,8 @@ get_filename_from_uri (const gchar *uri)
* @filename: filename to be set
*
* Set the filename for db cacahe file.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
void
@@ -89,6 +99,8 @@ e_book_backend_db_cache_set_filename (DB *db,
* @db: DB Handle
*
* Get the filename for db cacahe file.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gchar *
@@ -124,6 +136,8 @@ e_book_backend_db_cache_get_filename (DB *db)
* needed.
*
* Returns: A cached #EContact, or %NULL if @uid is not cached.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
EContact *
e_book_backend_db_cache_get_contact (DB *db,
@@ -158,6 +172,8 @@ e_book_backend_db_cache_get_contact (DB *db,
* Adds @contact to @cache.
*
* Returns: %TRUE if the contact was cached successfully, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_db_cache_add_contact (DB *db,
@@ -203,6 +219,8 @@ e_book_backend_db_cache_add_contact (DB *db,
* Removes the contact identified by @uid from @cache.
*
* Returns: %TRUE if the contact was found and removed, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_db_cache_remove_contact (DB *db,
@@ -234,6 +252,8 @@ e_book_backend_db_cache_remove_contact (DB *db,
* Checks if the contact identified by @uid exists in @cache.
*
* Returns: %TRUE if the cache contains the contact, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_db_cache_check_contact (DB *db,
@@ -267,6 +287,8 @@ e_book_backend_db_cache_check_contact (DB *db,
* free the list.
*
* Returns: A #GList of pointers to #EContact.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
GList *
e_book_backend_db_cache_get_contacts (DB *db,
@@ -329,6 +351,8 @@ e_book_backend_db_cache_get_contacts (DB *db,
* free the ID strings and the array.
*
* Returns: A #GPtrArray of pointers to contact ID strings.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
GPtrArray *
e_book_backend_db_cache_search (DB *db,
@@ -357,6 +381,8 @@ e_book_backend_db_cache_search (DB *db,
* Checks if an #EBookBackendCache exists at @uri.
*
* Returns: %TRUE if cache exists, %FALSE if not.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_db_cache_exists (const gchar *uri)
@@ -379,6 +405,8 @@ e_book_backend_db_cache_exists (const gchar *uri)
*
* Flags @cache as being populated - that is, it is up-to-date on the
* contents of the book it's caching.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
void
e_book_backend_db_cache_set_populated (DB *db)
@@ -402,6 +430,8 @@ e_book_backend_db_cache_set_populated (DB *db)
* Checks if @cache is populated.
*
* Returns: %TRUE if @cache is populated, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_db_cache_is_populated (DB *db)
@@ -425,8 +455,12 @@ e_book_backend_db_cache_is_populated (DB *db)
/**
* e_book_backend_db_cache_set_time:
+ * @db: A Berkeley DB handle
+ * @t: The time in string format
*
* Since: 2.26
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
void
e_book_backend_db_cache_set_time (DB *db,
@@ -446,8 +480,11 @@ e_book_backend_db_cache_set_time (DB *db,
/**
* e_book_backend_db_cache_get_time:
+ * @db: A Berkeley DB handle
*
* Since: 2.26
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gchar *
e_book_backend_db_cache_get_time (DB *db)
diff --git a/addressbook/libedata-book/e-book-backend-db-cache.h
b/addressbook/libedata-book/e-book-backend-db-cache.h
index 41c47fb..fcb2dfc 100644
--- a/addressbook/libedata-book/e-book-backend-db-cache.h
+++ b/addressbook/libedata-book/e-book-backend-db-cache.h
@@ -26,6 +26,8 @@
#ifndef E_BOOK_BACKEND_DB_CACHE_H
#define E_BOOK_BACKEND_DB_CACHE_H
+#ifndef EDS_DISABLE_DEPRECATED
+
#include <libebook-contacts/libebook-contacts.h>
G_BEGIN_DECLS
@@ -68,5 +70,7 @@ gchar * e_book_backend_db_cache_get_time
G_END_DECLS
+#endif /* EDS_DISABLE_DEPRECATED */
+
#endif /* E_BOOK_BACKEND_DB_CACHE_H */
diff --git a/addressbook/libedata-book/e-book-backend-factory.c
b/addressbook/libedata-book/e-book-backend-factory.c
index e63c173..296c13c 100644
--- a/addressbook/libedata-book/e-book-backend-factory.c
+++ b/addressbook/libedata-book/e-book-backend-factory.c
@@ -7,6 +7,15 @@
* Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
*/
+/**
+ * SECTION: e-book-backend-factory
+ * @include: libedata-book/libedata-book.h
+ * @short_description: The factory for creating new addressbooks
+ *
+ * This class handles creation of new addressbooks of various
+ * backend types.
+ **/
+
#include <config.h>
#include "e-book-backend.h"
diff --git a/addressbook/libedata-book/e-book-backend-factory.h
b/addressbook/libedata-book/e-book-backend-factory.h
index 7ae50aa..a8d94ca 100644
--- a/addressbook/libedata-book/e-book-backend-factory.h
+++ b/addressbook/libedata-book/e-book-backend-factory.h
@@ -54,14 +54,34 @@ typedef struct _EBookBackendFactory EBookBackendFactory;
typedef struct _EBookBackendFactoryClass EBookBackendFactoryClass;
typedef struct _EBookBackendFactoryPrivate EBookBackendFactoryPrivate;
+/**
+ * EBookBackendFactory:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
struct _EBookBackendFactory {
+ /*< private >*/
EBackendFactory parent;
EBookBackendFactoryPrivate *priv;
};
+/**
+ * EBookBackendFactoryClass:
+ * @factory_name: The string identifier for this book backend type
+ * @backend_type: The #GType to use to build #EBookBackends for this factory
+ *
+ * Class structure for the #EBookBackendFactory class.
+ *
+ * Subclasses need to set the factory name and backend type
+ * at initialization, the base class will take care of creating
+ * backends of the specified type on demand.
+ */
struct _EBookBackendFactoryClass {
+ /*< private >*/
EBackendFactoryClass parent_class;
+ /*< public >*/
/* Subclasses just need to set these
* class members, we handle the rest. */
const gchar *factory_name;
diff --git a/addressbook/libedata-book/e-book-backend-sexp.c b/addressbook/libedata-book/e-book-backend-sexp.c
index 6bcd13f..51da41a 100644
--- a/addressbook/libedata-book/e-book-backend-sexp.c
+++ b/addressbook/libedata-book/e-book-backend-sexp.c
@@ -23,6 +23,14 @@
* 02110-1301, USA.
*/
+
+/**
+ * SECTION: e-book-backend-sexp
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A utility for comparing #EContacts or vcards with search expressions.
+ *
+ * This API is an all purpose utility for comparing #EContacts with search expressions generated by
#EBookQuery.
+ */
#include "e-book-backend-sexp.h"
#include <glib/gi18n.h>
diff --git a/addressbook/libedata-book/e-book-backend-sexp.h b/addressbook/libedata-book/e-book-backend-sexp.h
index 12e5d8d..3dcff67 100644
--- a/addressbook/libedata-book/e-book-backend-sexp.h
+++ b/addressbook/libedata-book/e-book-backend-sexp.h
@@ -57,12 +57,25 @@ typedef struct _EBookBackendSExp EBookBackendSExp;
typedef struct _EBookBackendSExpClass EBookBackendSExpClass;
typedef struct _EBookBackendSExpPrivate EBookBackendSExpPrivate;
+/**
+ * EBookBackendSexp:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
struct _EBookBackendSExp {
+ /*< private >*/
GObject parent;
EBookBackendSExpPrivate *priv;
};
+/**
+ * EBookBackendSexpClass:
+ *
+ * Class structure for the #EBookBackendSexp class.
+ */
struct _EBookBackendSExpClass {
+ /*< private >*/
GObjectClass parent_class;
};
diff --git a/addressbook/libedata-book/e-book-backend-sqlitedb.c
b/addressbook/libedata-book/e-book-backend-sqlitedb.c
index fb21912..296c88c 100644
--- a/addressbook/libedata-book/e-book-backend-sqlitedb.c
+++ b/addressbook/libedata-book/e-book-backend-sqlitedb.c
@@ -22,6 +22,15 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+
+/**
+ * SECTION: e-book-backend-sqlitedb
+ * @include: libedata-book/libedata-book.h
+ * @short_description: An SQLite storage facility for addressbooks
+ *
+ * The #EBookBackendSqliteDB is deprecated, use #EBookSqlite instead.
+ */
+
#include "e-book-backend-sqlitedb.h"
#include <locale.h>
@@ -62,6 +71,15 @@
#endif
#define DB_FILENAME "contacts.db"
+
+/* WARNING:
+ *
+ * FOLDER_VERSION can NEVER be incremented again.
+ *
+ * This class is deprecated and the continuation of this
+ * very same folder version can be found in EBookSqlite,
+ * use EBookSqlite instead.
+ */
#define FOLDER_VERSION 7
typedef enum {
@@ -297,17 +315,6 @@ get_bool_cb (gpointer ref,
return 0;
}
-/**
- * e_book_sql_exec
- * @db:
- * @stmt:
- * @callback:
- * @data:
- * @error:
- *
- * Callers should hold the rw lock depending on read or write operation
- * Returns:
- **/
static gboolean
book_backend_sql_exec_real (sqlite3 *db,
const gchar *stmt,
@@ -1785,7 +1792,7 @@ summary_fields_add_indexes (GArray *array,
* @folder_name: name of the address-book
* @store_vcard: True if the vcard should be stored inside db, if FALSE only the summary fields would be
stored inside db.
* @setup: an #ESourceBackendSummarySetup describing how the summary should be setup
- * @error: A location to store any error that may have occurred
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Like e_book_backend_sqlitedb_new(), but allows configuration of which contact fields
* will be stored for quick reference in the summary. The configuration indicated by
@@ -1801,6 +1808,8 @@ summary_fields_add_indexes (GArray *array,
* Returns: (transfer full): The newly created #EBookBackendSqliteDB
*
* Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
EBookBackendSqliteDB *
e_book_backend_sqlitedb_new_full (const gchar *path,
@@ -1878,20 +1887,22 @@ e_book_backend_sqlitedb_new_full (const gchar *path,
}
/**
- * e_book_backend_sqlitedb_new
+ * e_book_backend_sqlitedb_new:
* @path: location where the db would be created
* @emailid: email id of the user
* @folderid: folder id of the address-book
* @folder_name: name of the address-book
* @store_vcard: True if the vcard should be stored inside db, if FALSE only the summary fields would be
stored inside db.
- * @error:
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* If the path for multiple addressbooks are same, the contacts from all addressbooks
* would be stored in same db in different tables.
*
- * Returns:
+ * Returns: (transfer full): A reference to a #EBookBackendSqliteDB
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
EBookBackendSqliteDB *
e_book_backend_sqlitedb_new (const gchar *path,
@@ -1981,6 +1992,8 @@ e_book_backend_sqlitedb_unlock_updates (EBookBackendSqliteDB *ebsdb,
* Note that the active collator will change with the active locale setting.
*
* Returns: (transfer full): A reference to the active collator.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
ECollator *
e_book_backend_sqlitedb_ref_collator(EBookBackendSqliteDB *ebsdb)
@@ -2373,7 +2386,7 @@ insert_contact (EBookBackendSqliteDB *ebsdb,
* @folderid: folder id
* @contact: EContact to be added
* @replace_existing: Whether this contact should replace another contact with the same UID.
- * @error: A location to store any error that may have occurred.
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* This is a convenience wrapper for e_book_backend_sqlitedb_new_contacts,
* which is the preferred means to add or modify multiple contacts when possible.
@@ -2381,6 +2394,8 @@ insert_contact (EBookBackendSqliteDB *ebsdb,
* Returns: TRUE on success.
*
* Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_new_contact (EBookBackendSqliteDB *ebsdb,
@@ -2409,7 +2424,7 @@ e_book_backend_sqlitedb_new_contact (EBookBackendSqliteDB *ebsdb,
* @folderid: folder id
* @contacts: list of EContacts
* @replace_existing: Whether this contact should replace another contact with the same UID.
- * @error: A location to store any error that may have occurred.
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Adds or replaces contacts in @ebsdb. If @replace_existing is specified then existing
* contacts with the same UID will be replaced, otherwise adding an existing contact
@@ -2418,6 +2433,8 @@ e_book_backend_sqlitedb_new_contact (EBookBackendSqliteDB *ebsdb,
* Returns: TRUE on success.
*
* Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_new_contacts (EBookBackendSqliteDB *ebsdb,
@@ -2470,13 +2487,13 @@ e_book_backend_sqlitedb_new_contacts (EBookBackendSqliteDB *ebsdb,
}
/**
- * e_book_backend_sqlitedb_add_contact
- * @ebsdb:
+ * e_book_backend_sqlitedb_add_contact:
+ * @ebsdb: An #EBookBackendSqliteDB
* @folderid: folder id
* @contact: EContact to be added
* @partial_content: contact does not contain full information. Used when
* the backend cache's partial information for auto-completion.
- * @error:
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* This is a convenience wrapper for e_book_backend_sqlitedb_add_contacts,
* which is the preferred means to add multiple contacts when possible.
@@ -2485,7 +2502,7 @@ e_book_backend_sqlitedb_new_contacts (EBookBackendSqliteDB *ebsdb,
*
* Since: 3.2
*
- * Deprecated: 3.8: Use e_book_backend_sqlitedb_new_contact() instead.
+ * Deprecated: 3.8: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_add_contact (EBookBackendSqliteDB *ebsdb,
@@ -2498,20 +2515,19 @@ e_book_backend_sqlitedb_add_contact (EBookBackendSqliteDB *ebsdb,
}
/**
- * e_book_backend_sqlitedb_add_contacts
- * @ebsdb:
+ * e_book_backend_sqlitedb_add_contacts:
+ * @ebsdb: An #EBookBackendSqliteDB
* @folderid: folder id
* @contacts: list of EContacts
* @partial_content: contact does not contain full information. Used when
* the backend cache's partial information for auto-completion.
- * @error:
- *
+ * @error: (allow-none): A location to store any error that may have occurred.
*
- * Returns: TRUE on success.
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
*
- * Deprecated: 3.8: Use e_book_backend_sqlitedb_new_contacts() instead.
+ * Deprecated: 3.8: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_add_contacts (EBookBackendSqliteDB *ebsdb,
@@ -2525,10 +2541,18 @@ e_book_backend_sqlitedb_add_contacts (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_remove_contact:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id
+ * @uid: the uid of the contact to remove
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Removes the contact indicated by @uid from the folder @folderid in @ebsdb.
*
- * FIXME: Document me.
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_remove_contact (EBookBackendSqliteDB *ebsdb,
@@ -2595,10 +2619,18 @@ generate_delete_stmt (const gchar *table,
/**
* e_book_backend_sqlitedb_remove_contacts:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id
+ * @uids: a #GSList of uids indicating which contacts to remove
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Removes the contacts indicated by @uids from the folder @folderid in @ebsdb.
*
- * FIXME: Document me.
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_remove_contacts (EBookBackendSqliteDB *ebsdb,
@@ -2663,12 +2695,24 @@ contact_found_cb (gpointer ref,
/**
* e_book_backend_sqlitedb_has_contact:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id
+ * @uid: The uid of the contact to check for
+ * @partial_content: This parameter is deprecated and unused.
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Checks if a contact bearing the UID indicated by @uid is stored
+ * in @folderid of @ebsdb.
*
- * FIXME: Document me.
+ * Returns: %TRUE if the the contact exists and there was no error, otherwise %FALSE.
*
- * Note: The @partial_content is unused here.
+ * <note><para>In order to differentiate an error from a contact which simply
+ * is not stored in @ebsdb, you must pass the @error parameter and check whether
+ * it was set by this function.</para></note>
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_has_contact (EBookBackendSqliteDB *ebsdb,
@@ -2720,10 +2764,30 @@ get_vcard_cb (gpointer ref,
/**
* e_book_backend_sqlitedb_get_contact:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id
+ * @uid: The uid of the contact to fetch
+ * @fields_of_interest: (allow-none): A #GHashTable indicating which fields should be included in returned
contacts
+ * @with_all_required_fields: (out) (allow-none): Whether all of the fields of interest were available
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Fetch the #EContact specified by @uid in @folderid of @ebsdb.
+ *
+ * <note><para>The @fields_of_interest parameter is a legacy parameter which can
+ * be used to specify that #EContacts with only the %E_CONTACT_UID
+ * and %E_CONTACT_REV fields. The hash table must use g_str_hash()
+ * and g_str_equal() and the keys 'uid' and 'rev' must be present.</para></note>
*
- * FIXME: Document me.
+ * <note><para>In order to differentiate an error from a contact which simply
+ * is not stored in @ebsdb, you must pass the @error parameter and check whether
+ * it was set by this function.</para></note>
+ *
+ * Returns: On success the #EContact corresponding to @uid is returned, otherwise %NULL is
+ * returned if there was an error or if no contact was found for @uid.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
EContact *
e_book_backend_sqlitedb_get_contact (EBookBackendSqliteDB *ebsdb,
@@ -2783,7 +2847,7 @@ uid_rev_fields (GHashTable *fields_of_interest)
*
* Since: 3.2
*
- * Deprecated: 3.8: Use e_book_backend_sqlitedb_check_summary_fields() instead.
+ * Deprecated: 3.8: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_is_summary_fields (GHashTable *fields_of_interest)
@@ -2821,12 +2885,21 @@ e_book_backend_sqlitedb_is_summary_fields (GHashTable *fields_of_interest)
/**
* e_book_backend_sqlitedb_check_summary_fields:
* @ebsdb: An #EBookBackendSqliteDB
- * @fields_of_interest: A hash table containing the fields of interest
+ * @fields_of_interest: A #GHashTable containing the fields of interest
*
* Checks if all the specified fields are part of the configured summary
* fields for @ebsdb
*
+ * <note><para>The @fields_of_interest parameter must use g_str_hash()
+ * and g_str_equal() and the keys in the hash table, specifying contact
+ * fields, should be derived using e_contact_field_name().</para></note>
+ *
+ * Returns: %TRUE if the fields specified in @fields_of_interest are configured
+ * in the summary.
+ *
* Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_check_summary_fields (EBookBackendSqliteDB *ebsdb,
@@ -2918,8 +2991,8 @@ store_data_to_vcard (gpointer ref,
* @folderid: The folder id
* @uid: The uid to fetch a vcard for
* @fields_of_interest: The required fields for this vcard, or %NULL to require all fields.
- * @with_all_required_fields: (allow none) (out): Whether all the required fields are present in the
returned vcard.
- * @error: A location to store any error that may have occurred.
+ * @with_all_required_fields: (allow-none) (out): Whether all the required fields are present in the
returned vcard.
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Searches @ebsdb in the context of @folderid for @uid.
*
@@ -2933,6 +3006,8 @@ store_data_to_vcard (gpointer ref,
* Returns: (transfer full): The vcard string for @uid or %NULL if @uid was not found.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
gchar *
e_book_backend_sqlitedb_get_vcard_string (EBookBackendSqliteDB *ebsdb,
@@ -3263,14 +3338,18 @@ e_book_backend_sqlitedb_check_summary_query_locked (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_check_summary_query:
- * @ebsdb: an #EBookBackendSqliteDB
+ * @ebsdb: An #EBookBackendSqliteDB
* @query: the query to check
* @with_list_attrs: Return location to store whether the query touches upon list attributes
*
* Checks whether @query contains only checks for the summary fields
* configured in @ebsdb
*
+ * Returns: %TRUE if @query contains only fields configured in the summary.
+ *
* Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_check_summary_query (EBookBackendSqliteDB *ebsdb,
@@ -3290,12 +3369,17 @@ e_book_backend_sqlitedb_check_summary_query (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_is_summary_query:
+ * @query: the query to check
*
* Checks whether the query contains only checks for the default summary fields
*
+ * Returns: %TRUE if @query contains only fields configured in the summary.
+ *
* Since: 3.2
*
* Deprecated: 3.8: Use e_book_backend_sqlitedb_check_summary_query() instead
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_is_summary_query (const gchar *query)
@@ -4136,37 +4220,42 @@ book_backend_sqlitedb_search_full (EBookBackendSqliteDB *ebsdb,
}
/**
- * e_book_backend_sqlitedb_search
- * @ebsdb:
- * @folderid:
- * @sexp: search expression; use NULL or an empty string to get all stored
- * contacts.
- * @fields_of_interest: a #GHashTable containing the names of fields to return,
- * or NULL for all. At the moment if this is non-null, the vcard will be
- * populated with summary fields, else it would return the whole vcard if
- * its stored in the db. [not implemented fully]
- * @searched: (allow none) (out): Whether @ebsdb was capable of searching
+ * e_book_backend_sqlitedb_search:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @sexp: (allow-none): search expression; use %NULL or an empty string to get all stored contacts.
+ * @fields_of_interest: (allow-none): A #GHashTable indicating which fields should be
+ * included in the returned contacts
+ * @searched: (allow-none) (out): Whether @ebsdb was capable of searching
* for the provided query @sexp.
- * @with_all_required_fields: (allow none) (out): Whether all the required
+ * @with_all_required_fields: (allow-none) (out): Whether all the required
* fields are present in the returned vcards.
- * @error:
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Searching with summary fields is always supported. Search expressions
* containing any other field is supported only if backend chooses to store
* the vcard inside the db.
*
- * Summary fields - uid, rev, nickname, given_name, family_name, file_as
- * email_1, email_2, email_3, email_4, is_list, list_show_addresses, wants_html
+ * If not configured otherwise, the default summary fields include:
+ * uid, rev, file_as, nickname, full_name, given_name, family_name,
+ * email, is_list, list_show_addresses, wants_html.
+ *
+ * Summary fields can be configured at addressbook creation time using
+ * the #ESourceBackendSummarySetup source extension.
*
- * If @ebsdb was incapable of returning vcards with results that satisfy
- * @fields_of_interest, then @with_all_required_fields will be updated to
- * @FALSE and only uid fields will be present in the returned vcards. This
- * can be useful when a summary query succeeds and the returned list can be
- * used to iterate and fetch for full required data from another persistance.
+ * <note><para>The @fields_of_interest parameter is a legacy parameter which can
+ * be used to specify that #EContacts with only the %E_CONTACT_UID
+ * and %E_CONTACT_REV fields. The hash table must use g_str_hash()
+ * and g_str_equal() and the keys 'uid' and 'rev' must be present.</para></note>
+ *
+ * The returned list should be freed with g_slist_free()
+ * and all elements freed with e_book_backend_sqlitedb_search_data_free().
*
- * Returns: List of EbSdbSearchData.
+ * Returns: (transfer full): A #GSList of #EbSdbSearchData structures.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
GSList *
e_book_backend_sqlitedb_search (EBookBackendSqliteDB *ebsdb,
@@ -4246,10 +4335,22 @@ e_book_backend_sqlitedb_search (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_search_uids:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @sexp: (allow-none): search expression; use %NULL or an empty string to get all stored contacts.
+ * @searched: (allow-none) (out): Whether @ebsdb was capable of searching for the provided query @sexp.
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Similar to e_book_backend_sqlitedb_search(), but returns only a list of contact UIDs.
*
- * FIXME: Document me.
+ * The returned list should be freed with g_slist_free()
+ * and all elements freed with g_free().
+ *
+ * Returns: (transfer full): A #GSList of allocated contact UID strings.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
GSList *
e_book_backend_sqlitedb_search_uids (EBookBackendSqliteDB *ebsdb,
@@ -4358,13 +4459,20 @@ get_uids_and_rev_cb (gpointer user_data,
/**
* e_book_backend_sqlitedb_get_uids_and_rev:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Gets hash table of all uids (key) and rev (value) pairs stored
* for each contact in the cache. The hash table should be freed
* with g_hash_table_destroy(), if not needed anymore. Each key
* and value is a newly allocated string.
*
+ * Returns: (transfer full): A #GHashTable of all contact revisions by UID.
+ *
* Since: 3.4
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
GHashTable *
e_book_backend_sqlitedb_get_uids_and_rev (EBookBackendSqliteDB *ebsdb,
@@ -4394,10 +4502,21 @@ e_book_backend_sqlitedb_get_uids_and_rev (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_get_is_populated:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @error: (allow-none): A location to store any error that may have occurred.
*
- * FIXME: Document me.
+ * Checks whether the 'is populated' flag is set for @folderid in @ebsdb.
+ *
+ * <note><para>In order to differentiate an error from the flag simply being
+ * %FALSE for @ebsdb, you must pass the @error parameter and check whether
+ * it was set by this function.</para></note>
+ *
+ * Returns: Whether the 'is populated' flag is set.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_get_is_populated (EBookBackendSqliteDB *ebsdb,
@@ -4427,10 +4546,18 @@ e_book_backend_sqlitedb_get_is_populated (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_set_is_populated:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @populated: The new value for the 'is populated' flag.
+ * @error: (allow-none): A location to store any error that may have occurred.
*
- * FIXME: Document me.
+ * Sets the value of the 'is populated' flag for @folderid in @ebsdb.
+ *
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_set_is_populated (EBookBackendSqliteDB *ebsdb,
@@ -4475,16 +4602,15 @@ e_book_backend_sqlitedb_set_is_populated (EBookBackendSqliteDB *ebsdb,
* @folderid: folder id of the address-book
* @revision_out: (out) (transfer full): The location to return the current
* revision
- * @error: A location to store any error that may have occurred
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Fetches the current revision for the address-book indicated by @folderid.
*
- * Upon success, @revision_out will hold the returned revision, otherwise
- * %FALSE will be returned and @error will be updated accordingly.
- *
- * Returns: Whether the revision was successfully fetched.
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
gboolean
e_book_backend_sqlitedb_get_revision (EBookBackendSqliteDB *ebsdb,
@@ -4517,13 +4643,15 @@ e_book_backend_sqlitedb_get_revision (EBookBackendSqliteDB *ebsdb,
* @ebsdb: An #EBookBackendSqliteDB
* @folderid: folder id of the address-book
* @revision: The new revision
- * @error: A location to store any error that may have occurred
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Sets the current revision for the address-book indicated by @folderid to be @revision.
*
- * Returns: Whether the revision was successfully set.
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
gboolean
e_book_backend_sqlitedb_set_revision (EBookBackendSqliteDB *ebsdb,
@@ -4564,15 +4692,24 @@ e_book_backend_sqlitedb_set_revision (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_get_has_partial_content
- * @ebsdb:
- * @folderid:
- * @error:
- *
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Fetches the 'partial content' flag from @folderid in @ebsdb.
+ *
+ * This flag is intended to indicate whether the stored vcards contain the full data or
+ * whether they were downloaded only partially.
+ *
+ * <note><para>In order to differentiate an error from the flag simply being
+ * %FALSE for @ebsdb, you must pass the @error parameter and check whether
+ * it was set by this function.</para></note>
*
- * Returns: TRUE if the vcards stored in the db were downloaded partially. It is to indicate
- * the stored vcards does not contain the full data.
+ * Returns: %TRUE if the vcards stored in the db were downloaded partially.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_get_has_partial_content (EBookBackendSqliteDB *ebsdb,
@@ -4601,10 +4738,18 @@ e_book_backend_sqlitedb_get_has_partial_content (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_set_has_partial_content:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @partial_content: new value for the 'partial content' flag
+ * @error: (allow-none): A location to store any error that may have occurred.
*
- * FIXME: Document me.
+ * Sets the value of the 'partial content' flag in @folderid of @ebsdb.
+ *
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_set_has_partial_content (EBookBackendSqliteDB *ebsdb,
@@ -4645,10 +4790,22 @@ e_book_backend_sqlitedb_set_has_partial_content (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_get_contact_bdata:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @uid: The UID of the contact to fetch extra data for.
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Fetches extra auxiliary data previously set for @uid.
+ *
+ * <note><para>In order to differentiate an error from the @uid simply
+ * not being present in @ebsdb, you must pass the @error parameter and
+ * check whether it was set by this function.</para></note>
*
- * FIXME: Document me.
+ * Returns: (transfer full): The extra data previously set for @uid, or %NULL
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gchar *
e_book_backend_sqlitedb_get_contact_bdata (EBookBackendSqliteDB *ebsdb,
@@ -4683,10 +4840,19 @@ e_book_backend_sqlitedb_get_contact_bdata (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_set_contact_bdata:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @uid: The UID of the contact to fetch extra data for.
+ * @value: The auxiliary data to set for @uid in @folderid.
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Sets the extra auxiliary data for the contact indicated by @uid.
*
- * FIXME: Document me.
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_set_contact_bdata (EBookBackendSqliteDB *ebsdb,
@@ -4730,10 +4896,17 @@ e_book_backend_sqlitedb_set_contact_bdata (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_get_sync_data:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Fetches data previously set with e_book_backend_sqlitedb_set_sync_data() for the given @folderid.
*
- * FIXME: Document me.
+ * Returns: (transfer full): The data previously set with e_book_backend_sqlitedb_set_sync_data().
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gchar *
e_book_backend_sqlitedb_get_sync_data (EBookBackendSqliteDB *ebsdb,
@@ -4761,10 +4934,18 @@ e_book_backend_sqlitedb_get_sync_data (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_set_sync_data:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @sync_data: The data to set.
+ * @error: (allow-none): A location to store any error that may have occurred.
*
- * FIXME: Document me.
+ * Sets some auxiliary data for the given @folderid in @ebsdb.
+ *
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_set_sync_data (EBookBackendSqliteDB *ebsdb,
@@ -4806,10 +4987,19 @@ e_book_backend_sqlitedb_set_sync_data (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_get_key_value:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @key: the key to fetch a value for
+ * @error: (allow-none): A location to store any error that may have occurred.
*
- * FIXME: Document me.
+ * Fetches data previously set with e_book_backend_sqlitedb_set_key_value() for the
+ * given @key in @folderid.
+ *
+ * Returns: (transfer full): The data previously set with e_book_backend_sqlitedb_set_key_value().
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gchar *
e_book_backend_sqlitedb_get_key_value (EBookBackendSqliteDB *ebsdb,
@@ -4839,10 +5029,19 @@ e_book_backend_sqlitedb_get_key_value (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_set_key_value:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @key: the key to fetch a value for
+ * @value: the value to story for @key in @folderid
+ * @error: (allow-none): A location to store any error that may have occurred.
*
- * FIXME: Document me.
+ * Sets the auxiliary data @value to be stored in relation to @key in @folderid.
+ *
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_set_key_value (EBookBackendSqliteDB *ebsdb,
@@ -4886,12 +5085,17 @@ e_book_backend_sqlitedb_set_key_value (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_get_partially_cached_ids:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @error: (allow-none): A location to store any error that may have occurred.
*
- * FIXME: Document me.
+ * Obsolete, do not use, this always ends with an error.
*
- * Note: Obsolete, do not use, it always ends with an error
+ * Returns: %NULL
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
GSList *
e_book_backend_sqlitedb_get_partially_cached_ids (EBookBackendSqliteDB *ebsdb,
@@ -4920,10 +5124,17 @@ e_book_backend_sqlitedb_get_partially_cached_ids (EBookBackendSqliteDB *ebsdb,
/**
* e_book_backend_sqlitedb_delete_addressbook:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Deletes the addressbook indicated by @folderid in @ebsdb.
*
- * FIXME: Document me.
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_sqlitedb_delete_addressbook (EBookBackendSqliteDB *ebsdb,
@@ -4988,10 +5199,13 @@ rollback:
/**
* e_book_backend_sqlitedb_search_data_free:
+ * @s_data: An #EbSdbSearchData
*
- * FIXME: Document me.
+ * Frees an #EbSdbSearchData
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
void
e_book_backend_sqlitedb_search_data_free (EbSdbSearchData *s_data)
@@ -5006,8 +5220,15 @@ e_book_backend_sqlitedb_search_data_free (EbSdbSearchData *s_data)
/**
* e_book_backend_sqlitedb_remove:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @error: (allow-none): A location to store any error that may have occurred.
+ *
+ * Removes the entire @ebsdb from storage on disk.
*
- * FIXME: Document me.
+ * FIXME: it is unclear when it is safe to call this function,
+ * it should probably be deprecated.
+ *
+ * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
*
* Since: 3.2
**/
@@ -5132,7 +5353,7 @@ sqlitedb_set_locale_internal (EBookBackendSqliteDB *ebsdb,
* @ebsdb: An #EBookBackendSqliteDB
* @folderid: folder id of the address-book
* @lc_collate: The new locale for the addressbook
- * @error: A location to store any error that may have occurred
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Relocalizes any locale specific data in the specified
* new @lc_collate locale.
@@ -5145,6 +5366,8 @@ sqlitedb_set_locale_internal (EBookBackendSqliteDB *ebsdb,
* Returns: Whether the new locale was successfully set.
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
gboolean
e_book_backend_sqlitedb_set_locale (EBookBackendSqliteDB *ebsdb,
@@ -5219,7 +5442,7 @@ e_book_backend_sqlitedb_set_locale (EBookBackendSqliteDB *ebsdb,
* @ebsdb: An #EBookBackendSqliteDB
* @folderid: folder id of the address-book
* @locale_out: (out) (transfer full): The location to return the current locale
- * @error: A location to store any error that may have occurred
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Fetches the current locale setting for the address-book indicated by @folderid.
*
@@ -5229,6 +5452,8 @@ e_book_backend_sqlitedb_set_locale (EBookBackendSqliteDB *ebsdb,
* Returns: Whether the locale was successfully fetched.
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
gboolean
e_book_backend_sqlitedb_get_locale (EBookBackendSqliteDB *ebsdb,
@@ -5761,7 +5986,7 @@ cursor_count_position_locked (EBookBackendSqliteDB *ebsdb,
* @sort_fields: (array length=n_sort_fields): An array of #EContactFields as sort keys in order of priority
* @sort_types: (array length=n_sort_fields): An array of #EBookCursorSortTypes, one for each field in
@sort_fields
* @n_sort_fields: The number of fields to sort results by.
- * @error: A return location to store any error that might be reported.
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Creates a new #EbSdbCursor.
*
@@ -5770,6 +5995,8 @@ cursor_count_position_locked (EBookBackendSqliteDB *ebsdb,
* Returns: (transfer full): A newly created #EbSdbCursor
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
EbSdbCursor *
e_book_backend_sqlitedb_cursor_new (EBookBackendSqliteDB *ebsdb,
@@ -5835,6 +6062,8 @@ e_book_backend_sqlitedb_cursor_new (EBookBackendSqliteDB *ebsdb,
* Frees @cursor.
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
void
e_book_backend_sqlitedb_cursor_free (EBookBackendSqliteDB *ebsdb,
@@ -5891,7 +6120,7 @@ collect_results_for_cursor_cb (gpointer ref,
* @count: A positive or negative amount of contacts to try and fetch
* @results: (out) (allow-none) (element-type EbSdbSearchData) (transfer full):
* A return location to store the results, or %NULL if %EBSDB_CURSOR_STEP_FETCH is not specified in %flags.
- * @error: A return location to store any error that might be reported.
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Steps @cursor through it's sorted query by a maximum of @count contacts
* starting from @origin.
@@ -5915,6 +6144,8 @@ collect_results_for_cursor_cb (gpointer ref,
* returned and @error is set.
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
gint
e_book_backend_sqlitedb_cursor_step (EBookBackendSqliteDB *ebsdb,
@@ -6121,6 +6352,8 @@ e_book_backend_sqlitedb_cursor_step (EBookBackendSqliteDB *ebsdb,
* Use e_book_backend_sqlitedb_ref_collator() to obtain the active collator for @ebsdb.
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
void
e_book_backend_sqlitedb_cursor_set_target_alphabetic_index (EBookBackendSqliteDB *ebsdb,
@@ -6150,7 +6383,7 @@ e_book_backend_sqlitedb_cursor_set_target_alphabetic_index (EBookBackendSqliteDB
* @ebsdb: An #EBookBackendSqliteDB
* @cursor: The #EbSdbCursor
* @sexp: The new query expression for @cursor
- * @error: A return location to store any error that might be reported.
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Modifies the current query expression for @cursor. This will not
* modify @cursor's state, but will change the outcome of any further
@@ -6160,6 +6393,8 @@ e_book_backend_sqlitedb_cursor_set_target_alphabetic_index (EBookBackendSqliteDB
* Returns: %TRUE if the expression was valid and accepted by @ebsdb
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
gboolean
e_book_backend_sqlitedb_cursor_set_sexp (EBookBackendSqliteDB *ebsdb,
@@ -6194,7 +6429,7 @@ e_book_backend_sqlitedb_cursor_set_sexp (EBookBackendSqliteDB *ebsdb,
* @cursor: The #EbSdbCursor
* @total: (out) (allow-none): A return location to store the total result set for this cursor
* @position: (out) (allow-none): A return location to store the total results before the cursor value
- * @error: (allow-none): A return location to store any error that might be reported.
+ * @error: (allow-none): A location to store any error that may have occurred.
*
* Calculates the @total amount of results for the @cursor's query expression,
* as well as the current @position of @cursor in the results. @position is
@@ -6205,6 +6440,8 @@ e_book_backend_sqlitedb_cursor_set_sexp (EBookBackendSqliteDB *ebsdb,
* Returns: Whether @total and @position were successfully calculated.
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
gboolean
e_book_backend_sqlitedb_cursor_calculate (EBookBackendSqliteDB *ebsdb,
@@ -6286,6 +6523,8 @@ e_book_backend_sqlitedb_cursor_calculate (EBookBackendSqliteDB *ebsdb,
* respectively, to be less than, to match, or be greater than the current value of @cursor.
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
gint
e_book_backend_sqlitedb_cursor_compare_contact (EBookBackendSqliteDB *ebsdb,
diff --git a/addressbook/libedata-book/e-book-backend-sqlitedb.h
b/addressbook/libedata-book/e-book-backend-sqlitedb.h
index dd08bc7..c17e4d7 100644
--- a/addressbook/libedata-book/e-book-backend-sqlitedb.h
+++ b/addressbook/libedata-book/e-book-backend-sqlitedb.h
@@ -29,6 +29,8 @@
#ifndef E_BOOK_BACKEND_SQLITEDB_H
#define E_BOOK_BACKEND_SQLITEDB_H
+#ifndef EDS_DISABLE_DEPRECATED
+
#include <libebook-contacts/libebook-contacts.h>
/* Standard GObject macros */
@@ -56,6 +58,8 @@
* Error domain for #EBookBackendSqliteDB operations.
*
* Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
#define E_BOOK_SDB_ERROR (e_book_backend_sqlitedb_error_quark ())
@@ -77,6 +81,8 @@ typedef struct _EBookBackendSqliteDBPrivate EBookBackendSqliteDBPrivate;
* @E_BOOK_SDB_ERROR_END_OF_LIST: An attempt was made to fetch results past the end of a contact list
*
* Defines the types of possible errors reported by the #EBookBackendSqliteDB
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
typedef enum {
E_BOOK_SDB_ERROR_CONSTRAINT,
@@ -94,22 +100,45 @@ typedef enum {
* functions below.
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
struct _EBookBackendSqliteDB {
+ /*< private >*/
GObject parent;
EBookBackendSqliteDBPrivate *priv;
};
+/**
+ * EBookBackendSqliteDBClass:
+ *
+ * Class structure for the #EBookBackendSqlite class.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
+ */
struct _EBookBackendSqliteDBClass {
+ /*< private >*/
GObjectClass parent_class;
};
/**
* EbSdbSearchData:
+ * @vcard: The the vcard string
+ * @uid: The %E_CONTACT_UID field of this contact
+ * @bdata: Extra data set for this contact.
*
- * FIXME: Document me.
+ * This structure is used to represent contacts returned
+ * by the EBookBackendSqliteDB from various functions
+ * such as e_book_backend_sqlitedb_search().
+ *
+ * The @bdata parameter will contain any data previously
+ * set for the given contact with e_book_backend_sqlitedb_set_contact_bdata().
+ *
+ * These should be freed with e_book_backend_sqlitedb_search_data_free().
*
* Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
typedef struct {
gchar *vcard;
@@ -123,6 +152,8 @@ typedef struct {
* An opaque cursor pointer
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
typedef struct _EbSdbCursor EbSdbCursor;
@@ -139,6 +170,8 @@ typedef struct _EbSdbCursor EbSdbCursor;
* is the same as %EBSDB_CURSOR_ORIGIN_BEGIN.
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
typedef enum {
EBSDB_CURSOR_ORIGIN_CURRENT = 0,
@@ -154,6 +187,8 @@ typedef enum {
* Defines the behaviour of e_book_backend_sqlitedb_cursor_step().
*
* Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
*/
typedef enum {
EBSDB_CURSOR_STEP_MOVE = (1 << 0),
@@ -378,7 +413,6 @@ gint e_book_backend_sqlitedb_cursor_compare_contact
EContact *contact,
gboolean *matches_sexp);
-#ifndef EDS_DISABLE_DEPRECATED
gboolean e_book_backend_sqlitedb_is_summary_query
(const gchar *query);
gboolean e_book_backend_sqlitedb_is_summary_fields
@@ -395,8 +429,9 @@ gboolean e_book_backend_sqlitedb_add_contacts
GSList *contacts,
gboolean partial_content,
GError **error);
-#endif
G_END_DECLS
+#endif /* EDS_DISABLE_DEPRECATED */
+
#endif /* E_BOOK_BACKEND_SQLITEDB_H */
diff --git a/addressbook/libedata-book/e-book-backend-summary.c
b/addressbook/libedata-book/e-book-backend-summary.c
index c41ee69..686391e 100644
--- a/addressbook/libedata-book/e-book-backend-summary.c
+++ b/addressbook/libedata-book/e-book-backend-summary.c
@@ -21,6 +21,13 @@
* 02110-1301, USA.
*/
+/**
+ * SECTION: e-book-backend-summary
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A utility for storing contact data and searching for contacts
+ *
+ * The #EBookBackendSummary is deprecated, use #EBookSqlite instead.
+ */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -153,6 +160,8 @@ clear_items (EBookBackendSummary *summary)
* the summary is changed until it is flushed to disk.
*
* Returns: A new #EBookBackendSummary.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
EBookBackendSummary *
e_book_backend_summary_new (const gchar *summary_path,
@@ -483,6 +492,8 @@ e_book_backend_summary_open (EBookBackendSummary *summary)
* not out of date.
*
* Returns: %TRUE if the load succeeded, %FALSE if it failed.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_summary_load (EBookBackendSummary *summary)
@@ -640,6 +651,8 @@ e_book_backend_summary_save_item (EBookBackendSummary *summary,
* Attempts to save @summary to disk.
*
* Returns: %TRUE if the save succeeded, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_summary_save (EBookBackendSummary *summary)
@@ -723,6 +736,8 @@ e_book_backend_summary_save (EBookBackendSummary *summary)
*
* Adds a summary of @contact to @summary. Does not check if
* the contact already has a summary.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
void
e_book_backend_summary_add_contact (EBookBackendSummary *summary,
@@ -788,6 +803,8 @@ e_book_backend_summary_add_contact (EBookBackendSummary *summary,
* @id: a unique contact ID string
*
* Removes the summary of the contact identified by @id from @summary.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
void
e_book_backend_summary_remove_contact (EBookBackendSummary *summary,
@@ -819,6 +836,8 @@ e_book_backend_summary_remove_contact (EBookBackendSummary *summary,
* exists in @summary.
*
* Returns: %TRUE if the summary exists, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_summary_check_contact (EBookBackendSummary *summary,
@@ -860,6 +879,8 @@ summary_flush_func (gpointer data)
* @summary: an #EBookBackendSummary
*
* Indicates that @summary has changed and should be flushed to disk.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
void
e_book_backend_summary_touch (EBookBackendSummary *summary)
@@ -883,6 +904,8 @@ e_book_backend_summary_touch (EBookBackendSummary *summary)
* Checks if @summary is more recent than @t.
*
* Returns: %TRUE if the summary is up to date, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_summary_is_up_to_date (EBookBackendSummary *summary,
@@ -955,6 +978,8 @@ static const struct {
* stored by @summary.
*
* Returns: %TRUE if the query can be satisfied, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gboolean
e_book_backend_summary_is_summary_query (EBookBackendSummary *summary,
@@ -1201,6 +1226,8 @@ static const struct {
* Searches @summary for contacts matching @query.
*
* Returns: A #GPtrArray of pointers to contact ID strings.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
GPtrArray *
e_book_backend_summary_search (EBookBackendSummary *summary,
@@ -1261,6 +1288,8 @@ e_book_backend_summary_search (EBookBackendSummary *summary,
* by @id.
*
* Returns: A new VCard, or %NULL if the contact summary didn't exist.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
**/
gchar *
e_book_backend_summary_get_summary_vcard (EBookBackendSummary *summary,
diff --git a/addressbook/libedata-book/e-book-backend-summary.h
b/addressbook/libedata-book/e-book-backend-summary.h
index b229d19..5bff14d 100644
--- a/addressbook/libedata-book/e-book-backend-summary.h
+++ b/addressbook/libedata-book/e-book-backend-summary.h
@@ -28,6 +28,8 @@
#ifndef E_BOOK_BACKEND_SUMMARY_H
#define E_BOOK_BACKEND_SUMMARY_H
+#ifndef EDS_DISABLE_DEPRECATED
+
#include <libebook-contacts/libebook-contacts.h>
/* Standard GObject macros */
@@ -55,12 +57,29 @@ typedef struct _EBookBackendSummary EBookBackendSummary;
typedef struct _EBookBackendSummaryClass EBookBackendSummaryClass;
typedef struct _EBookBackendSummaryPrivate EBookBackendSummaryPrivate;
-struct _EBookBackendSummary{
+/**
+ * EBookBackendSummary:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
+ */
+struct _EBookBackendSummary {
+ /*< private >*/
GObject parent_object;
EBookBackendSummaryPrivate *priv;
};
+/**
+ * EBookBackendSummaryClass:
+ *
+ * Class structure for the deprecated API for accessing the addressbook
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
+ */
struct _EBookBackendSummaryClass{
+ /*< private >*/
GObjectClass parent_class;
};
@@ -103,4 +122,6 @@ gchar * e_book_backend_summary_get_summary_vcard
G_END_DECLS
+#endif /* EDS_DISABLE_DEPRECATED */
+
#endif /* E_BOOK_BACKEND_SUMMARY_H */
diff --git a/addressbook/libedata-book/e-book-backend.c b/addressbook/libedata-book/e-book-backend.c
index 36d1726..ddd210d 100644
--- a/addressbook/libedata-book/e-book-backend.c
+++ b/addressbook/libedata-book/e-book-backend.c
@@ -22,6 +22,15 @@
* Copyright (C) 2012 Intel Corporation
*/
+/**
+ * SECTION: e-book-backend
+ * @include: libedata-book/libedata-book.h
+ * @short_description: An abstract class for implementing addressbook backends
+ *
+ * This is the main server facing API for interfacing with addressbook backends,
+ * addressbook backends must implement methods on this class.
+ **/
+
#include <config.h>
#include <glib/gi18n-lib.h>
diff --git a/addressbook/libedata-book/e-book-backend.h b/addressbook/libedata-book/e-book-backend.h
index d3230b0..5212b9c 100644
--- a/addressbook/libedata-book/e-book-backend.h
+++ b/addressbook/libedata-book/e-book-backend.h
@@ -100,14 +100,67 @@ typedef struct _EBookBackend EBookBackend;
typedef struct _EBookBackendClass EBookBackendClass;
typedef struct _EBookBackendPrivate EBookBackendPrivate;
+/**
+ * EBookBackend:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
struct _EBookBackend {
+ /*< private >*/
EBackend parent;
EBookBackendPrivate *priv;
};
+
+/**
+ * EBookBackendClass:
+ * @use_serial_dispatch_queue: Whether a serial dispatch queue should
+ * be used for this backend or not.
+ * @get_backend_property: Fetch a property value by name from the backend
+ * @open_sync: Open the backend
+ * @refresh_sync: Refresh the backend
+ * @create_contacts_sync: Add and store the passed vcards
+ * @modify_contacts_sync: Modify the existing contacts using the passed vcards
+ * @remove_contacts_sync: Remove the contacts specified by the passed UIDs
+ * @get_contact_sync: Fetch a contact by UID
+ * @get_contact_list_sync: Fetch a list of contacts based on a search expression
+ * @get_contact_list_uids_sync: Fetch a list of contact UIDs based on a search expression (optional)
+ * @start_view: Start up the specified view
+ * @stop_view: Stop the specified view
+ * @notify_update: Notify changes which might have occured for a given contact
+ * @get_direct_book: For addressbook backends which support Direct Read Access,
+ * report some information on how to access the addressbook persistance directly
+ * @configure_direct: For addressbook backends which support Direct Read Access, configure a
+ * backend instantiated on the client side for Direct Read Access, using data
+ * reported from the server via the @get_direct_book method.
+ * @sync: Sync the backend's persistance
+ * @set_locale: Store & remember the passed locale setting
+ * @dup_locale: Return the currently set locale setting (must be a string duplicate, for thread safety).
+ * @create_cursor: Create an #EDataBookCursor
+ * @delete_cursor: Delete an #EDataBookCursor previously created by this backend
+ * @closed: A signal notifying that the backend was closed
+ * @shutdown: A signal notifying that the backend is being shut down
+ * @open: Deprecated method
+ * @refresh: Deprecated method
+ * @create_contacts: Deprecated method
+ * @remove_contacts: Deprecated method
+ * @modify_contacts: Deprecated method
+ * @get_contact: Deprecated method
+ * @get_contact_list: Deprecated method
+ * @get_contact_list_uids: Deprecated method
+ *
+ * Class structure for the #EBookBackend class.
+ *
+ * These virtual methods must be implemented when writing
+ * an addressbook backend.
+ */
struct _EBookBackendClass {
+ /*< private >*/
EBackendClass parent_class;
+ /*< public >*/
+
/* Set this to TRUE to use a serial dispatch queue, instead
* of a concurrent dispatch queue. A serial dispatch queue
* executes one method at a time in the order in which they
diff --git a/addressbook/libedata-book/e-book-sqlite.c b/addressbook/libedata-book/e-book-sqlite.c
index 8ba288c..675fdca 100644
--- a/addressbook/libedata-book/e-book-sqlite.c
+++ b/addressbook/libedata-book/e-book-sqlite.c
@@ -20,6 +20,31 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/**
+ * SECTION: e-book-sqlite
+ * @include: libedata-book/libedata-book.h
+ * @short_description: An SQLite storage facility for addressbooks
+ *
+ * The #EBookSqlite is an API for storing and looking up #EContacts
+ * in an SQLite database. It also supports a lean index mode via
+ * the #EbSqlVCardCallback, if you are in a situation where it is
+ * not convenient to store the vCards directly in the SQLite. It is
+ * however recommended to avoid storing contacts in separate storage
+ * if at all possible, as this will decrease performance of searches
+ * an also contribute to flash wear.
+ *
+ * The API is thread safe, with special considerations to be made
+ * around e_book_sqlite_lock() and e_book_sqlite_unlock() for
+ * the sake of isolating transactions across threads.
+ *
+ * Any operations which can take a lot of time to complete (depending
+ * on the size of your addressbook) can be cancelled using a #GCancellable.
+ *
+ * Depending on your summary configuration, your mileage will vary. Refer
+ * to the #ESourceBackendSummarySetup for configuring your addressbook
+ * for the type of usage you mean to make of it.
+ */
+
#include "e-book-sqlite.h"
#include <locale.h>
@@ -6454,7 +6479,7 @@ e_book_sqlite_has_contact (EBookSqlite *ebsql,
* @ebsql: An #EBookSqlite
* @uid: The uid of the contact to fetch
* @meta_contact: Whether an entire contact is desired, or only the metadata
- * @contact: (out) (transfer full): Return location to store the fetched contact
+ * @ret_contact: (out) (transfer full): Return location to store the fetched contact
* @error: (allow-none): A location to store any error that may have occurred.
*
* Fetch the #EContact specified by @uid in @ebsql.
@@ -6470,7 +6495,7 @@ gboolean
e_book_sqlite_get_contact (EBookSqlite *ebsql,
const gchar *uid,
gboolean meta_contact,
- EContact **contact,
+ EContact **ret_contact,
GError **error)
{
gboolean success = FALSE;
@@ -6478,7 +6503,7 @@ e_book_sqlite_get_contact (EBookSqlite *ebsql,
g_return_val_if_fail (E_IS_BOOK_SQLITE (ebsql), FALSE);
g_return_val_if_fail (uid != NULL, FALSE);
- g_return_val_if_fail (contact != NULL && *contact == NULL, FALSE);
+ g_return_val_if_fail (ret_contact != NULL && *ret_contact == NULL, FALSE);
success = e_book_sqlite_get_vcard (ebsql,
uid,
@@ -6487,7 +6512,7 @@ e_book_sqlite_get_contact (EBookSqlite *ebsql,
error);
if (success && vcard) {
- *contact = e_contact_new_from_vcard_with_uid (vcard, uid);
+ *ret_contact = e_contact_new_from_vcard_with_uid (vcard, uid);
g_free (vcard);
}
@@ -6641,7 +6666,7 @@ e_book_sqlite_get_contact_extra (EBookSqlite *ebsql,
* e_book_sqlite_search:
* @ebsql: An #EBookSqlite
* @sexp: (allow-none): search expression; use %NULL or an empty string to list all stored contacts.
- * @meta_contact: Whether entire contacts are desired, or only the metadata
+ * @meta_contacts: Whether entire contacts are desired, or only the metadata
* @ret_list: (out) (transfer full) (element-type EbSqlSearchData): Return location
* to store a #GSList of #EbSqlSearchData structures
* @cancellable: (allow-none): A #GCancellable
@@ -7015,7 +7040,6 @@ e_book_sqlite_get_locale (EBookSqlite *ebsql,
/**
* e_book_sqlite_cursor_new:
* @ebsql: An #EBookSqlite
- * @folderid: folder id of the address-book
* @sexp: search expression; use NULL or an empty string to get all stored contacts.
* @sort_fields: (array length=n_sort_fields): An array of #EContactFields as sort keys in order of priority
* @sort_types: (array length=n_sort_fields): An array of #EBookCursorSortTypes, one for each field in
@sort_fields
diff --git a/addressbook/libedata-book/e-book-sqlite.h b/addressbook/libedata-book/e-book-sqlite.h
index 64c8706..3ca220d 100644
--- a/addressbook/libedata-book/e-book-sqlite.h
+++ b/addressbook/libedata-book/e-book-sqlite.h
@@ -188,7 +188,7 @@ typedef enum {
} EbSqlUnlockAction;
/**
- * EbSdbSearchData:
+ * EbSqlSearchData:
* @uid: The %E_CONTACT_UID field of this contact
* @vcard: The the vcard string
* @extra: Any extra data associated to the vcard
diff --git a/addressbook/libedata-book/e-data-book-direct.c b/addressbook/libedata-book/e-data-book-direct.c
index 456095c..7bb9c4e 100644
--- a/addressbook/libedata-book/e-data-book-direct.c
+++ b/addressbook/libedata-book/e-data-book-direct.c
@@ -18,6 +18,20 @@
* Author: Tristan Van Berkom <tristanvb openismus com>
*/
+/**
+ * SECTION: e-data-book-direct
+ * @include: libedata-book/libedata-book.h
+ * @short_description: An interface for implementing Direct Read Access
+ *
+ * This class should be created by an #EBookBackendClass.get_direct_book()
+ * implementation of a backend which supports direct read access.
+ *
+ * This will only be asked of the backend when instantiated on the server
+ * side. If the server side instance of an #EBookBackend does return
+ * an #EDataBookDirect, then a client side instance of the same backend
+ * will be created and #EBookBackendClass.configure_direct() will be
+ * called on the corresponding client side instance.
+ **/
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/addressbook/libedata-book/e-data-book-factory.c b/addressbook/libedata-book/e-data-book-factory.c
index 3ba7214..ba221d8 100644
--- a/addressbook/libedata-book/e-data-book-factory.c
+++ b/addressbook/libedata-book/e-data-book-factory.c
@@ -20,6 +20,15 @@
* Author: Ross Burton <ross linux intel com>
*/
+/**
+ * SECTION: e-data-book-factory
+ * @include: libedata-book/libedata-book.h
+ * @short_description: The main addressbook server object
+ *
+ * This class handles incomming D-Bus connections and creates
+ * the #EDataBook layer for server side addressbooks to communicate
+ * with client side #EBookClient objects.
+ **/
#include <config.h>
#include <locale.h>
#include <stdlib.h>
diff --git a/addressbook/libedata-book/e-data-book-view.c b/addressbook/libedata-book/e-data-book-view.c
index df4970c..8291dd6 100644
--- a/addressbook/libedata-book/e-data-book-view.c
+++ b/addressbook/libedata-book/e-data-book-view.c
@@ -20,6 +20,18 @@
* Author: Ross Burton <ross linux intel com>
*/
+/**
+ * SECTION: e-data-book-view
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A server side object for issuing view notifications
+ *
+ * This class communicates with #EBookClientViews over the bus.
+ *
+ * Addressbook backends can automatically own a number of views requested
+ * by the client, this API can be used by the backend to issue notifications
+ * which will be delivered to the #EBookClientView
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/addressbook/libedata-book/e-data-book.c b/addressbook/libedata-book/e-data-book.c
index 97b04b2..2d9eebd 100644
--- a/addressbook/libedata-book/e-data-book.c
+++ b/addressbook/libedata-book/e-data-book.c
@@ -16,6 +16,15 @@
*
*/
+/**
+ * SECTION: e-data-book
+ * @include: libedata-book/libedata-book.h
+ * @short_description: Server side D-Bus layer to communicate with addressbooks
+ *
+ * This class communicates with #EBookClients over the bus and accesses
+ * an #EBookBackend to satisfy client requests.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -439,6 +448,13 @@ e_data_book_error_quark (void)
/**
* e_data_book_create_error:
+ * @status: #EDataBookStatus code
+ * @custom_msg: Custom message to use for the error. When NULL,
+ * then uses a default message based on the @status code.
+ *
+ * Returns: NULL, when the @status is E_DATA_BOOK_STATUS_SUCCESS,
+ * or a newly allocated GError, which should be freed
+ * with g_error_free() call.
*
* Since: 2.32
**/
@@ -455,6 +471,9 @@ e_data_book_create_error (EDataBookStatus status,
/**
* e_data_book_create_error_fmt:
*
+ * Similar as e_data_book_create_error(), only here, instead of custom_msg,
+ * is used a printf() format to create a custom_msg for the error.
+ *
* Since: 2.32
**/
GError *
diff --git a/addressbook/libedata-book/e-data-book.h b/addressbook/libedata-book/e-data-book.h
index e7d0949..bd4070a 100644
--- a/addressbook/libedata-book/e-data-book.h
+++ b/addressbook/libedata-book/e-data-book.h
@@ -70,25 +70,9 @@ GQuark e_data_book_error_quark (void);
**/
#define E_DATA_BOOK_ERROR e_data_book_error_quark ()
-/**
- * e_data_book_create_error:
- * @status: #EDataBookStatus code
- * @custom_msg: Custom message to use for the error. When NULL,
- * then uses a default message based on the @status code.
- *
- * Returns: NULL, when the @status is E_DATA_BOOK_STATUS_SUCCESS,
- * or a newly allocated GError, which should be freed
- * with g_error_free() call.
- **/
GError * e_data_book_create_error (EDataBookStatus status,
const gchar *custom_msg);
-/**
- * e_data_book_create_error_fmt:
- *
- * Similar as e_data_book_create_error(), only here, instead of custom_msg,
- * is used a printf() format to create a custom_msg for the error.
- **/
GError * e_data_book_create_error_fmt (EDataBookStatus status,
const gchar *custom_msg_fmt,
...) G_GNUC_PRINTF (2, 3);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
