EOAuth2Service: Evolution-Data-Server Reference Manual

## EOAuth2Service EOAuth2Service — An interface for an OAuth2 service |

## Functions

ESource * | (*EOAuth2ServiceRefSourceFunc) ()
gboolean | e_oauth2_service_can_process ()
gboolean | e_oauth2_service_guess_can_process ()
guint32 | e_oauth2_service_get_flags ()
const gchar * | e_oauth2_service_get_name ()
const gchar * | e_oauth2_service_get_display_name ()
const gchar * | e_oauth2_service_get_client_id ()
const gchar * | e_oauth2_service_get_client_secret ()
const gchar * | e_oauth2_service_get_authentication_uri ()
const gchar * | e_oauth2_service_get_refresh_uri ()
const gchar * | e_oauth2_service_get_redirect_uri ()
void | e_oauth2_service_prepare_authentication_uri_query ()
EOAuth2ServiceNavigationPolicy | e_oauth2_service_get_authentication_policy ()
gboolean | e_oauth2_service_extract_authorization_code ()
void | e_oauth2_service_prepare_get_token_form ()
void | e_oauth2_service_prepare_get_token_message ()
void | e_oauth2_service_prepare_refresh_token_form ()
void | e_oauth2_service_prepare_refresh_token_message ()
gboolean | e_oauth2_service_receive_and_store_token_sync ()
gboolean | e_oauth2_service_refresh_and_store_token_sync ()
gboolean | e_oauth2_service_delete_token_sync ()
gboolean | e_oauth2_service_get_access_token_sync ()
void | e_oauth2_service_util_set_to_form ()
void | e_oauth2_service_util_take_to_form ()

## Types and Values

#define | E_OAUTH2_SECRET_REFRESH_TOKEN
#define | E_OAUTH2_SECRET_ACCESS_TOKEN
#define | E_OAUTH2_SECRET_EXPIRES_AFTER
enum | EOAuth2ServiceFlags
enum | EOAuth2ServiceNavigationPolicy
| EOAuth2Service

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

#### Parameters

user_data | user data, as passed to `e_oauth2_service_get_token_sync()` or `e_oauth2_service_refresh_token_sync()` |
uid | an ESource UID to return |

#### 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 |

#### Returns

one of EOAuth2ServiceNavigationPolicy

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.

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_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 `ref_source_user_data` user data for `ref_source` . | [scope call]
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 |
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 |
name | a property name |
value | a property value. | [transfer full][nullable]

Since: 3.28

## 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