ESourceAuthentication

## ESourceAuthentication ESourceAuthentication — ESource extension for authentication settings |

## Synopsis

    #include <libedataserver/libedataserver.h>

    struct              ESourceAuthentication;
    #define             E_SOURCE_EXTENSION_AUTHENTICATION
    gboolean            e_source_authentication_required    (ESourceAuthentication *extension);
    GSocketConnectable * e_source_authentication_ref_connectable
                                                            (ESourceAuthentication *extension);
    const gchar *       e_source_authentication_get_host    (ESourceAuthentication *extension);
    gchar *             e_source_authentication_dup_host    (ESourceAuthentication *extension);
    void                e_source_authentication_set_host    (ESourceAuthentication *extension,
                                                             const gchar *host);
    const gchar *       e_source_authentication_get_method  (ESourceAuthentication *extension);
    gchar *             e_source_authentication_dup_method  (ESourceAuthentication *extension);
    void                e_source_authentication_set_method  (ESourceAuthentication *extension,
                                                             const gchar *method);
    guint16             e_source_authentication_get_port    (ESourceAuthentication *extension);
    void                e_source_authentication_set_port    (ESourceAuthentication *extension,
                                                             guint16 port);
    gboolean            e_source_authentication_get_remember_password
                                                            (ESourceAuthentication *extension);
    void                e_source_authentication_set_remember_password
                                                            (ESourceAuthentication *extension,
                                                             gboolean remember_password);
    const gchar *       e_source_authentication_get_user    (ESourceAuthentication *extension);
    gchar *             e_source_authentication_dup_user    (ESourceAuthentication *extension);
    void                e_source_authentication_set_user    (ESourceAuthentication *extension,
                                                             const gchar *user);

## Object Hierarchy

      GObject
       +----ESourceExtension
             +----ESourceAuthentication

## Properties

      "connectable"              GSocketConnectable*   : Read
      "host"                     gchar*                : Read / Write / Construct
      "method"                   gchar*                : Read / Write / Construct
      "port"                     guint                 : Read / Write / Construct
      "remember-password"        gboolean              : Read / Write / Construct
      "user"                     gchar*                : Read / Write / Construct

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

## Details

### struct ESourceAuthentication

    struct ESourceAuthentication;

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

Since 3.6

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

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

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

`extension` : | an ESourceAuthentication
Returns : | a GSocketConnectable, or `NULL`. [transfer full]

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.

`extension` : | an ESourceAuthentication
Returns : | the host name of a remote account

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.

`extension` : | an ESourceAuthentication
Returns : | a newly-allocated copy of "host"

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.

`extension` : | an ESourceAuthentication
`host` : | a host name, or `NULL`. [allow-none]

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

`extension` : | an ESourceAuthentication
Returns : | the authentication method for a remote account

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.

`extension` : | an ESourceAuthentication
Returns : | a newly-allocated copy of "method"

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.

`extension` : | an ESourceAuthentication
`method` : | authentication method, or `NULL`. [allow-none]

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.

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

`extension` : | an ESourceAuthentication
`port` : | a port number

Since 3.6

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

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

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

`extension` : | an ESourceAuthentication
Returns : | the user name of a remote account

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.

`extension` : | an ESourceAuthentication
Returns : | a newly-allocated copy of "user"

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.

`extension` : | an ESourceAuthentication
`user` : | a user name, or `NULL`. [allow-none]

Since 3.6

## Property Details

### The `"connectable"` property

      "connectable"              GSocketConnectable*   : Read

A GSocketConnectable constructed from the host and port properties.

### The `"host"` property

      "host"                     gchar*                : Read / Write / Construct

Host name for the remote account.

Default value: ""

### The `"method"` property

      "method"                   gchar*                : Read / Write / Construct

Authentication method.

Default value: "none"

### The `"port"` property

      "port"                     guint                 : Read / Write / Construct

Port number for the remote account.

Allowed values: <= 65535

Default value: 0

### The `"remember-password"` property

      "remember-password"        gboolean              : Read / Write / Construct

Whether to offer to remember the password by default when prompted.

Default value: TRUE

### The `"user"` property

      "user"                     gchar*                : Read / Write / Construct

User name for the remote account.

Default value: NULL