+2006-05-24 Ross Burton <ross@burtonini.com>
+
+ * docs/reference/addressbook/libebook/tmpl/e-book-view-listener.sgml:
+ * docs/reference/addressbook/libebook/tmpl/e-book-view.sgml:
+ * docs/reference/addressbook/libebook/tmpl/e-book.sgml:
+ Update for doc changes.
+
2006-05-22 Harish Krishnaswamy <kharish@novell.com>
* configure.in: Update intltool requirements.
+2006-05-24 Ross Burton <ross@burtonini.com>
+
+ * libebook/e-book-view.c:
+ * libebook/e-book.c:
+ * libebook/e-vcard.c:
+ Add more API documentation (#342678)
+
2006-05-15 Harish Krishnaswamy <kharish@novell.com>
* libebook/e-vcard.[ch]: Restore the two functions removed from the
* @corba_book_view: a CORBA BookView object
* @listener: an #EBookViewListener
*
- * Creates a new #EBookView based on @corba_book_view and listening to @listener.
+ * Creates a new #EBookView based on @corba_book_view and listening to
+ * @listener. This is a private function, applications should call
+ * #e_book_get_book_view or #e_book_async_get_book_view.
*
* Return value: A new #EBookView.
**/
return book_view->priv->book;
}
+
/**
* e_book_view_start:
* @book_view: an #EBookView
*
* Tells @book_view to start processing events.
- **/
+ */
void
e_book_view_start (EBookView *book_view)
{
/**
* e_book_async_remove_contacts:
* @book: an #EBook
- * @ids: an #GList of const char *id's
+ * @ids: a #GList of const char *id's
* @cb: a function to call when the operation finishes
* @closure: data to pass to callback function
*
* Removes the contacts with ids from the list @ids from @book. This is
- * always more efficient than calling e_book_remove_contact_by_id if you
+ * always more efficient than calling e_book_remove_contact_by_id() if you
* have more than one id to remove, as some backends can implement it
* as a batch request.
*
}
}
+/**
+ * e_book_get_changes:
+ * @book: an #EBook
+ * @changeid: the change ID
+ * @changes: return location for a #GList of #EBookChange items
+ * @error: a #GError to set on failure.
+ *
+ * Get the set of changes since the previous call to #e_book_get_changes for a
+ * given change ID.
+ *
+ * Return value: TRUE on success, FALSE otherwise
+ */
gboolean
e_book_get_changes (EBook *book,
char *changeid,
g_mutex_unlock (book->priv->mutex);
}
+/**
+ * e_book_free_change_list:
+ * @change_list: a #GList of #EBookChange items
+ *
+ * Free the contents of #change_list, and the list itself.
+ */
void
e_book_free_change_list (GList *change_list)
{
\f
/**
* e_book_new:
- *
* @source: An #ESource pointer
* @error: A #GError pointer
*
/**
* e_book_new_from_uri:
- *
* @uri: the URI to load
* @error: A #GError pointer
*
/**
* e_book_new_system_addressbook:
- *
- * @uri: the URI to load
* @error: A #GError pointer
*
* Creates a new #EBook corresponding to the user's system
/**
* e_book_new_default_addressbook:
- *
- * @uri: the URI to load
* @error: A #GError pointer
*
* Creates a new #EBook corresponding to the user's default
-/** Skip newline characters and return the next character.
+/* Skip newline characters and return the next character.
* This function takes care of folding lines, skipping
* newline characters if found, taking care of equal characters
* and other strange things.
<!-- ##### FUNCTION e_book_view_listener_new ##### -->
<para>
-Creation function.
+
</para>
@Returns:
+<!-- ##### FUNCTION e_book_view_listener_start ##### -->
+<para>
+
+</para>
+
+@listener:
+
+
<!-- ##### FUNCTION e_book_view_listener_stop ##### -->
<para>
-Stops the listener.
+
</para>
@listener:
EBookView
<!-- ##### SECTION Short_Description ##### -->
-Represents a search against an EBook.
+Represents a search against an #EBook.
<!-- ##### SECTION Long_Description ##### -->
<para>
-Event notifications and callbacks from EBookView go to the
-#e-book-view-listener. Contrast EBookView with #e-book, which represents the
+Event notifications and callbacks from #EBookView go to the
+#EBookViewListener. Contrast #EBookView with #EBook, which represents the
addressbook itself.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-#e-book-view-listener, #e-book
+#EBookViewListener, #EBook.
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT EBookView ##### -->
<para>
-
+#EBookView has no publicly available members.
</para>
</para>
@ebookview: the object which received the signal.
-@arg1:
+@arg1: a #GList of #EContact objects that were added to the view
<!-- ##### SIGNAL EBookView::contacts-changed ##### -->
<para>
-
+Fired when contacts are changed. Each contact in the list will be unref'd
+when done, and the list freed, so simply reference any contacts you want to
+keep.
</para>
@ebookview: the object which received the signal.
-@arg1:
+@arg1: a #GList of #EContact objects that were modified
<!-- ##### SIGNAL EBookView::contacts-removed ##### -->
<para>
-
+Fired when contacts are removed from the view. The IDs and the list will be
+freed, so copy any IDs you want to keep.
</para>
@ebookview: the object which received the signal.
-@arg1:
+@arg1: a #GList of contact IDs (char*) that were removed from the view
<!-- ##### SIGNAL EBookView::sequence-complete ##### -->
<para>
-
+Fired when there are currently no more contacts to send. This is fired once
+after the initial set of #contacts-added signals, and after every future change.
</para>
@ebookview: the object which received the signal.
-@arg1:
+@arg1: an #EBookViewStatus
<!-- ##### SIGNAL EBookView::status-message ##### -->
<para>
-
+Fired with a status message reporting the progress of the view.
</para>
@ebookview: the object which received the signal.
-@arg1:
+@arg1: a const char* message
<!-- ##### FUNCTION e_book_view_new ##### -->
<para>
<!-- ##### SECTION Long_Description ##### -->
<para>
Represents a complete addressbook. Event notifications and callbacks go to the
-#e-book-listener. Contrast with #e-book-view, which represents a search of the addressbook.
+#EBookListener. Contrast with #EBookView, which represents a search of the addressbook.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-#e-book-listener, #e-book-view
+#EBookView
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SIGNAL EBook::auth-required ##### -->
<para>
-
+Authentication is required to access this source. You should call
+#e_book_authenticate_user or #e_book_async_authenticate_user.
</para>
@ebook: the object which received the signal.
<!-- ##### SIGNAL EBook::connection-status ##### -->
<para>
-
+The connection status for this book is being reported.
</para>
@ebook: the object which received the signal.
-@arg1:
+@arg1: #TRUE if the connection is online, #FALSE otherwise.
<!-- ##### SIGNAL EBook::writable-status ##### -->
<para>
-
+The writable status for this book is being reported.
</para>
@ebook: the object which received the signal.
-@arg1:
+@arg1: #TRUE if the book is writable, #FALSE otherwise.
<!-- ##### FUNCTION e_book_new ##### -->
<para>