## ESourceAuthentication

ESourceAuthentication — ESource extension for authentication settings

## Functions

gboolean | e_source_authentication_required ()
GSocketConnectable * | e_source_authentication_ref_connectable ()
const gchar * | e_source_authentication_get_host ()
gchar * | e_source_authentication_dup_host ()
void | e_source_authentication_set_host ()
const gchar * | e_source_authentication_get_method ()
gchar * | e_source_authentication_dup_method ()
void | e_source_authentication_set_method ()
guint16 | e_source_authentication_get_port ()
void | e_source_authentication_set_port ()
const gchar * | e_source_authentication_get_proxy_uid ()
gchar * | e_source_authentication_dup_proxy_uid ()
void | e_source_authentication_set_proxy_uid ()
gboolean | e_source_authentication_get_remember_password ()
void | e_source_authentication_set_remember_password ()
const gchar * | e_source_authentication_get_user ()
gchar * | e_source_authentication_dup_user ()
void | e_source_authentication_set_user ()
const gchar * | e_source_authentication_get_credential_name ()
gchar * | e_source_authentication_dup_credential_name ()
void | e_source_authentication_set_credential_name ()
gboolean | e_source_authentication_get_is_external ()
void | e_source_authentication_set_is_external ()

## Types and Values

#define | E_SOURCE_EXTENSION_AUTHENTICATION
struct | ESourceAuthentication

## Object Hierarchy

        GObject
        ╰── ESourceExtension
            ╰── ESourceAuthentication

## Includes

    #include <libedataserver/libedataserver.h>

## Description

The ESourceAuthentication extension tracks authentication settings for a user account on a remote server.

Access the extension as follows:

    1
    2
    3
    4
    5

    #include <libedataserver/libedataserver.h>

    ESourceAuthentication *extension;

    extension = e_source_get_extension (source, E_SOURCE_EXTENSION_AUTHENTICATION);

## Functions

### e_source_authentication_required ()

    gboolean
    e_source_authentication_required (ESourceAuthentication *extension);

This is a convenience function which returns whether authentication is required at all, regardless of the method used. This relies on the convention of setting “method” to "none" when authentication is not required.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

whether authentication is required at all

Since: 3.6

### e_source_authentication_ref_connectable ()

    GSocketConnectable *
    e_source_authentication_ref_connectable
                                   (ESourceAuthentication *extension);

Returns a GSocketConnectable instance constructed from `extension` 's “host” and “port” properties, or `NULL` if the “host” is not set.

The returned GSocketConnectable is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

a GSocketConnectable, or `NULL`.

[transfer full][nullable]

Since: 3.8

### e_source_authentication_get_host ()

    const gchar *
    e_source_authentication_get_host (ESourceAuthentication *extension);

Returns the host name used to authenticate to a remote account.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

the host name of a remote account.

[nullable]

Since: 3.6

### e_source_authentication_dup_host ()

    gchar *
    e_source_authentication_dup_host (ESourceAuthentication *extension);

Thread-safe variation of `e_source_authentication_get_host()`. Use this function when accessing `extension` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

a newly-allocated copy of “host”.

[nullable]

Since: 3.6

### e_source_authentication_set_host ()

    void
    e_source_authentication_set_host (ESourceAuthentication *extension,
                                      const gchar *host);

Sets the host name used to authenticate to a remote account.

The internal copy of `host` is automatically stripped of leading and trailing whitespace. If the resulting string is empty, `NULL` is set instead.

#### Parameters

extension | an ESourceAuthentication |
host | a host name, or `NULL`. | [nullable]

Since: 3.6

### e_source_authentication_get_method ()

    const gchar *
    e_source_authentication_get_method (ESourceAuthentication *extension);

Returns the authentication method for a remote account. There are no pre-defined method names; backends are free to set this however they wish. If authentication is not required for a remote account, the convention is to set “method” to "none".

#### Parameters

extension | an ESourceAuthentication |

#### Returns

the authentication method for a remote account.

[nullable]

Since: 3.6

### e_source_authentication_dup_method ()

    gchar *
    e_source_authentication_dup_method (ESourceAuthentication *extension);

Thread-safe variation of `e_source_authentication_get_method()`. Use this function when accessing `extension` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

a newly-allocated copy of “method”.

[nullable]

Since: 3.6

### e_source_authentication_set_method ()

    void
    e_source_authentication_set_method (ESourceAuthentication *extension,
                                        const gchar *method);

Sets the authentication method for a remote account. There are no pre-defined method names; backends are free to set this however they wish. If authentication is not required for a remote account, the convention is to set the method to "none". In keeping with that convention, “method” will be set to "none" if `method` is `NULL` or an empty string.

#### Parameters

extension | an ESourceAuthentication |
method | authentication method, or `NULL`. | [nullable]

Since: 3.6

### e_source_authentication_get_port ()

    guint16
    e_source_authentication_get_port (ESourceAuthentication *extension);

Returns the port number used to authenticate to a remote account.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

the port number of a remote account

Since: 3.6

### e_source_authentication_set_port ()

    void
    e_source_authentication_set_port (ESourceAuthentication *extension,
                                      guint16 port);

Sets the port number used to authenticate to a remote account.

#### Parameters

extension | an ESourceAuthentication |
port | a port number |

Since: 3.6

### e_source_authentication_get_proxy_uid ()

    const gchar *
    e_source_authentication_get_proxy_uid (ESourceAuthentication *extension);

Returns the “uid” of the ESource that holds network proxy settings for use when connecting to a remote account.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

the proxy profile “uid”

Since: 3.12

### e_source_authentication_dup_proxy_uid ()

    gchar *
    e_source_authentication_dup_proxy_uid (ESourceAuthentication *extension);

Thread-safe variation of `e_source_authentication_get_proxy_uid()`. Use this function when accessing `extension` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

a newly-allocated copy of “proxy-uid”

Since: 3.12

### e_source_authentication_set_proxy_uid ()

    void
    e_source_authentication_set_proxy_uid (ESourceAuthentication *extension,
                                           const gchar *proxy_uid);

Sets the “uid” of the ESource that holds network proxy settings for use when connecting to a remote account.

#### Parameters

extension | an ESourceAuthentication |
proxy_uid | the proxy profile “uid” |

Since: 3.12

### e_source_authentication_get_remember_password ()

    gboolean
    e_source_authentication_get_remember_password
                                   (ESourceAuthentication *extension);

Returns whether to offer to remember the provided password by default in password prompts. This way, if the user unchecks the option it will be unchecked by default in future password prompts.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

whether to offer to remember the password by default

Since: 3.10

### e_source_authentication_set_remember_password ()

    void
    e_source_authentication_set_remember_password
                                   (ESourceAuthentication *extension,
                                    gboolean remember_password);

Sets whether to offer to remember the provided password by default in password prompts. This way, if the user unchecks the option it will be unchecked by default in future password prompts.

#### Parameters

extension | an ESourceAuthentication |
remember_password | whether to offer to remember the password by default |

Since: 3.10

### e_source_authentication_get_user ()

    const gchar *
    e_source_authentication_get_user (ESourceAuthentication *extension);

Returns the user name used to authenticate to a remote account.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

the user name of a remote account.

[nullable]

Since: 3.6

### e_source_authentication_dup_user ()

    gchar *
    e_source_authentication_dup_user (ESourceAuthentication *extension);

Thread-safe variation of `e_source_authentication_get_user()`. Use this function when accessing `extension` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

a newly-allocated copy of “user”.

[nullable]

Since: 3.6

### e_source_authentication_set_user ()

    void
    e_source_authentication_set_user (ESourceAuthentication *extension,
                                      const gchar *user);

Sets the user name used to authenticate to a remote account.

The internal copy of `user` is automatically stripped of leading and trailing whitespace. If the resulting string is empty, `NULL` is set instead.

#### Parameters

extension | an ESourceAuthentication |
user | a user name, or `NULL`. | [nullable]

Since: 3.6

### e_source_authentication_get_credential_name ()

    const gchar *
    e_source_authentication_get_credential_name
                                   (ESourceAuthentication *extension);

Returns the credential name used to pass the stored or gathered credential (like password) into the `e_source_invoke_authenticate()`. This is a counterpart of the authentication method. The `NULL` means to use the default name, which is E_SOURCE_CREDENTIAL_PASSWORD.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

the credential name to use for authentication, or `NULL`.

[nullable]

Since: 3.16

### e_source_authentication_dup_credential_name ()

    gchar *
    e_source_authentication_dup_credential_name
                                   (ESourceAuthentication *extension);

Thread-safe variation of `e_source_authentication_get_credential_name()`. Use this function when accessing `extension` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

extension | an ESourceAuthentication |

#### Returns

a newly-allocated copy of “credential-name”.

[nullable]

Since: 3.16

### e_source_authentication_set_credential_name ()

    void
    e_source_authentication_set_credential_name
                                   (ESourceAuthentication *extension,
                                    const gchar *credential_name);

Sets the credential name used to pass the stored or gathered credential (like password) into the `e_source_invoke_authenticate()`. This is a counterpart of the authentication method. The `NULL` means to use the default name, which is E_SOURCE_CREDENTIAL_PASSWORD.

The internal copy of `credential_name` is automatically stripped of leading and trailing whitespace. If the resulting string is empty, `NULL` is set instead.

#### Parameters

extension | an ESourceAuthentication |
credential_name | a credential name, or `NULL`. | [nullable]

Since: 3.16

### e_source_authentication_get_is_external ()

    gboolean
    e_source_authentication_get_is_external
                                   (ESourceAuthentication *extension);

Get if the authentication is done by an external application such as a Single Sign On application (e.g. GNOME Online Accounts)

#### Parameters

extension | an ESourceAuthentication |

#### Returns

`TRUE` if the authentication is done by an external application, `FALSE` otherwise

Since: 3.36

### e_source_authentication_set_is_external ()

    void
    e_source_authentication_set_is_external
                                   (ESourceAuthentication *extension,
                                    gboolean is_external);

Set if the authentication is done by an external application such as a Single Sign On application (e.g. GNOME Online Accounts)

#### Parameters

extension | an ESourceAuthentication |
is_external | `TRUE` if the authentication is done using an external application, `FALSE` otherwise |

Since: 3.36

## Types and Values

### E_SOURCE_EXTENSION_AUTHENTICATION

    #define E_SOURCE_EXTENSION_AUTHENTICATION "Authentication"

Pass this extension name to `e_source_get_extension()` to access ESourceAuthentication. This is also used as a group name in key files.

Since: 3.6

### struct ESourceAuthentication

    struct ESourceAuthentication;

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

Since: 3.6