GoaProvider

## GoaProvider GoaProvider — Abstract base class for providers |

## Synopsis

                        GoaProvider;
    struct              GoaProviderClass;
    enum                GoaProviderGroup;
    const gchar *       goa_provider_get_provider_type      (GoaProvider *provider);
    gchar *             goa_provider_get_provider_name      (GoaProvider *provider,
                                                             GoaObject *object);
    GIcon *             goa_provider_get_provider_icon      (GoaProvider *provider,
                                                             GoaObject *object);
    GoaProviderGroup    goa_provider_get_provider_group     (GoaProvider *provider);
    gboolean            goa_provider_build_object           (GoaProvider *provider,
                                                             GoaObjectSkeleton *object,
                                                             GKeyFile *key_file,
                                                             const gchar *group,
                                                             GDBusConnection *connection,
                                                             gboolean just_added,
                                                             GError **error);
    GoaObject *         goa_provider_add_account            (GoaProvider *provider,
                                                             GoaClient *client,
                                                             GtkDialog *dialog,
                                                             GtkBox *vbox,
                                                             GError **error);
    gboolean            goa_provider_refresh_account        (GoaProvider *provider,
                                                             GoaClient *client,
                                                             GoaObject *object,
                                                             GtkWindow *parent,
                                                             GError **error);
    void                goa_provider_show_account           (GoaProvider *provider,
                                                             GoaClient *client,
                                                             GoaObject *object,
                                                             GtkBox *vbox,
                                                             GtkGrid *left,
                                                             GtkGrid *right);
    void                goa_provider_ensure_credentials     (GoaProvider *provider,
                                                             GoaObject *object,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            goa_provider_ensure_credentials_finish
                                                            (GoaProvider *provider,
                                                             gint *out_expires_in,
                                                             GAsyncResult *res,
                                                             GError **error);
    gboolean            goa_provider_ensure_credentials_sync
                                                            (GoaProvider *provider,
                                                             GoaObject *object,
                                                             gint *out_expires_in,
                                                             GCancellable *cancellable,
                                                             GError **error);
    guint               goa_provider_get_credentials_generation
                                                            (GoaProvider *provider);
    #define             GOA_PROVIDER_EXTENSION_POINT_NAME
    GList *             goa_provider_get_all                (void);
    GoaProvider *       goa_provider_get_for_provider_type  (const gchar *provider_type);

## Object Hierarchy

      GObject
       +----GoaProvider
             +----GoaOAuthProvider
             +----GoaOAuth2Provider

## Description

GoaProvider is the base type for all providers.

## Details

### GoaProvider

    typedef struct _GoaProvider GoaProvider;

The GoaProvider structure contains only private data and should only be accessed using the provided API.

### struct GoaProviderClass

    struct GoaProviderClass {
      GObjectClass parent_class;

      /* pure virtual */
      const gchar *(*get_provider_type) (GoaProvider        *provider);
      gchar       *(*get_provider_name) (GoaProvider        *provider,
                                         GoaObject          *object);
      GIcon       *(*get_provider_icon) (GoaProvider        *provider,
                                         GoaObject          *object);
      GoaObject   *(*add_account)       (GoaProvider        *provider,
                                         GoaClient          *client,
                                         GtkDialog          *dialog,
                                         GtkBox             *vbox,
                                         GError            **error);
      gboolean     (*refresh_account)   (GoaProvider        *provider,
                                         GoaClient          *client,
                                         GoaObject          *object,
                                         GtkWindow          *parent,
                                         GError            **error);
      gboolean     (*build_object)      (GoaProvider        *provider,
                                         GoaObjectSkeleton  *object,
                                         GKeyFile           *key_file,
                                         const gchar        *group,
                                         GDBusConnection    *connection,
                                         gboolean            just_added,
                                         GError            **error);
      /* virtual but with default implementation */
      gboolean (*ensure_credentials_sync) (GoaProvider         *provider,
                                           GoaObject           *object,
                                           gint                *out_expires_in,
                                           GCancellable        *cancellable,
                                           GError             **error);
      void     (*show_account)            (GoaProvider         *provider,
                                           GoaClient           *client,
                                           GoaObject           *object,
                                           GtkBox              *vbox,
                                           GtkGrid             *left,
                                           GtkGrid             *right);
      guint    (*get_credentials_generation) (GoaProvider   *provider);

      /* pure virtual */
      GoaProviderGroup (*get_provider_group) (GoaProvider   *provider);
    };

Class structure for GoaProvider.

GObjectClass `parent_class`; | The parent class.
`get_provider_type` () | Virtual function for `goa_provider_get_provider_type()`.
`get_provider_name` () | Virtual function for `goa_provider_get_provider_name()`.
`get_provider_icon` () | Virtual function for `goa_provider_get_provider_icon()`.
`add_account` () | Virtual function for `goa_provider_add_account()`.
`refresh_account` () | Virtual function for `goa_provider_refresh_account()`.
`build_object` () | Virtual function for `goa_provider_build_object()`.
`ensure_credentials_sync` () | Virtual function for `goa_provider_ensure_credentials_sync()`.
`show_account` () | Virtual function for `goa_provider_show_account()`.
`get_credentials_generation` () | Virtual function for `goa_provider_get_credentials_generation()`.
`get_provider_group` () | Virtual function for `goa_provider_get_provider_group()`.

### enum GoaProviderGroup

    typedef enum {
      GOA_PROVIDER_GROUP_BRANDED,
      GOA_PROVIDER_GROUP_CONTACTS,
      GOA_PROVIDER_GROUP_MAIL,
      GOA_PROVIDER_GROUP_TICKETING,
      GOA_PROVIDER_GROUP_INVALID
    } GoaProviderGroup;

An enum for specifying which group a provider belongs to. This is can be used to organize the providers while displaying them in an user interface.

`GOA_PROVIDER_GROUP_BRANDED` | Providers with a well-known brand. For example, Google and Facebook.
`GOA_PROVIDER_GROUP_CONTACTS` | Providers that offer address book services. For example, CardDAV.
`GOA_PROVIDER_GROUP_MAIL` | Providers that offer email-like messaging services. For example, IMAP and SMTP.
`GOA_PROVIDER_GROUP_TICKETING` | Providers with ticketing capabilities. For example, Kerberos.
`GOA_PROVIDER_GROUP_INVALID` | Used for error handling. No provider should belong to this group.

### goa_provider_get_provider_type ()

    const gchar *       goa_provider_get_provider_type      (GoaProvider *provider);

Gets the type of `provider`.

This is a pure virtual method - a subclass must provide an implementation.

`provider` : | A GoaProvider.
Returns : | A string owned by `provider`, do not free. [transfer none]

### goa_provider_get_provider_name ()

    gchar *             goa_provider_get_provider_name      (GoaProvider *provider,
                                                             GoaObject *object);

Gets a name for `provider` and `object` that is suitable for display in an user interface. The returned value may depend on `object` (if it's not `NULL`) - for example, hosted accounts might return a different name.

This is a pure virtual method - a subclass must provide an implementation.

`provider` : | A GoaProvider.
`object` : | A GoaObject for an account. [allow-none]
Returns : | A string that should be freed with `g_free()`. [transfer full]

### goa_provider_get_provider_icon ()

    GIcon *             goa_provider_get_provider_icon      (GoaProvider *provider,
                                                             GoaObject *object);

Gets an icon for `provider` and `object` that is suitable for display in an user interface. The returned value may depend on `object` - for example, hosted accounts might return a different icon.

This is a virtual method with a default implementation that returns a GThemedIcon with fallbacks constructed from the name `goa-account-TYPE` where `TYPE` is the return value of `goa_provider_get_provider_type()`.

`provider` : | A GoaProvider.
`object` : | A GoaObject for an account.
Returns : | An icon that should be freed with `g_object_unref()`. [transfer full]

### goa_provider_get_provider_group ()

    GoaProviderGroup    goa_provider_get_provider_group     (GoaProvider *provider);

Gets the group to which `provider` belongs that is suitable for organizing the providers while displaying them in an user interface.

This is a pure virtual method - a subclass must provide an implementation.

`provider` : | A GoaProvider.
Returns : | A GoaProviderGroup.

Since 3.8

### goa_provider_build_object ()

    gboolean            goa_provider_build_object           (GoaProvider *provider,
                                                             GoaObjectSkeleton *object,
                                                             GKeyFile *key_file,
                                                             const gchar *group,
                                                             GDBusConnection *connection,
                                                             gboolean just_added,
                                                             GError **error);

This method is called when construction account GoaObject from configuration data - it basically provides a way to add provider-specific information.

The passed in `object` will have a GoaAccount interface set. Implementations should validate and use data from `key_file` to add more interfaces to `object`.

Note that this may be called on already exported objects - for example on configuration files reload.

This is a pure virtual method - a subclass must provide an implementation.

`provider` : | A GoaProvider.
`object` : | The GoaObjectSkeleton that is being built.
`key_file` : | The GKeyFile with configuation data.
`group` : | The group in `key_file` to get data from.
`connection` : | The GDBusConnection used by the daemon to connect to the message bus.
`just_added` : | Whether the account was newly created or being updated.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if data was valid, `FALSE` if `error` is set.

### goa_provider_add_account ()

    GoaObject *         goa_provider_add_account            (GoaProvider *provider,
                                                             GoaClient *client,
                                                             GtkDialog *dialog,
                                                             GtkBox *vbox,
                                                             GError **error);

This method brings up the user interface necessary to create a new account on `client` of the type for `provider`, interacts with the user to get all information needed and creates the account.

The passed in `dialog` widget is guaranteed to be visible with `vbox` being empty and the only visible widget in `dialog`'s content area. The dialog has exactly one action widget, a cancel button with response id GTK_RESPONSE_CANCEL. Implementations are free to add additional action widgets, as needed.

If an account was successfully created, a GoaObject for the created account is returned. If `dialog` is dismissed, `NULL` is returned and `error` is set to `GOA_ERROR_DIALOG_DISMISSED`. If an account couldn't be created then `error` is set. In some cases, for example, when the credentials could not be stored in the keyring, a GoaObject can be returned even if `error` is set.

The caller will always show an error dialog if `error` is set unless the error is `GOA_ERROR_DIALOG_DISMISSED`.

Implementations should run the default main loop while interacting with the user and may do so using e.g. `gtk_dialog_run()` on `dialog`.

This is a pure virtual method - a subclass must provide an implementation.

`provider` : | A GoaProvider.
`client` : | A GoaClient.
`dialog` : | A GtkDialog.
`vbox` : | A vertically oriented GtkBox to put content in.
`error` : | Return location for error or `NULL`.
Returns : | The GoaObject for the created account (must be relased with `g_object_unref()`) or `NULL` if `error` is set.

### goa_provider_refresh_account ()

    gboolean            goa_provider_refresh_account        (GoaProvider *provider,
                                                             GoaClient *client,
                                                             GoaObject *object,
                                                             GtkWindow *parent,
                                                             GError **error);

This method brings up the user interface necessary for refreshing the credentials for the account specified by `object`. This typically involves having the user log in to the account again.

Implementations should use `parent` (unless `NULL`) as the transient parent of any created windows/dialogs.

Implementations should run the default main loop while interacting with the user.

This is a pure virtual method - a subclass must provide an implementation.

`provider` : | A GoaProvider.
`client` : | A GoaClient.
`object` : | A GoaObject with a GoaAccount interface.
`parent` : | Transient parent of dialogs or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the account has been refreshed, `FALSE` if `error` is set.

### goa_provider_show_account ()

    void                goa_provider_show_account           (GoaProvider *provider,
                                                             GoaClient *client,
                                                             GoaObject *object,
                                                             GtkBox *vbox,
                                                             GtkGrid *left,
                                                             GtkGrid *right);

Method used to add widgets in the control panel for the account represented by `object`.

This is a virtual method with an implementation that (currently) does nothing. A subclass should chain up (before adding their own widgets to `vbox`, `left` and `right`) if they want to expose such functionality.

`provider` : | A GoaProvider.
`client` : | A GoaClient.
`object` : | A GoaObject with a GoaAccount interface.
`vbox` : | A vertically oriented GtkBox to put content in.
`left` : | A vertically oriented GtkGrid to put left-aligned content in.
`right` : | A vertically oriented GtkGrid to put right-aligned content in.

### goa_provider_ensure_credentials ()

    void                goa_provider_ensure_credentials     (GoaProvider *provider,
                                                             GoaObject *object,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Ensures that credentials for `object` are still valid.

When the result is ready, `callback` will be called in the the thread-default main loop this function was called from. You can then call `goa_provider_ensure_credentials_finish()` to get the result of the operation.

This is a virtual method where the default implementation simply throws the `GOA_ERROR_NOT_SUPPORTED` error. A subclass may provide another implementation.

`provider` : | A GoaProvider.
`object` : | A GoaObject with a GoaAccount interface.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`callback` : | The function to call when the request is satisfied.
`user_data` : | Pointer to pass to `callback`.

### goa_provider_ensure_credentials_finish ()

    gboolean            goa_provider_ensure_credentials_finish
                                                            (GoaProvider *provider,
                                                             gint *out_expires_in,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes an operation started with `goa_provider_ensure_credentials()`.

`provider` : | A GoaProvider.
`out_expires_in` : | Return location for how long the expired credentials are good for (0 if unknown) or `NULL`. [out]
`res` : | A GAsyncResult obtained from the GAsyncReadyCallback passed to `goa_provider_ensure_credentials()`.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the credentials for the passed GoaObject are valid, `FALSE` if `error` is set.

### goa_provider_ensure_credentials_sync ()

    gboolean            goa_provider_ensure_credentials_sync
                                                            (GoaProvider *provider,
                                                             GoaObject *object,
                                                             gint *out_expires_in,
                                                             GCancellable *cancellable,
                                                             GError **error);

Like `goa_provider_ensure_credentials()` but blocks the calling thread until an answer is received.

`provider` : | A GoaProvider.
`object` : | A GoaObject with a GoaAccount interface.
`out_expires_in` : | Return location for how long the expired credentials are good for (0 if unknown) or `NULL`. [out]
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the credentials for the passed GoaObject are valid, `FALSE` if `error` is set.

### goa_provider_get_credentials_generation ()

    guint               goa_provider_get_credentials_generation
                                                            (GoaProvider *provider);

Gets the generation of credentials being used for the provider.

Implementations should bump this number when changes are introduced that may render existing credentials unusable.

For example, if an additional scope is requested (e.g. access to contacts data) while obtaining credentials, then this number needs to be bumped since existing credentials are not good for the added scope.

This is a virtual method where the default implementation returns 0.

`provider` : | A GoaProvider.
Returns : | The current generation of credentials.

### GOA_PROVIDER_EXTENSION_POINT_NAME

    #define GOA_PROVIDER_EXTENSION_POINT_NAME "goa-backend-provider"

Extension point for GoaProvider implementations.

### goa_provider_get_all ()

    GList *             goa_provider_get_all                (void);

Looks up the `GOA_PROVIDER_EXTENSION_POINT_NAME` extension point and returns a newly created GoaProvider for each provider type encountered.

Returns : | A list of element providers that should be freed with `g_list_free()` after each element has been freed with `g_object_unref()`. [transfer full][element-type GoaProvider]

### goa_provider_get_for_provider_type ()

    GoaProvider *       goa_provider_get_for_provider_type  (const gchar *provider_type);

Looks up the `GOA_PROVIDER_EXTENSION_POINT_NAME` extension point and returns a newly created GoaProvider for `provider_type`, if any.

`provider_type` : | A provider type.
Returns : | A GoaProvider (that must be freed with `g_object_unref()`) or `NULL` if not found. [transfer full]