Top | ![]() |
![]() |
![]() |
![]() |
#define | E_OAUTH2_SECRET_REFRESH_TOKEN |
#define | E_OAUTH2_SECRET_ACCESS_TOKEN |
#define | E_OAUTH2_SECRET_EXPIRES_AFTER |
enum | EOAuth2ServiceFlags |
enum | EOAuth2ServiceNavigationPolicy |
EOAuth2Service |
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.
ESource * (*EOAuth2ServiceRefSourceFunc) (gpointer user_data
,const gchar *uid
);
user_data |
user data, as passed to |
|
uid |
an ESource UID to return |
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
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.
Since: 3.28
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.
service |
||
protocol |
a protocol to search the service for, like "imap", or |
[nullable] |
hostname |
a host name to search the service for, like "server.example.com", or |
[nullable] |
Since: 3.28
guint32
e_oauth2_service_get_flags (EOAuth2Service *service
);
bit-or of EOAuth2ServiceFlags for the service
. The default
implementation returns E_OAUTH2_SERVICE_FLAG_NONE
.
Since: 3.28
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.
Since: 3.28
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.
Since: 3.28
const gchar * e_oauth2_service_get_client_id (EOAuth2Service *service
,ESource *source
);
Since: 3.28
const gchar * e_oauth2_service_get_client_secret (EOAuth2Service *service
,ESource *source
);
Since: 3.28
const gchar * e_oauth2_service_get_authentication_uri (EOAuth2Service *service
,ESource *source
);
Since: 3.28
const gchar * e_oauth2_service_get_refresh_uri (EOAuth2Service *service
,ESource *source
);
Since: 3.28
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".
Since: 3.28
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.
service |
||
source |
an associated ESource |
|
uri_query |
query for the URI to use. |
[element-type utf8 utf8] |
Since: 3.28
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).
Since: 3.28
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()
.
service |
||
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] |
whether could recognized successful or failed server response.
The out_authorization_code
is populated on success too.
Since: 3.28
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.
service |
||
source |
an associated ESource |
|
authorization_code |
authorization code, as returned from |
|
form |
form parameters to be used in the POST request. |
[element-type utf8 utf8] |
Since: 3.28
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
.
Since: 3.28
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.
service |
||
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
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
.
Since: 3.28
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.
service |
||
source |
an ESource |
|
authorization_code |
authorization code provided by the server |
|
ref_source |
an EOAuth2ServiceRefSourceFunc function to obtain an ESource
|
[scope call] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.28
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.
service |
||
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 |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.28
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.
service |
||
source |
an ESource |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.28
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.
service |
||
source |
an ESource |
|
ref_source |
an EOAuth2ServiceRefSourceFunc function to obtain an ESource. |
[scope call] |
ref_source_user_data |
user data for |
|
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 |
|
error |
return location for a GError, or |
Since: 3.28
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.
Since: 3.28
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.
Since: 3.28
Flags of the OAuth2 service.
No flag set |
||
the service requires also page
content to be passed to |
Since: 3.28
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.
Since: 3.28
typedef struct _EOAuth2Service EOAuth2Service;
Contains only private data that should be read and manipulated using the functions below.
Since: 3.28