GoaProvider: GNOME Online Accounts Reference Manual

## GoaProvider GoaProvider — Abstract base class for providers |

## Functions

const gchar * | goa_provider_get_provider_type ()
gchar * | goa_provider_get_provider_name ()
GIcon * | goa_provider_get_provider_icon ()
GoaProviderGroup | goa_provider_get_provider_group ()
GoaProviderFeatures | goa_provider_get_provider_features ()
GoaObject * | goa_provider_add_account ()
void | goa_provider_set_preseed_data ()
GVariant * | goa_provider_get_preseed_data ()
gboolean | goa_provider_refresh_account ()
void | goa_provider_show_account ()
guint | goa_provider_get_credentials_generation ()
void | goa_provider_get_all ()
GoaProvider * | goa_provider_get_for_provider_type ()

## Properties

GVariant * | preseed-data | Read / Write

## Types and Values

| GoaProvider
| GoaProviderClass
enum | GoaProviderGroup
enum | GoaProviderFeatures

## Object Hierarchy

        GObject
        ╰── GoaProvider
            ╰── GoaOAuth2Provider

## Description

GoaProvider is the base type for all providers.

## Functions

### goa_provider_get_provider_type ()

    const gchar *
    goa_provider_get_provider_type (GoaProvider *self);

Gets the type of `self` .

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

#### Parameters

self | A GoaProvider. |

#### Returns

A string owned by `self` , do not free.

[transfer none]

### goa_provider_get_provider_name ()

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

Gets a name for `self` 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.

#### Parameters

self | 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 *self,
                                    GoaObject *object);

Gets an icon for `self` 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()`.

#### Parameters

self | 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 *self);

`goa_provider_get_provider_group` has been deprecated since version 3.10 and should not be used in newly-written code.

Use `goa_provider_get_provider_features()` instead.

Gets the group to which `self` 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.

#### Parameters

self | A GoaProvider. |

#### Returns

A GoaProviderGroup.

Since: 3.8

### goa_provider_get_provider_features ()

    GoaProviderFeatures
    goa_provider_get_provider_features (GoaProvider *self);

Get the features bitmask (eg. `GOA_PROVIDER_FEATURE_CHAT`|`GOA_PROVIDER_FEATURE_CONTACTS`) supported by the provider.

#### Parameters

self | A GoaProvider. |

#### Returns

The GoaProviderFeatures bitmask with the provided features.

Since: 3.10

### goa_provider_add_account ()

    GoaObject *
    goa_provider_add_account (GoaProvider *self,
                              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 `self` , 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.

#### Parameters

self | 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_set_preseed_data ()

    void
    goa_provider_set_preseed_data (GoaProvider *self,
                                   GVariant *preseed_data);

`goa_provider_set_preseed_data` has been deprecated since version 3.28 and should not be used in newly-written code.

This function does nothing.

Sets the “preseed-data” property to feed any information already collected that can be useful when creating a new account.

If the `preseed_data` GVariant is floating, it is consumed to allow 'inline' use of the `g_variant_new()` family of functions.

#### Parameters

self | The GoaProvider |
preseed_data | A GVariant of type a{sv} |

### goa_provider_get_preseed_data ()

    GVariant *
    goa_provider_get_preseed_data (GoaProvider *self);

`goa_provider_get_preseed_data` has been deprecated since version 3.28 and should not be used in newly-written code.

This function does nothing.

Gets the GVariant set through the “preseed-data” property.

#### Parameters

self | The GoaProvider |

#### Returns

A GVariant that is known to be valid until the property is overridden or the provider freed.

[transfer none]

### goa_provider_refresh_account ()

    gboolean
    goa_provider_refresh_account (GoaProvider *self,
                                  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.

#### Parameters

self | 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 *self,
                               GoaClient *client,
                               GoaObject *object,
                               GtkBox *vbox,
                               GtkGrid *dummy1,
                               GtkGrid *dummy2);

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

This is a virtual method where the default implementation adds one GtkSwitch per service supported by the provider (as reported by `goa_provider_get_provider_features()`).

#### Parameters

self | A GoaProvider. |
client | A GoaClient. |
object | A GoaObject with a GoaAccount interface. |
vbox | A vertically oriented GtkBox to put content in. |
grid | A GtkGrid to put content in. |
dummy | Unused. |

### goa_provider_get_credentials_generation ()

    guint
    goa_provider_get_credentials_generation
                                   (GoaProvider *self);

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.

#### Parameters

self | A GoaProvider. |

#### Returns

The current generation of credentials.

### goa_provider_get_all ()

    void
    goa_provider_get_all (GAsyncReadyCallback callback,
                          gpointer user_data);

Creates a list of all the available GoaProvider instances.

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_get_all_finish()` to get the result of the operation.

See `goa_provider_get_for_provider_type()` for details on how the providers are found.

#### Parameters

callback | The function to call when the request is satisfied. |
user_data | Pointer to pass to `callback` . |

### 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.

#### Parameters

provider_type | A provider type. |

#### Returns

A GoaProvider (that must be freed with `g_object_unref()`) or `NULL` if not found.

[transfer full]

## Types and Values

### GoaProvider

    typedef struct _GoaProvider GoaProvider;

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

### GoaProviderClass

    typedef struct _GoaProviderClass GoaProviderClass;

Class structure for GoaProvider.

#### Members

### enum 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.

#### Members

GOA_PROVIDER_GROUP_BRANDED | Providers with a well-known brand. For example, Google. |
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_CHAT | Providers that offer chat-like messaging capabilities. For example, XMPP, IRC. |
GOA_PROVIDER_GROUP_INVALID | Used for error handling. No provider should belong to this group. |

### enum GoaProviderFeatures

These flags specify the features exported by each provider. They can be expecially useful to restrict the list of available providers when requesting the creation of an account for a specific purpose (eg. from a chat program).

#### Members

GOA_PROVIDER_FEATURE_BRANDED | Common providers to be highlighted (ie. Google, OwnCloud). |
GOA_PROVIDER_FEATURE_MAIL | Mail services (ie. SMTP, IMAP). |
GOA_PROVIDER_FEATURE_CALENDAR | Calendaring services (ie. CalDAV). |
GOA_PROVIDER_FEATURE_CONTACTS | Addressbook services (ie. CardDAV). |
GOA_PROVIDER_FEATURE_CHAT | Instant messaging services (ie. XMPP, IRC). |
GOA_PROVIDER_FEATURE_DOCUMENTS | Deprecated; currently unused. |
GOA_PROVIDER_FEATURE_PHOTOS | Photos storage services (ie. Flickr). |
GOA_PROVIDER_FEATURE_FILES | Files storage services (ie. WebDAV). |
GOA_PROVIDER_FEATURE_TICKETING | Ticketing services (ie. Kerberos). |
GOA_PROVIDER_FEATURE_READ_LATER | Deprecated; currently unused. |
GOA_PROVIDER_FEATURE_PRINTERS | Network printing services (e.g. Google Cloud Print). |
GOA_PROVIDER_FEATURE_MAPS | Deprecated; currently unused. |
GOA_PROVIDER_FEATURE_MUSIC | Music related services (e.g. Vkontakte). |
GOA_PROVIDER_FEATURE_TODO | Deprecated; currently unused. |
GOA_PROVIDER_FEATURE_INVALID | Used for error handling. No provider should provide this feature. |

Since: 3.10

## Property Details

### The `“preseed-data”` property

      “preseed-data”             GVariant *

An GVariant of type a{sv} storing any information already collected that can be useful when creating a new account. For instance, this can be useful to reuse the HTTP cookies from an existing browser session to skip the prompt for username and password in the OAuth2-based providers by passing a GVariant with the following contents:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    {
      "cookies": [
        {
          "domain": "example.com",
          "name": "LSID",
          "value": "asdfasdfasdf"
        },
        {
          "domain": "accounts.example.com",
          "name": "SSID",
          "value": "asdfasdfasdf"
        }
      ]
    }

Unknown or unsupported keys will be ignored by providers.

`GoaProvider:preseed-data` has been deprecated since version 3.28 and should not be used in newly-written code.

This property does nothing.

Owner: GoaProvider

Flags: Read / Write

Allowed values: GVariant<a{sv}>

Default value: NULL