ApPlugin

ApPlugin — Base class for account plugins.

Synopsis

#include <libaccount-plugin/plugin.h>

                    ApPlugin;
#define             AP_PLUGIN_CREDENTIALS_ID_FIELD
GtkWidget *         ap_plugin_build_widget              (ApPlugin *self);
void                ap_plugin_act_headless              (ApPlugin *self);
void                ap_plugin_delete_account            (ApPlugin *self,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            ap_plugin_delete_account_finish     (ApPlugin *self,
                                                         GAsyncResult *result,
                                                         GError **error);
void                ap_plugin_emit_finished             (ApPlugin *self);
AgAccount *         ap_plugin_get_account               (ApPlugin *self);
AgProvider *        ap_plugin_get_provider              (ApPlugin *self);
gboolean            ap_plugin_get_need_authentication   (ApPlugin *self);
void                ap_plugin_set_need_authentication   (ApPlugin *self,
                                                         gboolean need_authentication);
void                ap_plugin_set_credentials           (ApPlugin *self,
                                                         const gchar *username,
                                                         const gchar *password);
const gchar *       ap_plugin_get_username              (ApPlugin *self);
const gchar *       ap_plugin_get_password              (ApPlugin *self);
GHashTable *        ap_plugin_get_cookies               (ApPlugin *self);
void                ap_plugin_set_cookies               (ApPlugin *self,
                                                         GHashTable *cookies);
gboolean            ap_plugin_get_ignore_cookies        (ApPlugin *self);
void                ap_plugin_set_ignore_cookies        (ApPlugin *self,
                                                         gboolean ignore_cookies);
gboolean            ap_plugin_get_user_cancelled        (ApPlugin *self);
void                ap_plugin_set_user_cancelled        (ApPlugin *self,
                                                         gboolean cancelled);
const GError *      ap_plugin_get_error                 (ApPlugin *self);
void                ap_plugin_set_error                 (ApPlugin *self,
                                                         const GError *error);

Object Hierarchy

  GObject
   +----ApPlugin
         +----ApOAuthPlugin

Properties

  "account"                  AgAccount*            : Read / Write / Construct Only
  "need-authentication"      gboolean              : Read / Write

Signals

  "finished"                                       : Run Last

Description

Account plugins for the credentials panel of the GNOME control center need to subclass ApPlugin and implement its build_widget() virtual method. This method will be called by the credentials panel when it needs to show a UI to handle some operations on the account, such as creation, editing or re-authentication.

Details

ApPlugin

typedef struct _ApPlugin ApPlugin;

Use the accessor functions below.

AP_PLUGIN_CREDENTIALS_ID_FIELD

#define AP_PLUGIN_CREDENTIALS_ID_FIELD "CredentialsId"

The field in the credentials database for storing the signon identity ID.

ap_plugin_build_widget ()

GtkWidget *         ap_plugin_build_widget              (ApPlugin *self);

Build a UI widget to perform the needed operation on the AgAccount associated with this plugin:

  • if the AgAccount is a newly allocated instance (not stored on disk), then the plugin should proceed with the account creation. Otherwise,

  • if the "need-authentication" property is set, the returned UI widget should provide a way for the user to reauthenticate the account;

  • if none of the above conditions apply, the plugin should return a widget to allow editing the account global settings (that is, those settings which are common for all applications using the account). The plugin will emit the "finished" signal once the widget has completed its tasks and can be destroyed.

self :

 the ApPlugin.

Returns :

 a GtkWidget which till take care of performing the needed tasks, or NULL. [transfer floating]

ap_plugin_act_headless ()

void                ap_plugin_act_headless              (ApPlugin *self);

Perform the needed operation on the AgAccount associated with this plugin. This works similarly to the ap_plugin_build_widget() method, with the difference that in this case there is no UI involved. The plugin will emit the "finished" signal once it has completed its tasks.

self :

 the ApPlugin.

ap_plugin_delete_account ()

void                ap_plugin_delete_account            (ApPlugin *self,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Delete the account. When the operation is finished, callback will be invoked; you can then call ap_plugin_delete_account_finish() to know if the operation was successful. This is a virtual method; the base implementation removes the account from the accounts database and the accounts credentials from the Single Sign-On database.

self :

 the ApPlugin.

callback :

 a callback which will be invoked when the operation has been completed.

user_data :

 user data to be passed to the callback.

ap_plugin_delete_account_finish ()

gboolean            ap_plugin_delete_account_finish     (ApPlugin *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finish the operation started with ap_plugin_delete_account().

self :

 the ApPlugin.

result :

 the GAsyncResult obtained from the GAsyncReadyCallback passed to ap_plugin_delete_account().

error :

 location for error, or NULL.

Returns :

 TRUE if the operation succeeded, FALSE otherwise.

ap_plugin_emit_finished ()

void                ap_plugin_emit_finished             (ApPlugin *self);

Emits the "finished" signal. This method is useful for subclasses only.

self :

 the ApPlugin.

ap_plugin_get_account ()

AgAccount *         ap_plugin_get_account               (ApPlugin *self);

Get the AgAccount associated with this plugin instance.

self :

 the ApPlugin.

Returns :

 the AgAccount, or NULL. [transfer none]

ap_plugin_get_provider ()

AgProvider *        ap_plugin_get_provider              (ApPlugin *self);

Get the AgProvider associated with this plugin instance.

self :

 the ApPlugin.

Returns :

 the AgProvider, or NULL. [transfer none]

ap_plugin_get_need_authentication ()

gboolean            ap_plugin_get_need_authentication   (ApPlugin *self);

Get whether the AgAccount associated with this plugin instance needs to be re-authenticated.

self :

 the ApPlugin.

Returns :

 TRUE if the account needs re-authentication, FALSE otherwise.

ap_plugin_set_need_authentication ()

void                ap_plugin_set_need_authentication   (ApPlugin *self,
                                                         gboolean need_authentication);

Tell the plugin that the AgAccount associated with it needs to be re-authenticated.

self :

 the ApPlugin.

need_authentication :

 whether the plugin must perform the authentication.

ap_plugin_set_credentials ()

void                ap_plugin_set_credentials           (ApPlugin *self,
                                                         const gchar *username,
                                                         const gchar *password);

Set the user name and password. The plugin could use them for prefilling the login form (or skip it altogether).

self :

 the ApPlugin.

username :

 login username.

password :

 the user password, or NULL.

ap_plugin_get_username ()

const gchar *       ap_plugin_get_username              (ApPlugin *self);

Get the login username.

self :

 the ApPlugin.

Returns :

 the username, or NULL.

ap_plugin_get_password ()

const gchar *       ap_plugin_get_password              (ApPlugin *self);

Get the login password.

self :

 the ApPlugin.

Returns :

 the password, or NULL.

ap_plugin_get_cookies ()

GHashTable *        ap_plugin_get_cookies               (ApPlugin *self);

Get the HTTP cookies.

self :

 the ApPlugin.

Returns :

 a dictionary with cookie name and value pairs, or NULL. [element-type utf8 utf8][transfer none][allow-none]

ap_plugin_set_cookies ()

void                ap_plugin_set_cookies               (ApPlugin *self,
                                                         GHashTable *cookies);

Set the HTTP cookies. The plugin may use them while performing a web-based authentication.

self :

 the ApPlugin.

cookies :

 a GHashTable with cookie name and value pairs. [element-type utf8 utf8][transfer none]

ap_plugin_get_ignore_cookies ()

gboolean            ap_plugin_get_ignore_cookies        (ApPlugin *self);

Get whether the provided cookies should be ignored when performing the authentication.

self :

 the ApPlugin.

Returns :

 whether provided cookies should be ignored.

ap_plugin_set_ignore_cookies ()

void                ap_plugin_set_ignore_cookies        (ApPlugin *self,
                                                         gboolean ignore_cookies);

Tells the plugin implementation that all provided cookies should be ignored when performing the authentication; an ApPlugin subclass might choose to ignore cookies when the provided cookies are known not to be working.

self :

 the ApPlugin.

ignore_cookies :

 whether provided cookies should be ignored.

ap_plugin_get_user_cancelled ()

gboolean            ap_plugin_get_user_cancelled        (ApPlugin *self);

Get whether the requested operation was cancelled by the user.

self :

 the ApPlugin.

Returns :

 TRUE if the operation was cancelled, FALSE otherwise.

ap_plugin_set_user_cancelled ()

void                ap_plugin_set_user_cancelled        (ApPlugin *self,
                                                         gboolean cancelled);

Tell the plugin that the requested operation was cancelled by the user. This method should be called by ApPlugin subclasses only.

self :

 the ApPlugin.

cancelled :

 whether the plugin operation was cancelled by the user.

ap_plugin_get_error ()

const GError *      ap_plugin_get_error                 (ApPlugin *self);

Get whether the requested operation ended in an error.

self :

 the ApPlugin.

Returns :

 a GError if an error occurred, NULL otherwise. [transfer none]

ap_plugin_set_error ()

void                ap_plugin_set_error                 (ApPlugin *self,
                                                         const GError *error);

Tell the plugin that the requested operation ended in an error. This method should be called by ApPlugin subclasses only.

self :

 the ApPlugin.

error :

 the GError to set on the plugin.

Property Details

The "account" property

  "account"                  AgAccount*            : Read / Write / Construct Only

The AgAccount associated with the plugin.

The "need-authentication" property

  "need-authentication"      gboolean              : Read / Write

Whether the plugin needs to be authenticated again.

Default value: FALSE

Signal Details

The "finished" signal

void                user_function                      (ApPlugin *plugin,
                                                        gpointer  user_data)      : Run Last

Emitted when the plugin UI has completed its task and can be dismissed.

plugin :

 the ApPlugin.

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.19