GoaProvider

GoaProvider — Abstract base class for providers

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── GoaProvider
        ├── GoaOAuthProvider
        ╰── GoaOAuth2Provider

Description

GoaProvider is the base type for all providers.

Functions

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.

Parameters

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.

Parameters

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

Parameters

provider

A GoaProvider.

 

object

A GoaObject for an account.

 

Returns

An icon that should be freed with g_object_unref().

[transfer full]


goa_provider_build_object ()

gboolean
goa_provider_build_object (GoaProvider *provider,
                           GoaObjectSkeleton *object,
                           GKeyFile *key_file,
                           const gchar *group,
                           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.

Parameters

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.

 

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.

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

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.

Parameters

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,
                           GtkTable *table);

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 and table ) if they want to expose such functionality.

Parameters

provider

A GoaProvider.

 

client

A GoaClient.

 

object

A GoaObject with a GoaAccount interface.

 

vbox

A vertically oriented GtkBox to put content in.

 

table

A table which is the first element of vbox.

 

goa_provider_store_credentials_sync ()

gboolean
goa_provider_store_credentials_sync (GoaProvider *provider,
                                     GoaObject *object,
                                     GVariant *credentials,
                                     GCancellable *cancellable,
                                     GError **error);

Stores credentials for identity in the key-ring. If credentials is floating, it is consumed.

The calling thread is blocked while waiting for a reply.

This is a convenience method (not virtual) that subclasses can use.

Parameters

provider

A GoaProvider.

 

object

The account to store credentials for.

 

credentials

The credentials to store.

 

cancellable

A GCancellable or NULL.

[allow-none]

error

Return location for error or NULL.

 

Returns

TRUE if the credentials was successfully stored, FALSE if error is set.


goa_provider_lookup_credentials_sync ()

GVariant *
goa_provider_lookup_credentials_sync (GoaProvider *provider,
                                      GoaObject *object,
                                      GCancellable *cancellable,
                                      GError **error);

Looks up credentials in the keyring for identity previously stored with goa_provider_store_credentials().

The calling thread is blocked while waiting for a reply.

This is a convenience method (not virtual) that subclasses can use.

Parameters

provider

A GoaProvider.

 

object

The account to store credentials for.

 

cancellable

A GCancellable or NULL.

[allow-none]

error

Return location for error or NULL.

 

Returns

A GVariant (never floating) with credentials or NULL if error is set. Free with g_variant_unref().

[transfer full]


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 returns the GOA_ERROR_NOT_SUPPORTED error. A subclass may provide another implementation.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

provider

A GoaProvider.

 

Returns

The current generation of credentials.


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.

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.


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,
                                     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,
                                       GtkTable            *table);
  guint    (*get_credentials_generation) (GoaProvider   *provider);
};

Class structure for GoaProvider.

Members

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

   

get_credentials_generation ()

Virtual function for goa_provider_get_credentials_generation().

 

GOA_PROVIDER_EXTENSION_POINT_NAME

#define GOA_PROVIDER_EXTENSION_POINT_NAME "goa-backend-provider"

Extension point for GoaProvider implementations.