## ESourceWebdav

ESourceWebdav — ESource extension for WebDAV settings

## Synopsis

    #include <libedataserver/libedataserver.h>

    struct              ESourceWebdav;
    #define             E_SOURCE_EXTENSION_WEBDAV_BACKEND
    gboolean            e_source_webdav_get_avoid_ifmatch   (ESourceWebdav *extension);
    void                e_source_webdav_set_avoid_ifmatch   (ESourceWebdav *extension,
                                                             gboolean avoid_ifmatch);
    gboolean            e_source_webdav_get_calendar_auto_schedule
                                                            (ESourceWebdav *extension);
    void                e_source_webdav_set_calendar_auto_schedule
                                                            (ESourceWebdav *extension,
                                                             gboolean calendar_auto_schedule);
    const gchar *       e_source_webdav_get_display_name    (ESourceWebdav *extension);
    gchar *             e_source_webdav_dup_display_name    (ESourceWebdav *extension);
    void                e_source_webdav_set_display_name    (ESourceWebdav *extension,
                                                             const gchar *display_name);
    const gchar *       e_source_webdav_get_email_address   (ESourceWebdav *extension);
    gchar *             e_source_webdav_dup_email_address   (ESourceWebdav *extension);
    void                e_source_webdav_set_email_address   (ESourceWebdav *extension,
                                                             const gchar *email_address);
    const gchar *       e_source_webdav_get_resource_path   (ESourceWebdav *extension);
    gchar *             e_source_webdav_dup_resource_path   (ESourceWebdav *extension);
    void                e_source_webdav_set_resource_path   (ESourceWebdav *extension,
                                                             const gchar *resource_path);
    const gchar *       e_source_webdav_get_resource_query  (ESourceWebdav *extension);
    gchar *             e_source_webdav_dup_resource_query  (ESourceWebdav *extension);
    void                e_source_webdav_set_resource_query  (ESourceWebdav *extension,
                                                             const gchar *resource_query);
    const gchar *       e_source_webdav_get_ssl_trust       (ESourceWebdav *extension);
    gchar *             e_source_webdav_dup_ssl_trust       (ESourceWebdav *extension);
    void                e_source_webdav_set_ssl_trust       (ESourceWebdav *extension,
                                                             const gchar *ssl_trust);
    SoupURI *           e_source_webdav_dup_soup_uri        (ESourceWebdav *extension);
    void                e_source_webdav_set_soup_uri        (ESourceWebdav *extension,
                                                             SoupURI *soup_uri);
    enum                ETrustPromptResponse;
    ETrustPromptResponse e_source_webdav_prepare_ssl_trust_prompt
                                                            (ESourceWebdav *extension,
                                                             SoupMessage *message,
                                                             struct _ESourceRegistry *registry,
                                                             struct _ENamedParameters *parameters);
    ETrustPromptResponse e_source_webdav_prepare_ssl_trust_prompt_with_parent
                                                            (ESourceWebdav *extension,
                                                             SoupMessage *message,
                                                             ESource *parent_source,
                                                             struct _ENamedParameters *parameters);
    void                e_source_webdav_store_ssl_trust_prompt
                                                            (ESourceWebdav *extension,
                                                             SoupMessage *message,
                                                             ETrustPromptResponse response);
    void                e_source_webdav_unset_temporary_ssl_trust
                                                            (ESourceWebdav *extension);

    gboolean            e_source_webdav_get_ignore_invalid_cert
                                                            (ESourceWebdav *extension);
    void                e_source_webdav_set_ignore_invalid_cert
                                                            (ESourceWebdav *extension,
                                                             gboolean ignore_invalid_cert);

## Object Hierarchy

      GObject
       +----ESourceExtension
             +----ESourceWebdav

## Properties

      "avoid-ifmatch"            gboolean              : Read / Write / Construct
      "calendar-auto-schedule"   gboolean              : Read / Write / Construct
      "display-name"             gchar*                : Read / Write / Construct
      "email-address"            gchar*                : Read / Write / Construct
      "ignore-invalid-cert"      gboolean              : Read / Write / Construct
      "resource-path"            gchar*                : Read / Write / Construct
      "resource-query"           gchar*                : Read / Write / Construct
      "soup-uri"                 SoupURI*              : Read / Write
      "ssl-trust"                gchar*                : Read / Write / Construct

## Description

The ESourceWebdav extension tracks settings for accessing resources on a remote WebDAV server.

This class exists in libedataserver because we have several WebDAV-based backends. Each of these backends is free to use this class directly or subclass it with additional settings. Subclasses should override the extension name.

The SoupURI is parsed into components and distributed across several other built-in extensions such as ESourceAuthentication and ESourceSecurity.

Access the extension as follows:

    1
    2
    3
    4
    5

    #include <libedataserver/libedataserver.h>

    ESourceWebdav *extension;

    extension = e_source_get_extension (source, E_SOURCE_EXTENSION_WEBDAV_BACKEND);

## Details

### struct ESourceWebdav

    struct ESourceWebdav;

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

Since 3.6

### E_SOURCE_EXTENSION_WEBDAV_BACKEND

    #define E_SOURCE_EXTENSION_WEBDAV_BACKEND "WebDAV Backend"

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

Since 3.6

### e_source_webdav_get_avoid_ifmatch ()

    gboolean            e_source_webdav_get_avoid_ifmatch   (ESourceWebdav *extension);

This setting works around a bug in older Apache mod_dav versions.

### Note

We may deprecate this once Apache 2.2.8 or newer becomes sufficiently ubiquitous, or we figure out a way to detect and work around the bug automatically.

`extension` : | an ESourceWebdav
Returns : | whether the WebDAV server is known to exhibit the bug

Since 3.6

### e_source_webdav_set_avoid_ifmatch ()

    void                e_source_webdav_set_avoid_ifmatch   (ESourceWebdav *extension,
                                                             gboolean avoid_ifmatch);

This setting works around a bug in older Apache mod_dav versions.

### Note

We may deprecate this once Apache 2.2.8 or newer becomes sufficiently ubiquitous, or we figure out a way to detect and work around the bug automatically.

`extension` : | an ESourceWebdav
`avoid_ifmatch` : | whether the WebDAV server is known to exhibit the bug

Since 3.6

### e_source_webdav_get_calendar_auto_schedule ()

    gboolean            e_source_webdav_get_calendar_auto_schedule
                                                            (ESourceWebdav *extension);

FIXME Document me!

`extension` : | an ESourceWebdav

Since 3.6

### e_source_webdav_set_calendar_auto_schedule ()

    void                e_source_webdav_set_calendar_auto_schedule
                                                            (ESourceWebdav *extension,
                                                             gboolean calendar_auto_schedule);

FIXME Document me!

`extension` : | an ESourceWebdav
`calendar_auto_schedule` : | whether the server supports the "calendar-auto-schedule" feature of CalDAV

Since 3.6

### e_source_webdav_get_display_name ()

    const gchar *       e_source_webdav_get_display_name    (ESourceWebdav *extension);

Returns the last known display name of a WebDAV resource, which may differ from the "display-name" property of the ESource to which `extension` belongs.

`extension` : | an ESourceWebdav
Returns : | the display name of the WebDAV resource

Since 3.6

### e_source_webdav_dup_display_name ()

    gchar *             e_source_webdav_dup_display_name    (ESourceWebdav *extension);

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

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

`extension` : | an ESourceWebdav
Returns : | a newly-allocated copy of "display-name"

Since 3.6

### e_source_webdav_set_display_name ()

    void                e_source_webdav_set_display_name    (ESourceWebdav *extension,
                                                             const gchar *display_name);

Updates the last known display name of a WebDAV resource, which may differ from the "display-name" property of the ESource to which `extension` belongs.

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

`extension` : | an ESourceWebdav
`display_name` : | the display name of the WebDAV resource, or `NULL`. [allow-none]

Since 3.6

### e_source_webdav_get_email_address ()

    const gchar *       e_source_webdav_get_email_address   (ESourceWebdav *extension);

Returns the user's email address which can be passed to a CalDAV server if the user wishes to receive scheduling messages.

`extension` : | an ESourceWebdav
Returns : | the user's email address

Since 3.6

### e_source_webdav_dup_email_address ()

    gchar *             e_source_webdav_dup_email_address   (ESourceWebdav *extension);

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

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

`extension` : | an ESourceWebdav
Returns : | the newly-allocated copy of "email-address"

Since 3.6

### e_source_webdav_set_email_address ()

    void                e_source_webdav_set_email_address   (ESourceWebdav *extension,
                                                             const gchar *email_address);

Sets the user's email address which can be passed to a CalDAV server if the user wishes to receive scheduling messages.

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

`extension` : | an ESourceWebdav
`email_address` : | the user's email address, or `NULL`. [allow-none]

Since 3.6

### e_source_webdav_get_resource_path ()

    const gchar *       e_source_webdav_get_resource_path   (ESourceWebdav *extension);

Returns the absolute path to a resource on a WebDAV server.

`extension` : | an ESourceWebdav
Returns : | the absolute path to a WebDAV resource

Since 3.6

### e_source_webdav_dup_resource_path ()

    gchar *             e_source_webdav_dup_resource_path   (ESourceWebdav *extension);

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

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

`extension` : | an ESourceWebdav
Returns : | the newly-allocated copy of "resource-path"

Since 3.6

### e_source_webdav_set_resource_path ()

    void                e_source_webdav_set_resource_path   (ESourceWebdav *extension,
                                                             const gchar *resource_path);

Sets the absolute path to a resource on a WebDAV server.

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

`extension` : | an ESourceWebdav
`resource_path` : | the absolute path to a WebDAV resource, or `NULL`. [allow-none]

Since 3.6

### e_source_webdav_get_resource_query ()

    const gchar *       e_source_webdav_get_resource_query  (ESourceWebdav *extension);

Returns the URI query required to access a resource on a WebDAV server.

This is typically used when the "resource-path" points not to the resource itself but to a web program that generates the resource content on-the-fly. The "resource-query" holds the input values for the program.

`extension` : | an ESourceWebdav
Returns : | the query to access a WebDAV resource

Since 3.6

### e_source_webdav_dup_resource_query ()

    gchar *             e_source_webdav_dup_resource_query  (ESourceWebdav *extension);

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

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

`extension` : | an ESourceWebdav
Returns : | the newly-allocated copy of "resource-query"

Since 3.6

### e_source_webdav_set_resource_query ()

    void                e_source_webdav_set_resource_query  (ESourceWebdav *extension,
                                                             const gchar *resource_query);

Sets the URI query required to access a resource on a WebDAV server.

This is typically used when the "resource-path" points not to the resource itself but to a web program that generates the resource content on-the-fly. The "resource-query" holds the input values for the program.

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

`extension` : | an ESourceWebdav
`resource_query` : | the query to access a WebDAV resource, or `NULL`. [allow-none]

Since 3.6

### e_source_webdav_get_ssl_trust ()

    const gchar *       e_source_webdav_get_ssl_trust       (ESourceWebdav *extension);

Returns an SSL certificate trust for the `extension`. The value encodes three parameters, divided by a pipe '|', the first is users preference, can be one of "reject", "accept", "temporary-reject" and "temporary-accept". The second is a host name for which the trust was set. Finally the last is a SHA1 hash of the certificate. This is not meant to be changed by a caller, it is supposed to be manipulated with `e_source_webdav_prepare_ssl_trust_prompt()` and `e_source_webdav_store_ssl_trust_prompt()`.

`extension` : | an ESourceWebdav
Returns : | an SSL certificate trust for the `extension`

Since 3.8

### e_source_webdav_dup_ssl_trust ()

    gchar *             e_source_webdav_dup_ssl_trust       (ESourceWebdav *extension);

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

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

`extension` : | an ESourceWebdav
Returns : | the newly-allocated copy of "ssl-trust"

Since 3.8

### e_source_webdav_set_ssl_trust ()

    void                e_source_webdav_set_ssl_trust       (ESourceWebdav *extension,
                                                             const gchar *ssl_trust);

Sets the SSL certificate trust. See `e_source_webdav_get_ssl_trust()` for more infomation about its content and how to use it.

`extension` : | an ESourceWebdav
`ssl_trust` : | the ssl_trust to store, or `NULL` to unset. [allow-none]

Since 3.8

### e_source_webdav_dup_soup_uri ()

    SoupURI *           e_source_webdav_dup_soup_uri        (ESourceWebdav *extension);

This is a convenience function which returns a newly-allocated SoupURI, its contents assembled from the ESourceAuthentication extension, the ESourceSecurity extension, and `extension` itself. Free the returned SoupURI with `soup_uri_free()`.

`extension` : | an ESourceWebdav
Returns : | a newly-allocated SoupURI. [transfer full]

Since 3.6

### e_source_webdav_set_soup_uri ()

    void                e_source_webdav_set_soup_uri        (ESourceWebdav *extension,
                                                             SoupURI *soup_uri);

This is a convenience function which propagates the components of `uri` to the ESourceAuthentication extension, the ESourceSecurity extension, and `extension` itself. (The "fragment" component of `uri` is ignored.)

`extension` : | an ESourceWebdav
`soup_uri` : | a SoupURI

Since 3.6

### enum ETrustPromptResponse

    typedef enum {
    	E_TRUST_PROMPT_RESPONSE_UNKNOWN = -1,
    	E_TRUST_PROMPT_RESPONSE_REJECT = 0,
    	E_TRUST_PROMPT_RESPONSE_ACCEPT = 1,
    	E_TRUST_PROMPT_RESPONSE_ACCEPT_TEMPORARILY = 2,
    	E_TRUST_PROMPT_RESPONSE_REJECT_TEMPORARILY = 3
    } ETrustPromptResponse;

XXX Document me!

`E_TRUST_PROMPT_RESPONSE_UNKNOWN` |
`E_TRUST_PROMPT_RESPONSE_REJECT` |
`E_TRUST_PROMPT_RESPONSE_ACCEPT` |
`E_TRUST_PROMPT_RESPONSE_ACCEPT_TEMPORARILY` |
`E_TRUST_PROMPT_RESPONSE_REJECT_TEMPORARILY` |

Since 3.8

### e_source_webdav_prepare_ssl_trust_prompt ()

    ETrustPromptResponse e_source_webdav_prepare_ssl_trust_prompt
                                                            (ESourceWebdav *extension,
                                                             SoupMessage *message,
                                                             struct _ESourceRegistry *registry,
                                                             struct _ENamedParameters *parameters);

Checks `messages`'s certificate against currently stored trust response and either returns what to do immediately, or returns E_TRUST_PROMPT_RESPONSE_UNKNOWN and populates `parameters` with necessary values for a trust prompt.

`extension` : | an ESourceWebdav
`message` : | a SoupMessage with SOUP_STATUS_SSL_FAILED status code
`registry` : | an ESourceRegistry, to use for parent lookups
`parameters` : | an ENamedParameters to be populated
Returns : | What to do with SSL connection, where E_TRUST_PROMPT_RESPONSE_UNKNOWN means 'ask a user, with populated parameters'. Note: The E_TRUST_PROMPT_RESPONSE_REJECT is returned on any errors, like the `message` not being with the SOUP_STATUS_SSL_FAILED status code, no certificate being stored in the `message` and so on.

Since 3.8

### e_source_webdav_prepare_ssl_trust_prompt_with_parent ()

    ETrustPromptResponse e_source_webdav_prepare_ssl_trust_prompt_with_parent
                                                            (ESourceWebdav *extension,
                                                             SoupMessage *message,
                                                             ESource *parent_source,
                                                             struct _ENamedParameters *parameters);

The same as `e_source_webdav_prepare_ssl_trust_prompt()`, only takes `parent_source` directly, instead of an ESourceRegistry.

See `e_source_webdav_prepare_ssl_trust_prompt()` for more details.

`extension` : | an ESourceWebdav
`message` : | a SoupMessage with SOUP_STATUS_SSL_FAILED status code
`parent_source` : | an ESource, parent of the `extension`'s source
`parameters` : | an ENamedParameters to be populated

Since 3.8

### e_source_webdav_store_ssl_trust_prompt ()

    void                e_source_webdav_store_ssl_trust_prompt
                                                            (ESourceWebdav *extension,
                                                             SoupMessage *message,
                                                             ETrustPromptResponse response);

Stores user's response from a trust prompt, thus it is re-used the next time it'll be needed. An E_TRUST_PROMPT_RESPONSE_UNKNOWN is treated as a temporary reject, which means the user will be asked again.

`extension` : | an ESourceWebdav
`message` : | a SoupMessage with SOUP_STATUS_SSL_FAILED status code
`response` : | user's response from a trust prompt

Since 3.8

### e_source_webdav_unset_temporary_ssl_trust ()

    void                e_source_webdav_unset_temporary_ssl_trust
                                                            (ESourceWebdav *extension);

Unsets temporary trust set on this `extension`, but keeps it as is for other values.

`extension` : | an ESourceWebdav

Since 3.8

### e_source_webdav_get_ignore_invalid_cert ()

    gboolean            e_source_webdav_get_ignore_invalid_cert
                                                            (ESourceWebdav *extension);

### Warning

`e_source_webdav_get_ignore_invalid_cert` has been deprecated since version 3.8 and should not be used in newly-written code. The trust prompt APIs replace this.

Returns `TRUE` if invalid SSL certificates should be ignored.

This option allows SSL certificates to be accepted even if they have signed by an unrecognized Certificate Authority.

`extension` : | an ESourceWebdav
Returns : | whether invalid SSL certificates should be ignored

Since 3.6

### e_source_webdav_set_ignore_invalid_cert ()

    void                e_source_webdav_set_ignore_invalid_cert
                                                            (ESourceWebdav *extension,
                                                             gboolean ignore_invalid_cert);

### Warning

`e_source_webdav_set_ignore_invalid_cert` has been deprecated since version 3.8 and should not be used in newly-written code. The trust prompt APIs replace this.

Sets whether invalid SSL certificates should be ignored.

This option allows SSL certificates to be accepted even if they have signed by an unrecognized Certificate Authority.

`extension` : | an ESourceWebdav
`ignore_invalid_cert` : | whether invalid SSL certificates should be ignored

Since 3.6

## Property Details

### The `"avoid-ifmatch"` property

      "avoid-ifmatch"            gboolean              : Read / Write / Construct

Work around a bug in old Apache servers.

Default value: FALSE

### The `"calendar-auto-schedule"` property

      "calendar-auto-schedule"   gboolean              : Read / Write / Construct

Whether the server handles meeting invitations (CalDAV-only).

Default value: FALSE

### The `"display-name"` property

      "display-name"             gchar*                : Read / Write / Construct

Display name of the WebDAV resource.

Default value: ""

### The `"email-address"` property

      "email-address"            gchar*                : Read / Write / Construct

The user's email address.

Default value: ""

### The `"ignore-invalid-cert"` property

      "ignore-invalid-cert"      gboolean              : Read / Write / Construct

Ignore invalid SSL certificates.

Default value: FALSE

### The `"resource-path"` property

      "resource-path"            gchar*                : Read / Write / Construct

Absolute path to a WebDAV resource.

Default value: NULL

### The `"resource-query"` property

      "resource-query"           gchar*                : Read / Write / Construct

Query to access a WebDAV resource.

Default value: NULL

### The `"soup-uri"` property

      "soup-uri"                 SoupURI*              : Read / Write

WebDAV service as a SoupURI.

### The `"ssl-trust"` property

      "ssl-trust"                gchar*                : Read / Write / Construct

SSL certificate trust setting, for invalid server certificates.

Default value: NULL