EOAuth2Service

EOAuth2Service — An interface for an OAuth2 service

Functions

Types and Values

Object Hierarchy

    GInterface
    ╰── EOAuth2Service

Prerequisites

EOAuth2Service requires GObject.

Includes

#include <libedataserver/libedataserver.h>

Description

An interface for an OAuth2 service. Any descendant might be defined as an extension of EOAuth2Services and it should add itself into it with e_oauth2_services_add(). To make it easier, an EOAuth2ServiceBase is provided for convenience.

Functions

EOAuth2ServiceRefSourceFunc ()

ESource *
(*EOAuth2ServiceRefSourceFunc) (gpointer user_data,
                                const gchar *uid);

Returns

an ESource with UID uid , or NULL, if not found. Dereference the returned non-NULL ESource with g_object_unref(), when no longer needed.

[transfer full][nullable]

Since: 3.28


e_oauth2_service_can_process ()

gboolean
e_oauth2_service_can_process (EOAuth2Service *service,
                              ESource *source);

Checks whether the service can be used with the given source .

The default implementation checks whether the source has an ESourceAuthentication extension and when its method matches e_oauth2_service_get_name(), then it automatically returns TRUE. Contrary, when the source contains GNOME Online Accounts or Ubuntu Online Accounts extension, then it returns FALSE.

The default implementation is tried always as the first and when it fails, then the descendant's implementation is called.

Parameters

service

an EOAuth2Service

 

source

an ESource

 

Returns

Whether the service can be used for the given source

Since: 3.28


e_oauth2_service_guess_can_process ()

gboolean
e_oauth2_service_guess_can_process (EOAuth2Service *service,
                                    const gchar *protocol,
                                    const gchar *hostname);

Checks whether the service can be used with the given protocol and/or hostname . Any of protocol and hostname can be NULL, but not both. It's up to each implementer to decide, which of the arguments are important and whether all or only any of them can be required.

The function is meant to check whether the service can be offered for example when configuring a new account. The real usage is determined by e_oauth2_service_can_process().

The default implementation consults org.gnome.evolution-data-server.oauth2-services-hint GSettings key against given hostname. See its description for more information.

The default implementation is tried always as the first and when it fails, then the descendant's implementation is called.

Parameters

service

an EOAuth2Service

 

protocol

a protocol to search the service for, like "imap", or NULL.

[nullable]

hostname

a host name to search the service for, like "server.example.com", or NULL.

[nullable]

Returns

Whether the service can be used for the given arguments

Since: 3.28


e_oauth2_service_get_flags ()

guint32
e_oauth2_service_get_flags (EOAuth2Service *service);

Parameters

service

an EOAuth2Service

 

Returns

bit-or of EOAuth2ServiceFlags for the service . The default implementation returns E_OAUTH2_SERVICE_FLAG_NONE.

Since: 3.28


e_oauth2_service_get_name ()

const gchar *
e_oauth2_service_get_name (EOAuth2Service *service);

Returns a unique name of the service. It can be named for example by the server or the company from which it receives the OAuth2 token and where it refreshes it, like "Company" for login.company.com.

Parameters

service

an EOAuth2Service

 

Returns

the name of the service

Since: 3.28


e_oauth2_service_get_display_name ()

const gchar *
e_oauth2_service_get_display_name (EOAuth2Service *service);

Returns a human readable name of the service. This is similar to e_oauth2_service_get_name(), except this string should be localized, because it will be used in user-visible strings.

Parameters

service

an EOAuth2Service

 

Returns

the display name of the service

Since: 3.28


e_oauth2_service_get_client_id ()

const gchar *
e_oauth2_service_get_client_id (EOAuth2Service *service,
                                ESource *source);

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

Returns

application client ID, as provided by the server

Since: 3.28


e_oauth2_service_get_client_secret ()

const gchar *
e_oauth2_service_get_client_secret (EOAuth2Service *service,
                                    ESource *source);

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

Returns

application client secret, as provided by the server, or NULL.

[nullable]

Since: 3.28


e_oauth2_service_get_authentication_uri ()

const gchar *
e_oauth2_service_get_authentication_uri
                               (EOAuth2Service *service,
                                ESource *source);

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

Returns

an authentication URI, to be used to obtain the authentication code

Since: 3.28


e_oauth2_service_get_refresh_uri ()

const gchar *
e_oauth2_service_get_refresh_uri (EOAuth2Service *service,
                                  ESource *source);

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

Returns

a URI to be used to refresh the authentication token

Since: 3.28


e_oauth2_service_get_redirect_uri ()

const gchar *
e_oauth2_service_get_redirect_uri (EOAuth2Service *service,
                                   ESource *source);

Returns a value for the "redirect_uri" keys in the authenticate and get_token operations. The default implementation returns "urn:ietf:wg:oauth:2.0:oob".

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

Returns

The redirect_uri to use, or NULL for none.

[nullable]

Since: 3.28


e_oauth2_service_prepare_authentication_uri_query ()

void
e_oauth2_service_prepare_authentication_uri_query
                               (EOAuth2Service *service,
                                ESource *source,
                                GHashTable *uri_query);

The service can change what arguments are passed in the authentication URI in this method. The default implementation sets some values too, namely "response_type", "client_id", "redirect_uri" and "login_hint", if available in the source . These parameters are always provided, even when the interface implementer overrides this method.

The uri_query hash table expects both key and value to be newly allocated strings, which will be freed together with the hash table or when the key is replaced.

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

uri_query

query for the URI to use.

[element-type utf8 utf8]

Since: 3.28


e_oauth2_service_get_authentication_policy ()

EOAuth2ServiceNavigationPolicy
e_oauth2_service_get_authentication_policy
                               (EOAuth2Service *service,
                                ESource *source,
                                const gchar *uri);

Used to decide what to do when the server redirects to the next page. The default implementation always returns E_OAUTH2_SERVICE_NAVIGATION_POLICY_ALLOW.

This method is called before e_oauth2_service_extract_authorization_code() and can be used to block certain resources or to abort the authentication when the server redirects to an unexpected page (like when user denies authorization in the page).

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

uri

a URI of the navigation resource

 

Since: 3.28


e_oauth2_service_extract_authorization_code ()

gboolean
e_oauth2_service_extract_authorization_code
                               (EOAuth2Service *service,
                                ESource *source,
                                const gchar *page_title,
                                const gchar *page_uri,
                                const gchar *page_content,
                                gchar **out_authorization_code);

Tries to extract an authorization code from a web page provided by the server. The function can be called multiple times, whenever the page load is finished. The default implementation uses e_oauth2_service_util_extract_from_uri() to get the code from the given page_uri .

There can happen three states: 1) either the service cannot determine the authentication code from the page information, then the FALSE is returned and the out_authorization_code is left untouched; or 2) the server reported a failure, in which case the function returns TRUE and lefts the out_authorization_code untouched; or 3) the service could extract the authentication code from the given arguments, then the function returns TRUE and sets the received authorization code to out_authorization_code .

The page_content is NULL, unless flags returned by e_oauth2_service_get_flags() contain also E_OAUTH2_SERVICE_FLAG_EXTRACT_REQUIRES_PAGE_CONTENT.

This method is always called after e_oauth2_service_get_authentication_policy().

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

page_title

a web page title

 

page_uri

a web page URI

 

page_content

a web page content.

[nullable]

out_authorization_code

the extracted authorization code.

[out][transfer full]

Returns

whether could recognized successful or failed server response. The out_authorization_code is populated on success too.

Since: 3.28


e_oauth2_service_extract_error_message ()

gboolean
e_oauth2_service_extract_error_message
                               (EOAuth2Service *service,
                                ESource *source,
                                const gchar *page_title,
                                const gchar *page_uri,
                                const gchar *page_content,
                                gchar **out_error_message);

Tries to extract error message from the server response, return TRUE, when an error message could be found, in which case also sets the out_error_message with it. The default implementation uses e_oauth2_service_util_extract_from_uri(), returning either the error description or the error code, when the description is not found.

The out_error_message is expected to be plain text.

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

page_title

a web page title

 

page_uri

a web page URI

 

page_content

a web page content.

[nullable]

out_error_message

the extracted error message.

[out][transfer full]

Returns

whether could recognized failed server response. The out_error_message is populated on success.

Since: 3.48


e_oauth2_service_prepare_get_token_form ()

void
e_oauth2_service_prepare_get_token_form
                               (EOAuth2Service *service,
                                ESource *source,
                                const gchar *authorization_code,
                                GHashTable *form);

Sets additional form parameters to be used in the POST request when requesting access token after successfully obtained authorization code. The default implementation sets some values too, namely "code", "client_id", "client_secret", "redirect_uri" and "grant_type". These parameters are always provided, even when the interface implementer overrides this method.

The form hash table expects both key and value to be newly allocated strings, which will be freed together with the hash table or when the key is replaced.

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

authorization_code

authorization code, as returned from e_oauth2_service_extract_authorization_code()

 

form

form parameters to be used in the POST request.

[element-type utf8 utf8]

Since: 3.28


e_oauth2_service_prepare_get_token_message ()

void
e_oauth2_service_prepare_get_token_message
                               (EOAuth2Service *service,
                                ESource *source,
                                SoupMessage *message);

The service can change the message before it's sent to the e_oauth2_service_get_authentication_uri(), with POST data being provided by e_oauth2_service_prepare_get_token_form(). The default implementation does nothing with the message .

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

message

a SoupMessage

 

Since: 3.28


e_oauth2_service_prepare_refresh_token_form ()

void
e_oauth2_service_prepare_refresh_token_form
                               (EOAuth2Service *service,
                                ESource *source,
                                const gchar *refresh_token,
                                GHashTable *form);

Sets additional form parameters to be used in the POST request when requesting to refresh an access token. The default implementation sets some values too, namely "refresh_token", "client_id", "client_secret" and "grant_type". These parameters are always provided, even when the interface implementer overrides this method.

The form hash table expects both key and value to be newly allocated strings, which will be freed together with the hash table or when the key is replaced.

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

refresh_token

a refresh token to be used

 

form

form parameters to be used in the POST request.

[element-type utf8 utf8]

Since: 3.28


e_oauth2_service_prepare_refresh_token_message ()

void
e_oauth2_service_prepare_refresh_token_message
                               (EOAuth2Service *service,
                                ESource *source,
                                SoupMessage *message);

The service can change the message before it's sent to the e_oauth2_service_get_refresh_uri(), with POST data being provided by e_oauth2_service_prepare_refresh_token_form(). The default implementation does nothing with the message .

Parameters

service

an EOAuth2Service

 

source

an associated ESource

 

message

a SoupMessage

 

Since: 3.28


e_oauth2_service_receive_and_store_token_sync ()

gboolean
e_oauth2_service_receive_and_store_token_sync
                               (EOAuth2Service *service,
                                ESource *source,
                                const gchar *authorization_code,
                                EOAuth2ServiceRefSourceFunc ref_source,
                                gpointer ref_source_user_data,
                                GCancellable *cancellable,
                                GError **error);

Queries service at e_oauth2_service_get_refresh_uri() with a request to obtain a new access token, associated with the given authorization_code and stores it into the secret store on success.

Parameters

service

an EOAuth2Service

 

source

an ESource

 

authorization_code

authorization code provided by the server

 

ref_source

an EOAuth2ServiceRefSourceFunc function to obtain an ESource.

[scope call]

ref_source_user_data

user data for ref_source

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.28


e_oauth2_service_refresh_and_store_token_sync ()

gboolean
e_oauth2_service_refresh_and_store_token_sync
                               (EOAuth2Service *service,
                                ESource *source,
                                const gchar *refresh_token,
                                EOAuth2ServiceRefSourceFunc ref_source,
                                gpointer ref_source_user_data,
                                GCancellable *cancellable,
                                GError **error);

Queries service at e_oauth2_service_get_refresh_uri() with a request to refresh existing access token with provided refresh_token and stores it into the secret store on success.

Parameters

service

an EOAuth2Service

 

source

an ESource

 

refresh_token

refresh token as provided by the server

 

ref_source

an EOAuth2ServiceRefSourceFunc function to obtain an ESource.

[scope call]

ref_source_user_data

user data for ref_source

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.28


e_oauth2_service_delete_token_sync ()

gboolean
e_oauth2_service_delete_token_sync (EOAuth2Service *service,
                                    ESource *source,
                                    GCancellable *cancellable,
                                    GError **error);

Deletes token information for the service and source from the secret store.

Parameters

service

an EOAuth2Service

 

source

an ESource

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.28


e_oauth2_service_get_access_token_sync ()

gboolean
e_oauth2_service_get_access_token_sync
                               (EOAuth2Service *service,
                                ESource *source,
                                EOAuth2ServiceRefSourceFunc ref_source,
                                gpointer ref_source_user_data,
                                gchar **out_access_token,
                                gint *out_expires_in,
                                GCancellable *cancellable,
                                GError **error);

Reads access token information from the secret store for the source and in case it's expired it refreshes the token, if possible.

Free the returned out_access_token with g_free(), when no longer needed.

Parameters

service

an EOAuth2Service

 

source

an ESource

 

ref_source

an EOAuth2ServiceRefSourceFunc function to obtain an ESource.

[scope call]

ref_source_user_data

user data for ref_source

 

out_access_token

return location for the access token.

[out][transfer full]

out_expires_in

how many seconds the access token expires in.

[out]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE, when the returned access token has been set and it's not expired, FALSE otherwise.

Since: 3.28


e_oauth2_service_util_set_to_form ()

void
e_oauth2_service_util_set_to_form (GHashTable *form,
                                   const gchar *name,
                                   const gchar *value);

Sets value for name to form . The form should be the one used in e_oauth2_service_prepare_authentication_uri_query(), e_oauth2_service_prepare_get_token_form() or e_oauth2_service_prepare_refresh_token_form().

If the value is NULL, then the property named name is removed from the form instead.

Parameters

form

a GHashTable.

[element-type utf8 utf8]

name

a property name

 

value

a property value.

[nullable]

Since: 3.28


e_oauth2_service_util_take_to_form ()

void
e_oauth2_service_util_take_to_form (GHashTable *form,
                                    const gchar *name,
                                    gchar *value);

Takes ownership of value and sets it for name to form . The value will be freed with g_free(), when no longer needed. The form should be the one used in e_oauth2_service_prepare_authentication_uri_query(), e_oauth2_service_prepare_get_token_form() or e_oauth2_service_prepare_refresh_token_form().

If the value is NULL, then the property named name is removed from the form instead.

Parameters

form

a GHashTable.

[element-type utf8 utf8]

name

a property name

 

value

a property value.

[transfer full][nullable]

Since: 3.28


e_oauth2_service_util_extract_from_uri ()

gboolean
e_oauth2_service_util_extract_from_uri
                               (const gchar *in_uri,
                                gchar **out_authorization_code,
                                gchar **out_error_code,
                                gchar **out_error_description);

Extracts either an authorization code from a 'code' argument of the in_uri , or an error code from an 'error' argument of the in_uri and an error description from the 'error_description' argument of the in_uri .

Parameters

in_uri

a URI returned from the server

 

out_authorization_code

extracted authorization code, can be NULL.

[optional][out][transfer full][nullable]

out_error_code

extracted error code, can be NULL.

[optional][out][transfer full][nullable]

out_error_description

extracted error description, can be NULL.

[optional][out][transfer full][nullable]

Returns

TRUE, when any of the non-NULL out arguments had been populated.

Since: 3.48


e_oauth2_service_util_compile_value ()

const gchar *
e_oauth2_service_util_compile_value (const gchar *compile_value,
                                     gchar *out_glob_buff,
                                     gsize out_glob_buff_size);

Processes the compile_value and returns the result, which is stored into the out_glob_buff . The out_glob_buff should be large enough to hold the processed value and it should be a global memory buffer (usually statically allocated) initialized to 0, which is used to short-circuit the call, because the processing is done only if the first element of the out_glob_buff is 0, in all other cases the function immediately returns the out_glob_buff .

Parameters

compile_value

a value provided in the compile time

 

out_glob_buff

a global buffer to store the processed value to.

[out caller-allocates]

out_glob_buff_size

size of the out_glob_buff

 

Returns

processed compile_value , saved into *out_glob_buff

Since: 3.46

Types and Values

E_OAUTH2_SECRET_REFRESH_TOKEN

#define E_OAUTH2_SECRET_REFRESH_TOKEN "refresh_token"

E_OAUTH2_SECRET_ACCESS_TOKEN

#define E_OAUTH2_SECRET_ACCESS_TOKEN "access_token"

E_OAUTH2_SECRET_EXPIRES_AFTER

#define E_OAUTH2_SECRET_EXPIRES_AFTER "expires_after"

enum EOAuth2ServiceFlags

Flags of the OAuth2 service.

Members

E_OAUTH2_SERVICE_FLAG_NONE

No flag set

 

E_OAUTH2_SERVICE_FLAG_EXTRACT_REQUIRES_PAGE_CONTENT

the service requires also page content to be passed to e_oauth2_service_extract_authorization_code()

 

Since: 3.28


enum EOAuth2ServiceNavigationPolicy

A value used during querying authentication URI, to decide whether certain resource can be used or not. The E_OAUTH2_SERVICE_NAVIGATION_POLICY_ABORT can be used to abort the authentication query, like when user cancelled it.

Members

E_OAUTH2_SERVICE_NAVIGATION_POLICY_DENY

Deny navigation to the given web resource

 

E_OAUTH2_SERVICE_NAVIGATION_POLICY_ALLOW

Allow navigation to the given web resource

 

E_OAUTH2_SERVICE_NAVIGATION_POLICY_ABORT

Abort authentication processing

 

Since: 3.28


EOAuth2Service

typedef struct _EOAuth2Service EOAuth2Service;

Contains only private data that should be read and manipulated using the functions below.

Since: 3.28