EDataServer.OAuth2Service
Description: Reference for EDataServer.OAuth2Service

### Interface

# EDataServerOAuth2Service

since: 3.28

#### Description [src]

    interface EDataServer.OAuth2Service : GObject.Object

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

Available since: 3.28

#### Prerequisite

In order to implement OAuth2Service, your type must inherit from`GObject`.

#### Implementations

- EOAuth2ServiceGoogle
- EOAuth2ServiceOutlook
- EOAuth2ServiceYahoo

#### Functions

###### e_oauth2_service_util_compile_value

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

since: 3.46

###### e_oauth2_service_util_extract_from_uri

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

since: 3.48

###### e_oauth2_service_util_set_to_form

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

since: 3.28

###### e_oauth2_service_util_take_to_form

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

since: 3.28

#### Instance methods

###### e_oauth2_service_can_process

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

since: 3.28

###### e_oauth2_service_delete_token_sync

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

since: 3.28

###### e_oauth2_service_dup_credentials_prompter_cookies_sync

Additional cookies to be used in the prompt dialog when asking for the user credentials. The default implementation does not provide any cookies.

since: 3.54

###### e_oauth2_service_extract_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`.

since: 3.28

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

since: 3.48

###### e_oauth2_service_get_access_token_sync

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

since: 3.28

###### e_oauth2_service_get_authentication_policy

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

since: 3.28

###### e_oauth2_service_get_authentication_uri

No description available.

since: 3.28

###### e_oauth2_service_get_client_id

No description available.

since: 3.28

###### e_oauth2_service_get_client_secret

No description available.

since: 3.28

###### e_oauth2_service_get_display_name

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.

since: 3.28

###### e_oauth2_service_get_flags

No description available.

since: 3.28

###### e_oauth2_service_get_name

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.

since: 3.28

###### e_oauth2_service_get_redirect_uri

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

since: 3.28

###### e_oauth2_service_get_refresh_uri

No description available.

since: 3.28

###### e_oauth2_service_guess_can_process

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.

since: 3.28

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

since: 3.28

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

since: 3.28

###### e_oauth2_service_prepare_get_token_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`.

since: 3.28

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

since: 3.28

###### e_oauth2_service_prepare_refresh_token_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`.

since: 3.28

###### e_oauth2_service_receive_and_store_token_sync

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.

since: 3.28

###### e_oauth2_service_refresh_and_store_token_sync

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.

since: 3.28

#### Interface structure

    struct EDataServerOAuth2ServiceInterface {
      GTypeInterface parent_interface;
      gboolean (* can_process) (
        EOAuth2Service* service,
        ESource* source
      );
      gboolean (* guess_can_process) (
        EOAuth2Service* service,
        const gchar* protocol,
        const gchar* hostname
      );
      guint32 (* get_flags) (
        EOAuth2Service* service
      );
      const gchar* (* get_name) (
        EOAuth2Service* service
      );
      const gchar* (* get_display_name) (
        EOAuth2Service* service
      );
      const gchar* (* get_client_id) (
        EOAuth2Service* service,
        ESource* source
      );
      const gchar* (* get_client_secret) (
        EOAuth2Service* service,
        ESource* source
      );
      const gchar* (* get_authentication_uri) (
        EOAuth2Service* service,
        ESource* source
      );
      const gchar* (* get_refresh_uri) (
        EOAuth2Service* service,
        ESource* source
      );
      const gchar* (* get_redirect_uri) (
        EOAuth2Service* service,
        ESource* source
      );
      void (* prepare_authentication_uri_query) (
        EOAuth2Service* service,
        ESource* source,
        GHashTable* uri_query
      );
      EOAuth2ServiceNavigationPolicy (* get_authentication_policy) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* uri
      );
      gboolean (* extract_authorization_code) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* page_title,
        const gchar* page_uri,
        const gchar* page_content,
        gchar** out_authorization_code
      );
      void (* prepare_get_token_form) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* authorization_code,
        GHashTable* form
      );
      void (* prepare_get_token_message) (
        EOAuth2Service* service,
        ESource* source,
        SoupMessage* message
      );
      void (* prepare_refresh_token_form) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* refresh_token,
        GHashTable* form
      );
      void (* prepare_refresh_token_message) (
        EOAuth2Service* service,
        ESource* source,
        SoupMessage* message
      );
      gboolean (* extract_error_message) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* page_title,
        const gchar* page_uri,
        const gchar* page_content,
        gchar** out_error_message
      );
      GSList* (* dup_credentials_prompter_cookies_sync) (
        EOAuth2Service* service,
        ESource* source,
        GCancellable* cancellable
      );
      gpointer reserved;

    }

No description available.

###### Interface members

`parent_interface` |
    GTypeInterface
| No description available.
`can_process` |
    gboolean (* can_process) (
        EOAuth2Service* service,
        ESource* source
      )
| No description available.
`guess_can_process` |
    gboolean (* guess_can_process) (
        EOAuth2Service* service,
        const gchar* protocol,
        const gchar* hostname
      )
| No description available.
`get_flags` |
    guint32 (* get_flags) (
        EOAuth2Service* service
      )
| No description available.
`get_name` |
    const gchar* (* get_name) (
        EOAuth2Service* service
      )
| No description available.
`get_display_name` |
    const gchar* (* get_display_name) (
        EOAuth2Service* service
      )
| No description available.
`get_client_id` |
    const gchar* (* get_client_id) (
        EOAuth2Service* service,
        ESource* source
      )
| No description available.
`get_client_secret` |
    const gchar* (* get_client_secret) (
        EOAuth2Service* service,
        ESource* source
      )
| No description available.
`get_authentication_uri` |
    const gchar* (* get_authentication_uri) (
        EOAuth2Service* service,
        ESource* source
      )
| No description available.
`get_refresh_uri` |
    const gchar* (* get_refresh_uri) (
        EOAuth2Service* service,
        ESource* source
      )
| No description available.
`get_redirect_uri` |
    const gchar* (* get_redirect_uri) (
        EOAuth2Service* service,
        ESource* source
      )
| No description available.
`prepare_authentication_uri_query` |
    void (* prepare_authentication_uri_query) (
        EOAuth2Service* service,
        ESource* source,
        GHashTable* uri_query
      )
| No description available.
`get_authentication_policy` |
    EOAuth2ServiceNavigationPolicy (* get_authentication_policy) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* uri
      )
| No description available.
`extract_authorization_code` |
    gboolean (* extract_authorization_code) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* page_title,
        const gchar* page_uri,
        const gchar* page_content,
        gchar** out_authorization_code
      )
| No description available.
`prepare_get_token_form` |
    void (* prepare_get_token_form) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* authorization_code,
        GHashTable* form
      )
| No description available.
`prepare_get_token_message` |
    void (* prepare_get_token_message) (
        EOAuth2Service* service,
        ESource* source,
        SoupMessage* message
      )
| No description available.
`prepare_refresh_token_form` |
    void (* prepare_refresh_token_form) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* refresh_token,
        GHashTable* form
      )
| No description available.
`prepare_refresh_token_message` |
    void (* prepare_refresh_token_message) (
        EOAuth2Service* service,
        ESource* source,
        SoupMessage* message
      )
| No description available.
`extract_error_message` |
    gboolean (* extract_error_message) (
        EOAuth2Service* service,
        ESource* source,
        const gchar* page_title,
        const gchar* page_uri,
        const gchar* page_content,
        gchar** out_error_message
      )
| No description available.
`dup_credentials_prompter_cookies_sync` |
    GSList* (* dup_credentials_prompter_cookies_sync) (
        EOAuth2Service* service,
        ESource* source,
        GCancellable* cancellable
      )
| No description available.
`reserved` |
    gpointer
| No description available.

#### Virtual methods

###### EDataServer.OAuth2Service.can_process

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

since: 3.28

###### EDataServer.OAuth2Service.dup_credentials_prompter_cookies_sync

Additional cookies to be used in the prompt dialog when asking for the user credentials. The default implementation does not provide any cookies.

since: 3.54

###### EDataServer.OAuth2Service.extract_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`.

since: 3.28

###### EDataServer.OAuth2Service.extract_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.

since: 3.48

###### EDataServer.OAuth2Service.get_authentication_policy

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

since: 3.28

###### EDataServer.OAuth2Service.get_authentication_uri

No description available.

since: 3.28

###### EDataServer.OAuth2Service.get_client_id

No description available.

since: 3.28

###### EDataServer.OAuth2Service.get_client_secret

No description available.

since: 3.28

###### EDataServer.OAuth2Service.get_display_name

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.

since: 3.28

###### EDataServer.OAuth2Service.get_flags

No description available.

since: 3.28

###### EDataServer.OAuth2Service.get_name

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.

since: 3.28

###### EDataServer.OAuth2Service.get_redirect_uri

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

since: 3.28

###### EDataServer.OAuth2Service.get_refresh_uri

No description available.

since: 3.28

###### EDataServer.OAuth2Service.guess_can_process

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.

since: 3.28

###### EDataServer.OAuth2Service.prepare_authentication_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.

since: 3.28

###### EDataServer.OAuth2Service.prepare_get_token_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.

since: 3.28

###### EDataServer.OAuth2Service.prepare_get_token_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`.

since: 3.28

###### EDataServer.OAuth2Service.prepare_refresh_token_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.

since: 3.28

###### EDataServer.OAuth2Service.prepare_refresh_token_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`.

since: 3.28