Add a Writing GOA applications chapter

Signed-off-by: David Zeuthen <davidz@redhat.com>

3 files changed, 128 insertions, 4 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index fb74279..eae3bfe 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -52,6 +52,7 @@ content_files =			\
 
 expand_content_files =		\
 	goa-daemon.xml		\
+	goa-overview.xml	\
 	$(NULL)
 
 extra_files =			\
diff --git a/doc/goa-docs.xml b/doc/goa-docs.xml
index 1a506bd..4967e4e 100644
--- a/doc/goa-docs.xml
+++ b/doc/goa-docs.xml
@@ -52,9 +52,7 @@
     </legalnotice>
   </bookinfo>
 
-  <part id="overview">
-    <title>GNOME Online Accounts Overview</title>
-  </part>
+  <xi:include href="xml/goa-overview.xml"/>
 
   <part id="ref-dbus">
     <title>D-Bus API Reference</title>
@@ -98,8 +96,8 @@
 
     <chapter>
       <title>Core Interfaces</title>
-      <xi:include href="../src/goa/goa-generated-doc-org.gnome.OnlineAccounts.Manager.xml"/>
       <xi:include href="../src/goa/goa-generated-doc-org.gnome.OnlineAccounts.Account.xml"/>
+      <xi:include href="../src/goa/goa-generated-doc-org.gnome.OnlineAccounts.Manager.xml"/>
     </chapter>
     <chapter>
       <title>Credentials Interfaces</title>
diff --git a/doc/goa-overview.xml b/doc/goa-overview.xml
new file mode 100644
index 0000000..2afc0eb
--- /dev/null
+++ b/doc/goa-overview.xml
@@ -0,0 +1,125 @@
+<?xml version="1.0"?>
+<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<part id="overview">
+  <title>GNOME Online Accounts Overview</title>
+
+  <chapter id="overview-writing">
+    <title>Writing GOA applications</title>
+    <para>
+      The term <emphasis>GOA application</emphasis> is used to
+      describe applications or libraries that are using the <link
+      linkend="ref-dbus">GNOME Online Accounts D-Bus APIs</link>
+      either directly or through the <link
+      linkend="ref-library">supplied client library</link>.
+    </para>
+
+    <sect1>
+      <title>Account Objects</title>
+      <para>
+        A GOA application typically creates #GoaClient object to get a
+        list of accounts and listen for changes. Each account provide
+        one or more specific services (such as <link
+        linkend="gdbus-org.gnome.OnlineAccounts.Mail">mail</link>,
+        <link
+        linkend="gdbus-org.gnome.OnlineAccounts.Calendar">calendaring</link>
+        or <link
+        linkend="gdbus-org.gnome.OnlineAccounts.Contacts">contacts</link>)
+        so the application will need to set up a filter for the
+        services it is interested in. For example, a mail application
+        would only be interested in GOA accounts with mail- and
+        contacts-services, not accounts with
+        calendaring-services. Applications can use methods on the
+        #GoaObject type (such as goa_object_peek_mail()) to check what
+        kind of services an account provides. Note that this list can
+        change at run-time if e.g. the user toggles a <guilabel>Use
+        account for Mail</guilabel> check-button.
+      </para>
+      <para>
+        Applications may use the <link
+        linkend="gdbus-property-org-gnome-OnlineAccounts-Account.Id">Account.Id</link>
+        property as a unique key to store information obtained from
+        an account.
+      </para>
+      <para>
+        Applications must not destroy data if an account object is
+        removed (e.g. when the #GoaClient::account-removed signal is
+        emitted) - for example, if the <command>goa-daemon</command>
+        program crashes or is restarted on software upgrade, account
+        objects will be removed only to be added back the next time
+        <command>goa-daemon</command> is started.
+      </para>
+      <para>
+        Applications should use the
+        <link linkend="gdbus-property-org-gnome-OnlineAccounts-Account.ProviderName">Account.ProviderIcon</link>,
+        <link linkend="gdbus-property-org-gnome-OnlineAccounts-Account.ProviderName">Account.ProviderName</link>
+        and
+        <link linkend="gdbus-property-org-gnome-OnlineAccounts-Account.ProviderName">Account.PresentationIdentity</link>
+        properties when presenting an account in an user interface.
+        For example, for a hypothetical online services provider Acme,
+        this would be the Acme Logo, the word "Acme" and the identity
+        could be either an email address such as
+        <email><![CDATA[some.name@acme.com]]></email> or an user
+        handle such as <literal>davidz25</literal> or
+        <literal>chunkylover53</literal>.
+      </para>
+    </sect1>
+
+    <sect1>
+      <title>Accessing Services</title>
+      <para>
+        A GOA application needs to handle service-specific protocols
+        and quirks itself. Some service-types, such as <link
+        linkend="gdbus-org.gnome.OnlineAccounts.Mail">mail</link>, may
+        use standard protocols such as <ulink
+        url="http://tools.ietf.org/html/rfc3501">IMAP</ulink> or
+        <ulink url="http://tools.ietf.org/html/rfc5321">SMTP</ulink>
+        but they also may not. GOA applications should always look at
+        the <link
+        linkend="gdbus-property-org-gnome-OnlineAccounts-Account.ProviderType">Account.ProviderType</link>
+        property to infer what kind of protocol and endpoint to use.
+      </para>
+    </sect1>
+
+    <sect1>
+      <title>Credentials Handling</title>
+      <para>
+        For accessing a service, the application typically needs to
+        present credentials. The application can request the
+        credentials via GOA. First the application should invoke the
+        <link
+        linkend="gdbus-method-org-gnome-OnlineAccounts-Account.EnsureCredentials">Account.EnsureCredentials()</link>
+        method on the account object. If this succeeds, the
+        application can request the credentials using e.g.  <link
+        linkend="gdbus-method-org-gnome-OnlineAccounts-OAuthBased.GetAccessToken">OAuthBased.GetAccessToken()</link>
+        or <link
+        linkend="gdbus-method-org-gnome-OnlineAccounts-OAuth2Based.GetAccessToken">OAuth2Based.GetAccessToken()</link>
+        depending on what kind of credentials the account is using.
+        If the service returns an authorization error (say, the access
+        token expired), the application should call <link
+        linkend="gdbus-method-org-gnome-OnlineAccounts-Account.EnsureCredentials">Account.EnsureCredentials()</link>
+        again to e.g. renew the credentials.
+      </para>
+      <para>
+        On the other hand, if <link
+        linkend="gdbus-method-org-gnome-OnlineAccounts-Account.EnsureCredentials">Account.EnsureCredentials()</link>
+        ever fails, then the user will get notified that there is a
+        problem with the account so he can take actions to fix it.
+        Applications can listen to changes on the <link
+        linkend="gdbus-property-org-gnome-OnlineAccounts-Account.AttentionNeeded">Account.AttentionNeeded</link>
+        property to get notified when it's time to try accessing the
+        account again.
+      </para>
+      <para>
+        Note that the implementation for a provider may switch from
+        e.g. OAuth to OAuth2 in a newer release of GNOME Online
+        Accounts. Therefore, applications must never assume that the
+        #GoaObject for an account implements a fixed set of
+        interfaces.
+      </para>
+    </sect1>
+
+  </chapter>
+</part>