New file. New file. New file. New file. New file. :-)

1999-12-13  Nat Friedman  <nat@helixcode.com>

	* ebook/e-book.h: New file.
	* ebook/e-book.c: New file.
	* ebook/e-card.h: New file.
	* ebook/e-card-fields.h: New file.
	* ebook/e-commerce.h: New file. :-)

svn path=/trunk/; revision=1486

5 files changed, 384 insertions, 0 deletions

diff --git a/ebook/e-book.c b/ebook/e-book.c
new file mode 100644
index 0000000000..4230394904
--- /dev/null
+++ b/ebook/e-book.c
@@ -0,0 +1,195 @@
+/*
+ * The Evolution addressbook client object.
+ *
+ * Author:
+ *   Nat Friedman (nat@helixcode.com)
+ *
+ * Copyright 1999, Helix Code, Inc.
+ */
+
+#include <ebook/e-book.h>
+
+/**
+ * e_book_new:
+ * @uri: A URI string describing the location of the backend
+ * which the new #EBook will use.
+ *
+ * Returns: A new #EBook object, bound to the backend specified
+ * by @uri, or %NULL if an error occurs.
+ */
+EBook *
+e_book_new (const char *uri)
+{
+	e_book_get_card (
+}
+
+/**
+ * e_book_get_type:
+ *
+ * Returns: The #GtkType for #EBook.
+ */
+GtkType
+e_book_get_type (void)
+{
+}
+
+/**
+ * e_book_get_card:
+ * @book: An #EBook object.
+ * @id: A unique ID which specified a card stored inside
+ * @book's backend store.
+ *
+ * This function fetches the card specified by @id from @book's
+ * backend, parses it into a new #ECard object, and returns it.
+ *
+ * Returns: A newly created #ECard, filled with the card data
+ * specified by @id.  The #EBook may maintain an internal card cache,
+ * and will therefore hold a reference to each #ECard itself.  The
+ * reference count on the returned #ECard will be incremented when the
+ * card is returned.  When the client wishes to destroy the returned
+ * #ECard, he should just dereference it.
+ */
+ECard *
+e_book_get_card (EBook *book, const char *id)
+{
+}
+
+/**
+ * e_book_get_cards:
+ * @book: An #EBook object.
+ *
+ * Returns: A #GList of all the #ECards stored in @book's backend.
+ * The #GList is newly-allocated for the client and must be freed by
+ * him.  The #ECard objects in the #GList are each referenced, and
+ * must be unreferenced when the client is done using them.
+ */
+GList *
+e_book_get_cards (EBook *book)
+{
+}
+
+/**
+ * e_book_get_ids:
+ * @book: An #EBook object.
+ *
+ * Returns: A #GList of all the unique card ID strings stored in
+ * @book's backend.  The #GList is newly-allocated, as are all of the
+ * #ECard objects stored in it.  The client must free the #GList and
+ * unreference all fo the cards when he is done with them.
+ */
+GList *
+e_book_get_ids (EBook *book)
+{
+}
+
+/**
+ * e_book_sync_card:
+ * @book: An #EBook object.
+ * @card: A dirty #ECard object.
+ *
+ * Writes all the changes in @card into @book's card store.
+ */
+void
+e_book_sync_card (EBook *book)
+{
+}
+
+/**
+ * e_book_update_card:
+ * @book: An #EBook object.
+ * @card: An #ECard object which has become out-of-date
+ * and no longer contains the most current card data
+ * in @book's card store.
+ *
+ * Updates @card with any changes which may have occured in its
+ * corresponding backend data.
+ */
+void
+e_book_update_card (EBook *book, ECard *card)
+{
+}
+
+/**
+ * e_book_add_card:
+ * @book: An #EBook object.
+ * @card: A newly-created ECard object.
+ *
+ * Adds @card to @book's card store.  Creates a unique ID for @card
+ * and sets @card's ID field.  This action will cause a #card_added
+ * signal to be raised on @book.
+ *
+ * Returns: The newly-created unique ID for @card.  The copy
+ * returned is the same copy which is stored in @card.  The #EBook
+ * may reference @card and keep a handle to it.
+ */
+const char *
+e_book_add_card (EBook *book, ECard *card)
+{
+}
+
+/**
+ * e_book_remove_card:
+ * @book: An #EBook object.
+ * @id: A unique ID for a card stored in @book.
+ *
+ * Removes the card specified by @id from @book's card store.  If the
+ * client has kept around an old #ECard object for the card being
+ * removed, he will have to remove it himself.  The #ECard will not
+ * receive a #card_removed signals.  A #card_removed signal will be
+ * raised on @book, the card will be removed from the #EBook card
+ * cache, and the corresponding #ECard's reference count will be
+ * decremented.
+ */
+void
+e_book_remove_card (EBook *book, const char *id)
+{
+}
+
+/**
+ * e_book_complete:
+ * @book: An #EBook object.
+ * @str: A string.
+ *
+ * The purpose of this function is to provide an easy way for the
+ * client application to to implement typing completion in its address
+ * entry dialogs.  The #EBook will compute a list of cards which
+ * potentially complete @str.  The basis for the completion (address,
+ * nickname, etc) is implementation-dependent, and I may add some
+ * configurability to this later.
+ * 
+ * Returns: A list of #ECard objects which are potentially what the
+ * user was getting at when he typed @str.  The list is sorted in
+ * descending order of likelihood.  The returned #GList must be freed
+ * by the client.  The #ECard objects in the #GList may have come from
+ * @book's cache, and the client may already hold other references to
+ * them.  For this reason, the reference count on each #ECard object
+ * is incremented when the object is returned.
+ */
+GList *
+e_book_complete (EBook *book, const char *str)
+{
+}       
+
+/**
+ * e_book_get_name:
+ * @book: An #EBook object.
+ *
+ * Returns: The name of the card store to which @book is bound.
+ * The returned string must be freed by the client.
+ */
+char *
+e_book_get_name (EBook *book)
+{
+}
+
+/**
+ * e_book_set_name:
+ * @book: An #EBook object.
+ * @name: A string containing a new name for @book.
+ *
+ * Sets @book's name to @name.
+ */
+char *
+e_book_set_name (EBook *book, const char *namen)
+{
+}
diff --git a/ebook/e-book.h b/ebook/e-book.h
new file mode 100644
index 0000000000..0aab676e65
--- /dev/null
+++ b/ebook/e-book.h
@@ -0,0 +1,60 @@
+/*
+ * The Evolution addressbook client object.
+ *
+ * Author:
+ *   Nat Friedman (nat@helixcode.com)
+ *
+ * Copyright 1999, Helix Code, Inc.
+ */
+
+#ifndef __E_BOOK_H__
+#define __E_BOOK_H__
+
+typedef struct {
+	GtkObject     parent;
+	EBookPrivate *priv;
+} EBook;
+
+typedef struct {
+	GtkObjectClass parent;
+
+	/*
+	 * Signals.
+	 */
+	void (card_changed *) (const char *id);
+	void (card_removed *) (const char *id);
+	void (card_added *)   (const char *id);
+} EBookClass;
+
+/* Creating a new addressbook. */
+EBook      *e_book_new          (const char *uri);
+GtkType     e_book_get_type     (void);
+
+/* Fetching cards and card IDs out of the addressbook. */
+ECard      *e_book_get_card     (EBook      *book,
+				 const char *id);
+GList      *e_book_get_cards    (EBook      *book);
+GList      *e_book_get_ids      (EBook      *book);
+
+/* Getting/putting card changes. */
+void        e_book_sync_card    (EBook      *book,
+				 ECard      *card);
+void        e_book_update_card  (EBook      *book,
+				 ECard      *card);
+
+/* Adding and deleting cards. */
+const char *e_book_add_card     (EBook      *book,
+				 ECard      *card);
+void        e_book_remove_card  (EBook      *book,
+				 const char *id);
+
+/* Typing completion... */
+GList      *e_book_complete     (EBook      *book,
+				 const char *str);
+
+/* Information about this addresbook. */
+char       *e_book_get_name     (EBook      *book);
+void        e_book_set_name     (EBook      *book,
+				 const char *name);
+
+#endif /* ! __E_BOOK_H__ */
diff --git a/ebook/e-card-fields.h b/ebook/e-card-fields.h
new file mode 100644
index 0000000000..c1822ca981
--- /dev/null
+++ b/ebook/e-card-fields.h
@@ -0,0 +1,53 @@
+/*
+ * ECard field type definitions.
+ *
+ * Author:
+ *   Nat Friedman (nat@helixcode.com)
+ *
+ * Copyright 1999, Helix Code, Inc.
+ */
+
+#ifndef __E_CARD_FIELDS_H__
+#define __E_CARD_FIELDS_H__
+
+typedef struct {
+	int year;
+	int month;
+	int day;
+} ECardDate;
+
+typedef struct {
+	char *addr;
+
+	char *desc;
+	char *id;
+} ECardEmail;
+
+typedef struct {
+	char *addr1;
+	char *addr2;
+	char *city;
+	char *postcode;
+	char *region;
+	char *country;
+
+	char *desc;
+	char *id;
+} ECardAddress;
+
+typedef struct {
+	char *phone;
+
+	char *desc;
+	char *id;
+} ECardPhone;
+
+typedef struct {
+	char *url;
+
+	char *desc;
+	char *id;
+} ECardURL;
+
+#endif /* ! __E_CARD_FIELDS_H__ */
+ 
diff --git a/ebook/e-card.h b/ebook/e-card.h
new file mode 100644
index 0000000000..4778b62e2c
--- /dev/null
+++ b/ebook/e-card.h
@@ -0,0 +1,61 @@
+/*
+ * The Evolution addressbook card object.
+ *
+ * Author:
+ *   Nat Friedman (nat@helixcode.com)
+ *
+ * Copyright 1999, Helix Code, Inc.
+ */
+
+#ifndef __E_CARD_H__
+#define __E_CARD_H__
+
+#include <ebook/e-card-fields.h>
+
+typedef enum {
+} ECardDirtyFlags;
+
+typedef struct _ECardPrivate ECardPrivate;
+
+typedef struct {
+	GtkObject     parent;
+	ECardPrivate *priv;
+} ECard;
+
+typedef struct {
+	GtkObjectClass parent;
+
+	/*
+	 * Signals.
+	 */
+	void (changed *) (ECardDirtyFlags dirty);
+} ECardClass;
+
+
+ECard        *e_card_new             (void);
+GtkType       e_card_get_type        (void);
+
+/* Name */
+char         *e_card_get_full_name   (ECard *card);
+
+/* Email */
+GList        *e_card_get_emails      (ECard *card);
+ECardEmail   *e_card_get_email       (ECard *card);
+
+/* Snail mail */
+GList        *e_card_get_addresses   (ECard *card);
+ECardAddress *e_card_get_address     (ECard *card);
+
+/* Telephone */
+GList        *e_card_get_phones      (ECard *card);
+ECardPhone   *e_card_get_phone       (Ecard *card);
+
+/* Title, position, groups */
+char         *e_card_get_title       (ECard *card);
+GList        *e_card_get_categories  (ECard *card);
+
+/* Home page, other URLs associated with this person */
+GList        *e_card_get_urls        (ECard *card);
+ECardURL     *e_card_get_url         (ECard *card);
+
+#endif /* ! __E_CARD_H__ */
diff --git a/ebook/e-commerce.h b/ebook/e-commerce.h
new file mode 100644
index 0000000000..788bad0be4
--- /dev/null
+++ b/ebook/e-commerce.h
@@ -0,0 +1,15 @@
+#ifndef __E_COMMERCE_H__
+#define __E_COMMERCE_H__
+
+typedef {
+	GtkObject parent;
+} ECommerce;
+
+typedef {
+	GtkObjectClass parent;
+} ECommerceClass;
+
+ECommerce *e_commerce_new (void)
+
+#endif /* ! __E_COMMERCE_H__ */
+