"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [

]>

<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 

      linkend="ref-dbus">GNOME Online Accounts D-Bus APIs</link>

      either directly or through the 

      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 

        linkend="gdbus-org.gnome.OnlineAccounts.Mail">mail</link>,

        linkend="gdbus-org.gnome.OnlineAccounts.Calendar">calendaring</link>

        or 

        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 

        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></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 

        linkend="gdbus-org.gnome.OnlineAccounts.Mail">mail</link>, may

        use standard protocols such as 

        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 

        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

        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.  

        linkend="gdbus-method-org-gnome-OnlineAccounts-OAuthBased.GetAccessToken">OAuthBased.GetAccessToken()</link>

        or 

        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 

        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 

        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 

        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>