## 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);
    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
      "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_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 `"user"` property

      "user"                     gchar*                : Read / Write / Construct

User name for the remote account.

Default value: NULL