GoaProvider

GoaProvider — Abstract base class for providers

Synopsis

                    GoaProvider;
struct              GoaProviderClass;
enum                GoaProviderGroup;
enum                GoaProviderFeatures;
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);
GoaProviderFeatures goa_provider_get_provider_features  (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);
void                goa_provider_set_preseed_data       (GoaProvider *provider,
                                                         GVariant *preseed_data);
GVariant *          goa_provider_get_preseed_data       (GoaProvider *provider);
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 *grid,
                                                         GtkGrid *dummy);
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
void                goa_provider_get_all                (GAsyncReadyCallback callback,
                                                         gpointer user_data);
GoaProvider *       goa_provider_get_for_provider_type  (const gchar *provider_type);

Object Hierarchy

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

Properties

  "preseed-data"             GVariant*             : Read / Write

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);
  void         (*show_account)      (GoaProvider         *provider,
                                     GoaClient           *client,
                                     GoaObject           *object,
                                     GtkBox              *vbox,
                                     GtkGrid             *grid,
                                     GtkGrid             *dummy);
  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);
  guint    (*get_credentials_generation) (GoaProvider   *provider);

  /* pure virtual */
  GoaProviderGroup (*get_provider_group) (GoaProvider   *provider);
  GoaProviderFeatures  (*get_provider_features)     (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().

show_account ()

Virtual function for goa_provider_show_account().

build_object ()

Virtual function for goa_provider_build_object().

ensure_credentials_sync ()

Virtual function for goa_provider_ensure_credentials_sync().

get_credentials_generation ()

Virtual function for goa_provider_get_credentials_generation().

get_provider_group ()

Virtual function for goa_provider_get_provider_group().

get_provider_features ()

Virtual function for goa_provider_get_provider_features().

enum GoaProviderGroup

typedef enum {
  GOA_PROVIDER_GROUP_BRANDED,
  GOA_PROVIDER_GROUP_CONTACTS,
  GOA_PROVIDER_GROUP_MAIL,
  GOA_PROVIDER_GROUP_TICKETING,
  GOA_PROVIDER_GROUP_CHAT,
  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_CHAT

GOA_PROVIDER_GROUP_INVALID

Used for error handling. No provider should belong to this group.

enum GoaProviderFeatures

typedef enum {
  GOA_PROVIDER_FEATURE_BRANDED   = 1 << 1,
  GOA_PROVIDER_FEATURE_MAIL      = 1 << 2,
  GOA_PROVIDER_FEATURE_CALENDAR  = 1 << 3,
  GOA_PROVIDER_FEATURE_CONTACTS  = 1 << 4,
  GOA_PROVIDER_FEATURE_CHAT      = 1 << 5,
  GOA_PROVIDER_FEATURE_DOCUMENTS = 1 << 6,
  GOA_PROVIDER_FEATURE_PHOTOS    = 1 << 7,
  GOA_PROVIDER_FEATURE_FILES     = 1 << 8,
  GOA_PROVIDER_FEATURE_TICKETING = 1 << 9,
  GOA_PROVIDER_FEATURE_INVALID   = 0
} 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).

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

Documents storage services (ie. Google Documents).

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_INVALID

Used for error handling. No provider should provide this feature.

Since 3.10


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

Warning

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 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_get_provider_features ()

GoaProviderFeatures goa_provider_get_provider_features  (GoaProvider *provider);

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

provider :

A GoaProvider.

Returns :

The GoaProviderFeatures bitmask with the provided features.

Since 3.10


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

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

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.

provider :

The GoaProvider

preseed_data :

A GVariant of type a{sv}

goa_provider_get_preseed_data ()

GVariant *          goa_provider_get_preseed_data       (GoaProvider *provider);

Gets the GVariant set through the "preseed-data" property.

provider :

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 *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 *grid,
                                                         GtkGrid *dummy);

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

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.

vbox :

A vertically oriented GtkBox to put content in.

grid :

A GtkGrid to put content in.

dummy :

Unused.

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

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.

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

Returns a GoaProvider for provider_type (if available).

If provider_type doesn't contain any "/", a GOA_PROVIDER_EXTENSION_POINT_NAME extension for provider_type is looked up and the newly created GoaProvider, if any, is returned.

If provider_type contains a "/", a GOA_PROVIDER_FACTORY_EXTENSION_POINT_NAME extension for the first part of provider_type is looked up. If found, the GoaProviderFactory is used to create a dynamic GoaProvider matching the second part of provider_type.

provider_type :

A provider type.

Returns :

A GoaProvider (that must be freed with g_object_unref()) or NULL if not found. [transfer full]

Property Details

The "preseed-data" property

  "preseed-data"             GVariant*             : Read / Write

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:

{
  "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.

Allowed values: GVariant<a{sv}>

Default value: NULL