ApPlugin

ApPlugin — Base class for account plugins.

Functions

Properties

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

Signals

void finished Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── ApPlugin
        ╰── ApOAuthPlugin

Includes

#include <libaccount-plugin/plugin.h>

Description

Account plugins for the credentials panel of the Unity 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.

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

self

the ApPlugin.

 

ap_plugin_get_account ()

AgAccount *
ap_plugin_get_account (ApPlugin *self);

Get the AgAccount associated with this plugin instance.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

self

the ApPlugin.

 

Returns

the username, or NULL.


ap_plugin_get_password ()

const gchar *
ap_plugin_get_password (ApPlugin *self);

Get the login password.

Parameters

self

the ApPlugin.

 

Returns

the password, or NULL.


ap_plugin_get_cookies ()

GHashTable *
ap_plugin_get_cookies (ApPlugin *self);

Get the HTTP cookies.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

self

the ApPlugin.

 

error

the GError to set on the plugin.

 

Types and Values

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.

Property Details

The “account” property

  “account”                  AgAccount *

The AgAccount associated with the plugin.

Flags: Read / Write / Construct Only


The “need-authentication” property

  “need-authentication”      gboolean

Whether the plugin needs to be authenticated again.

Flags: Read / Write

Default value: FALSE

Signal Details

The “finished” signal

void
user_function (ApPlugin *plugin,
               gpointer  user_data)

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

Parameters

plugin

the ApPlugin.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last