contacts: Add support for the “file as” property

Add support for “file as” strings on contacts, specifying their sort order
if they have non-Western-style names or names which are otherwise incorrectly
sorted in the contact list.

The following API has been added:
 • GDataContactsContact:file-as
 • gdata_contacts_contact_[get|set]_file_as()

This includes basic test coverage of the new code.

Helps: bgo#661033

5 files changed, 94 insertions, 5 deletions

diff --git a/docs/reference/gdata-sections.txt b/docs/reference/gdata-sections.txt
index 049422b0..d0867294 100644
--- a/docs/reference/gdata-sections.txt
+++ b/docs/reference/gdata-sections.txt
@@ -362,6 +362,8 @@ gdata_contacts_contact_get_maiden_name
 gdata_contacts_contact_set_maiden_name
 gdata_contacts_contact_get_nickname
 gdata_contacts_contact_set_nickname
+gdata_contacts_contact_get_file_as
+gdata_contacts_contact_set_file_as
 gdata_contacts_contact_get_birthday
 gdata_contacts_contact_set_birthday
 gdata_contacts_contact_get_gender
diff --git a/gdata/gdata.symbols b/gdata/gdata.symbols
index 044f41cf..939eb4e7 100644
--- a/gdata/gdata.symbols
+++ b/gdata/gdata.symbols
@@ -938,3 +938,5 @@ gdata_youtube_video_get_media_rating
 gdata_documents_entry_get_resource_id
 gdata_youtube_query_get_license
 gdata_youtube_query_set_license
+gdata_contacts_contact_get_file_as
+gdata_contacts_contact_set_file_as
diff --git a/gdata/services/contacts/gdata-contacts-contact.c b/gdata/services/contacts/gdata-contacts-contact.c
index 19c9c029..b72b6ecc 100644
--- a/gdata/services/contacts/gdata-contacts-contact.c
+++ b/gdata/services/contacts/gdata-contacts-contact.c
@@ -1,7 +1,7 @@
 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 /*
  * GData Client
- * Copyright (C) Philip Withnall 2009–2010 <philip@tecnocode.co.uk>
+ * Copyright (C) Philip Withnall 2009, 2010, 2011 <philip@tecnocode.co.uk>
  *
  * GData Client is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -189,6 +189,7 @@ struct _GDataContactsContactPrivate {
 	gchar *photo_etag;
 	GList *jots; /* GDataGContactJot */
 	gchar *nickname;
+	gchar *file_as;
 	GDate birthday;
 	gboolean birthday_has_year; /* contacts can choose to just give the month and day of their birth */
 	GList *relations; /* GDataGContactRelation */
@@ -229,7 +230,8 @@ enum {
 	PROP_SENSITIVITY,
 	PROP_SHORT_NAME,
 	PROP_SUBJECT,
-	PROP_PHOTO_ETAG
+	PROP_PHOTO_ETAG,
+	PROP_FILE_AS,
 };
 
 G_DEFINE_TYPE (GDataContactsContact, gdata_contacts_contact, GDATA_TYPE_ENTRY)
@@ -325,6 +327,19 @@ gdata_contacts_contact_class_init (GDataContactsContactClass *klass)
 	                                                      G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
 	/**
+	 * GDataContactsContact:file-as:
+	 *
+	 * The name to file the contact under for sorting purposes.
+	 *
+	 * Since: 0.11.0
+	 */
+	g_object_class_install_property (gobject_class, PROP_FILE_AS,
+	                                 g_param_spec_string ("file-as",
+	                                                      "File As", "The name to file the contact under for sorting purposes.",
+	                                                      NULL,
+	                                                      G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
 	 * GDataContactsContact:birthday:
 	 *
 	 * The contact's birthday.
@@ -616,6 +631,7 @@ gdata_contacts_contact_finalize (GObject *object)
 	g_hash_table_destroy (priv->groups);
 	g_free (priv->photo_etag);
 	g_free (priv->nickname);
+	g_free (priv->file_as);
 	g_free (priv->billing_information);
 	g_free (priv->directory_server);
 	g_free (priv->gender);
@@ -658,6 +674,9 @@ gdata_contacts_contact_get_property (GObject *object, guint property_id, GValue
 		case PROP_NICKNAME:
 			g_value_set_string (value, priv->nickname);
 			break;
+		case PROP_FILE_AS:
+			g_value_set_string (value, priv->file_as);
+			break;
 		case PROP_BIRTHDAY:
 			g_value_set_boxed (value, &(priv->birthday));
 			break;
@@ -716,6 +735,9 @@ gdata_contacts_contact_set_property (GObject *object, guint property_id, const G
 		case PROP_NICKNAME:
 			gdata_contacts_contact_set_nickname (self, g_value_get_string (value));
 			break;
+		case PROP_FILE_AS:
+			gdata_contacts_contact_set_file_as (self, g_value_get_string (value));
+			break;
 		case PROP_BIRTHDAY:
 			gdata_contacts_contact_set_birthday (self, g_value_get_boxed (value), self->priv->birthday_has_year);
 			break;
@@ -852,6 +874,7 @@ parse_xml (GDataParsable *parsable, xmlDoc *doc, xmlNode *node, gpointer user_da
 		    gdata_parser_object_from_element_setter (node, "language", P_REQUIRED, GDATA_TYPE_GCONTACT_LANGUAGE,
 		                                             gdata_contacts_contact_add_language, self, &success, error) == TRUE ||
 		    gdata_parser_string_from_element (node, "nickname", P_REQUIRED | P_NO_DUPES, &(self->priv->nickname), &success, error) == TRUE ||
+		    gdata_parser_string_from_element (node, "fileAs", P_REQUIRED | P_NO_DUPES, &(self->priv->file_as), &success, error) == TRUE ||
 		    gdata_parser_string_from_element (node, "billingInformation", P_REQUIRED | P_NO_DUPES | P_NON_EMPTY,
 		                                      &(self->priv->billing_information), &success, error) == TRUE ||
 		    gdata_parser_string_from_element (node, "directoryServer", P_REQUIRED | P_NO_DUPES | P_NON_EMPTY,
@@ -1094,6 +1117,11 @@ get_xml (GDataParsable *parsable, GString *xml_string)
 	if (priv->nickname != NULL)
 		gdata_parser_string_append_escaped (xml_string, "<gContact:nickname>", priv->nickname, "</gContact:nickname>");
 
+	/* gContact:fileAs */
+	if (priv->file_as != NULL) {
+		gdata_parser_string_append_escaped (xml_string, "<gContact:fileAs>", priv->file_as, "</gContact:fileAs>");
+	}
+
 	/* gContact:birthday */
 	if (g_date_valid (&(priv->birthday)) == TRUE) {
 		if (priv->birthday_has_year == TRUE) {
@@ -1311,6 +1339,44 @@ gdata_contacts_contact_set_nickname (GDataContactsContact *self, const gchar *ni
 }
 
 /**
+ * gdata_contacts_contact_get_file_as:
+ * @self: a #GDataContactsContact
+ *
+ * Gets the #GDataContactsContact:file-as property.
+ *
+ * Return value: the name the contact's filed under, or %NULL
+ *
+ * Since: 0.11.0
+ */
+const gchar *
+gdata_contacts_contact_get_file_as (GDataContactsContact *self)
+{
+	g_return_val_if_fail (GDATA_IS_CONTACTS_CONTACT (self), NULL);
+	return self->priv->file_as;
+}
+
+/**
+ * gdata_contacts_contact_set_file_as:
+ * @self: a #GDataContactsContact
+ * @file_as: (allow-none): the new name to file the contact under, or %NULL
+ *
+ * Sets the #GDataContactsContact:file-as property to @file_as.
+ *
+ * If @file_as is %NULL, the contact will be filed under their full name.
+ *
+ * Since: 0.7.0
+ **/
+void
+gdata_contacts_contact_set_file_as (GDataContactsContact *self, const gchar *file_as)
+{
+	g_return_if_fail (GDATA_IS_CONTACTS_CONTACT (self));
+
+	g_free (self->priv->file_as);
+	self->priv->file_as = g_strdup (file_as);
+	g_object_notify (G_OBJECT (self), "file-as");
+}
+
+/**
  * gdata_contacts_contact_get_birthday:
  * @self: a #GDataContactsContact
  * @birthday: (allow-none) (out caller-allocates): return location for the birthday, or %NULL
diff --git a/gdata/services/contacts/gdata-contacts-contact.h b/gdata/services/contacts/gdata-contacts-contact.h
index e335a9cf..0f91f342 100644
--- a/gdata/services/contacts/gdata-contacts-contact.h
+++ b/gdata/services/contacts/gdata-contacts-contact.h
@@ -1,7 +1,7 @@
 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 /*
  * GData Client
- * Copyright (C) Philip Withnall 2009–2010 <philip@tecnocode.co.uk>
+ * Copyright (C) Philip Withnall 2009, 2010, 2011 <philip@tecnocode.co.uk>
  *
  * GData Client is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -167,6 +167,9 @@ void gdata_contacts_contact_set_name (GDataContactsContact *self, GDataGDName *n
 const gchar *gdata_contacts_contact_get_nickname (GDataContactsContact *self) G_GNUC_PURE;
 void gdata_contacts_contact_set_nickname (GDataContactsContact *self, const gchar *nickname);
 
+const gchar *gdata_contacts_contact_get_file_as (GDataContactsContact *self) G_GNUC_PURE;
+void gdata_contacts_contact_set_file_as (GDataContactsContact *self, const gchar *file_as);
+
 gboolean gdata_contacts_contact_get_birthday (GDataContactsContact *self, GDate *birthday) G_GNUC_PURE;
 void gdata_contacts_contact_set_birthday (GDataContactsContact *self, GDate *birthday, gboolean birthday_has_year);
 
diff --git a/gdata/tests/contacts.c b/gdata/tests/contacts.c
index 8a8acdf5..518aa9eb 100644
--- a/gdata/tests/contacts.c
+++ b/gdata/tests/contacts.c
@@ -1,7 +1,7 @@
 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 /*
  * GData Client
- * Copyright (C) Philip Withnall 2009–2010 <philip@tecnocode.co.uk>
+ * Copyright (C) Philip Withnall 2009, 2010, 2011 <philip@tecnocode.co.uk>
  *
  * GData Client is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -319,6 +319,7 @@ test_contact_insert (InsertData *data, gconstpointer service)
 	g_object_unref (name2);
 
 	gdata_contacts_contact_set_nickname (contact, "Big J");
+	gdata_contacts_contact_set_file_as (contact, "J, Big");
 	g_date_set_dmy (&date, 1, 1, 1900);
 	gdata_contacts_contact_set_birthday (contact, &date, FALSE);
 	gdata_entry_set_content (GDATA_ENTRY (contact), "Notes");
@@ -419,6 +420,7 @@ test_contact_insert (InsertData *data, gconstpointer service)
 
 	/* Various properties */
 	g_assert_cmpstr (gdata_contacts_contact_get_nickname (new_contact), ==, "Big J");
+	g_assert_cmpstr (gdata_contacts_contact_get_file_as (new_contact), ==, "J, Big");
 	g_assert (gdata_contacts_contact_get_birthday (new_contact, &date) == FALSE);
 	g_assert (g_date_valid (&date) == TRUE);
 	g_assert_cmpuint (g_date_get_month (&date), ==, 1);
@@ -788,7 +790,7 @@ test_contact_properties (void)
 	GDataGContactCalendar *calendar;
 	GDataGContactExternalID *external_id;
 	GDataGContactLanguage *language;
-	gchar *nickname, *billing_information, *directory_server, *gender, *initials, *maiden_name, *mileage, *occupation;
+	gchar *nickname, *file_as, *billing_information, *directory_server, *gender, *initials, *maiden_name, *mileage, *occupation;
 	gchar *priority, *sensitivity, *short_name, *subject, *photo_etag;
 	GDate date, *date2;
 	GTimeVal current_time;
@@ -816,6 +818,7 @@ test_contact_properties (void)
 	g_assert_cmpstr (gdata_entry_get_title (GDATA_ENTRY (contact)), ==, "John Smith");
 
 	gdata_contacts_contact_set_nickname (contact, "Big J");
+	gdata_contacts_contact_set_file_as (contact, "J, Big");
 	g_date_set_dmy (&date, 1, 1, 1900);
 	gdata_contacts_contact_set_birthday (contact, &date, FALSE);
 	gdata_entry_set_content (GDATA_ENTRY (contact), "Notes");
@@ -908,6 +911,7 @@ test_contact_properties (void)
 	              "photo-etag", &photo_etag,
 	              "name", &name,
 	              "nickname", &nickname,
+	              "file-as", &file_as,
 	              "birthday", &date2,
 	              "birthday-has-year", &birthday_has_year,
 	              "billing-information", &billing_information,
@@ -928,6 +932,7 @@ test_contact_properties (void)
 	g_assert (photo_etag == NULL);
 	g_assert (name2 == name);
 	g_assert_cmpstr (nickname, ==, "Big J");
+	g_assert_cmpstr (file_as, ==, "J, Big");
 	g_assert (g_date_valid (date2) == TRUE);
 	g_assert_cmpuint (g_date_get_month (date2), ==, 1);
 	g_assert_cmpuint (g_date_get_day (date2), ==, 1);
@@ -947,6 +952,7 @@ test_contact_properties (void)
 	g_object_unref (name2);
 	g_free (date2);
 	g_free (nickname);
+	g_free (file_as);
 	g_free (billing_information);
 	g_free (directory_server);
 	g_free (gender);
@@ -1002,6 +1008,7 @@ test_contact_properties (void)
 			"<gContact:userDefinedField key='' value='Foo'/>" /* bgo#648058 */
 			"<gContact:hobby>Rowing</gContact:hobby>"
 			"<gContact:nickname>Big J</gContact:nickname>"
+			"<gContact:fileAs>J, Big</gContact:fileAs>"
 			"<gContact:birthday when='--01-01'/>"
 			"<gContact:billingInformation>Big J Enterprises, Ltd.</gContact:billingInformation>"
 			"<gContact:directoryServer>This is a server</gContact:directoryServer>"
@@ -1071,6 +1078,7 @@ test_contact_escaping (void)
 
 	contact = gdata_contacts_contact_new (NULL);
 	gdata_contacts_contact_set_nickname (contact, "Nickname & stuff");
+	gdata_contacts_contact_set_file_as (contact, "Stuff, & Nickname");
 	gdata_contacts_contact_set_billing_information (contact, "Billing information & stuff");
 	gdata_contacts_contact_set_directory_server (contact, "http://foo.com?foo&bar");
 	gdata_contacts_contact_set_gender (contact, "Misc. & other");
@@ -1102,6 +1110,7 @@ test_contact_escaping (void)
 			"<gContact:groupMembershipInfo href='http://foo.com?foo&amp;bar'/>"
 			"<gContact:hobby>Escaping &amp;s</gContact:hobby>"
 			"<gContact:nickname>Nickname &amp; stuff</gContact:nickname>"
+			"<gContact:fileAs>Stuff, &amp; Nickname</gContact:fileAs>"
 			"<gContact:billingInformation>Billing information &amp; stuff</gContact:billingInformation>"
 			"<gContact:directoryServer>http://foo.com?foo&amp;bar</gContact:directoryServer>"
 			"<gContact:gender value='Misc. &amp; other'/>"
@@ -1287,6 +1296,7 @@ test_contact_parser_minimal (void)
 	/* TODO: Check the other properties */
 
 	g_assert (gdata_contacts_contact_get_nickname (contact) == NULL);
+	g_assert (gdata_contacts_contact_get_file_as (contact) == NULL);
 	g_assert (gdata_contacts_contact_get_birthday (contact, &birthday) == FALSE);
 	g_assert (g_date_valid (&birthday) == FALSE);
 	g_assert (gdata_contacts_contact_get_billing_information (contact) == NULL);
@@ -1346,6 +1356,7 @@ test_contact_parser_normal (void)
 			"<gContact:groupMembershipInfo href='http://www.google.com/feeds/contacts/groups/jo%40gmail.com/base/1234b'/>"
 			"<gd:deleted/>"
 			"<gContact:nickname>Agent Smith</gContact:nickname>"
+			"<gContact:fileAs>Smith, Agent</gContact:fileAs>"
 			"<gContact:birthday when='2010-12-03'/>"
 			"<gContact:billingInformation>Foo &amp; Bar Inc.</gContact:billingInformation>"
 			"<gContact:directoryServer>Directory &amp; server</gContact:directoryServer>"
@@ -1387,6 +1398,7 @@ test_contact_parser_normal (void)
 	/* TODO: Check the other properties */
 
 	g_assert_cmpstr (gdata_contacts_contact_get_nickname (contact), ==, "Agent Smith");
+	g_assert_cmpstr (gdata_contacts_contact_get_file_as (contact), ==, "Smith, Agent");
 	g_assert_cmpstr (gdata_contacts_contact_get_billing_information (contact), ==, "Foo & Bar Inc.");
 	g_assert_cmpstr (gdata_contacts_contact_get_directory_server (contact), ==, "Directory & server");
 	g_assert_cmpstr (gdata_contacts_contact_get_gender (contact), ==, GDATA_CONTACTS_GENDER_FEMALE);
@@ -1592,6 +1604,10 @@ test_contact_parser_error_handling (void)
 	TEST_XML_ERROR_HANDLING ("<gContact:nickname/>"); /* missing content */
 	TEST_XML_ERROR_HANDLING ("<gContact:nickname>Nickname 1</gContact:nickname><gContact:nickname>Duplicate!</gContact:nickname>"); /* duplicate */
 
+	/* gContact:fileAs */
+	TEST_XML_ERROR_HANDLING ("<gContact:fileAs/>"); /* missing content */
+	TEST_XML_ERROR_HANDLING ("<gContact:fileAs>File As 1</gContact:fileAs><gContact:fileAs>Duplicate!</gContact:fileAs>"); /* duplicate */
+
 	/* gContact:birthday */
 	TEST_XML_ERROR_HANDLING ("<gContact:birthday/>"); /* missing "when" attribute */
 	TEST_XML_ERROR_HANDLING ("<gContact:birthday when='foobar'/>"); /* invalid date */