[libgdata] calendar: Add a code example for calendar ACLs

[Philip Withnall <pwithnall src gnome org>]

commit 61927f8f0ad6c0e819fadf88637ae94d4fba0aef
Author: Philip Withnall <philip tecnocode co uk>
Date:   Thu Dec 30 10:04:51 2010 +0000

    calendar: Add a code example for calendar ACLs
    
    Helps: bgo#579885

 gdata/services/calendar/gdata-calendar-service.c |   97 ++++++++++++++++++++++
 1 files changed, 97 insertions(+), 0 deletions(-)
---
diff --git a/gdata/services/calendar/gdata-calendar-service.c b/gdata/services/calendar/gdata-calendar-service.c
index fda7746..6c8157c 100644
--- a/gdata/services/calendar/gdata-calendar-service.c
+++ b/gdata/services/calendar/gdata-calendar-service.c
@@ -28,6 +28,103 @@
  *
  * For more details of Google Calendar's GData API, see the <ulink type="http" url="http://code.google.com/apis/calendar/docs/2.0/reference.html";>
  * online documentation</ulink>.
+ *
+ * Each calendar accessible through the service has an access control list (ACL) which defines the level of access to the calendar to each user, and
+ * which users the calendar is shared with. For more information about ACLs for calendars, see the
+ * <ulink type="http" url="http://code.google.com/apis/calendar/data/2.0/developers_guide_protocol.html#SharingACalendar";>online documentation on
+ * sharing calendars</ulink>.
+ *
+ * <example>
+ * 	<title>Retrieving the Access Control List for a Calendar</title>
+ * 	<programlisting>
+ *	GDataCalendarService *service;
+ *	GDataCalendarCalendar *calendar;
+ *	GDataFeed *acl_feed;
+ *	GDataAccessRule *rule, *new_rule;
+ *	GDataLink *acl_link;
+ *	GList *i;
+ *	GError *error = NULL;
+ *
+ *	/<!-- -->* Create a service and retrieve a calendar to work on *<!-- -->/
+ *	service = create_calendar_service ();
+ *	calendar = get_calendar (service);
+ *
+ *	/<!-- -->* Query the service for the ACL for the given calendar *<!-- -->/
+ *	acl_feed = gdata_access_handler_get_rules (GDATA_ACCESS_HANDLER (calendar), GDATA_SERVICE (service), NULL, NULL, NULL, &error);
+ *
+ *	g_object_unref (calendar);
+ *
+ *	if (error != NULL) {
+ *		g_error ("Error getting ACL feed for calendar: %s", error->message);
+ *		g_error_free (error);
+ *		g_object_unref (service);
+ *		return;
+ *	}
+ *
+ *	/<!-- -->* Iterate through the ACL *<!-- -->/
+ *	for (i = gdata_feed_get_entries (acl_feed); i != NULL; i = i->next) {
+ *		const gchar *scope_value;
+ *
+ *		rule = GDATA_ACCESS_RULE (i->data);
+ *
+ *		/<!-- -->* Do something with the access rule here. As an example, we update the rule applying to test gmail com and delete all
+ *		 * the other rules. We then insert another rule for example gmail com below. *<!-- -->/
+ *		gdata_access_rule_get_scope (rule, NULL, &scope_value);
+ *		if (scope_value != NULL && strcmp (scope_value, "test gmail com") == 0) {
+ *			GDataAccessRule *updated_rule;
+ *
+ *			/<!-- -->* Update the rule to make test gmail com an editor (full read/write access to the calendar, but they can't change
+ *			 * the ACL). *<!-- -->/
+ *			gdata_access_rule_set_role (rule, GDATA_CALENDAR_ACCESS_ROLE_EDITOR);
+ *			updated_rule = GDATA_ACCESS_RULE (gdata_service_update_entry (GDATA_SERVICE (service), GDATA_ENTRY (rule), NULL, &error));
+ *
+ *			if (error != NULL) {
+ *				g_error ("Error updating access rule for %s: %s", scope_value, error->message);
+ *				g_error_free (error);
+ *				g_object_unref (acl_feed);
+ *				g_object_unref (service);
+ *				return;
+ *			}
+ *
+ *			g_object_unref (updated_rule);
+ *		} else {
+ *			/<!-- -->* Delete any rule which doesn't apply to test gmail com *<!-- -->/
+ *			gdata_service_delete_entry (GDATA_SERVICE (service), GDATA_ENTRY (rule), NULL, &error);
+ *
+ *			if (error != NULL) {
+ *				g_error ("Error deleting access rule for %s: %s", scope_value, error->message);
+ *				g_error_free (error);
+ *				g_object_unref (acl_feed);
+ *				g_object_unref (service);
+ *				return;
+ *			}
+ *		}
+ *	}
+ *
+ *	g_object_unref (acl_feed);
+ *
+ *	/<!-- -->* Create and insert a new access rule for example gmail com which allows then to view free/busy information for events in the
+ *	 * calendar, but doesn't allow them to view the full event details. *<!-- -->/
+ *	rule = gdata_access_rule_new (NULL);
+ *	gdata_access_rule_set_role (rule, GDATA_CALENDAR_ACCESS_ROLE_FREE_BUSY);
+ *	gdata_access_rule_set_scope (rule, GDATA_ACCESS_SCOPE_USER, "example gmail com");
+ *
+ *	acl_link = gdata_entry_look_up_link (GDATA_ENTRY (calendar), GDATA_LINK_ACCESS_CONTROL_LIST);
+ *	new_rule = GDATA_ACCESS_RULE (gdata_service_insert_entry (GDATA_SERVICE (service), gdata_link_get_uri (acl_link), GDATA_ENTRY (rule),
+ *	                                                          NULL, &error));
+ *
+ *	g_object_unref (rule);
+ *	g_object_unref (service);
+ *
+ *	if (error != NULL) {
+ *		g_error ("Error inserting access rule: %s", error->message);
+ *		g_error_free (error);
+ *		return;
+ *	}
+ *
+ *	g_object_unref (acl_link);
+ * 	</programlisting>
+ * </example>
  **/
 
 #include <config.h>