ESourceWebdav: Evolution-Data-Server Reference Manual

## ESourceWebdav ESourceWebdav — ESource extension for WebDAV settings |

## Functions

gboolean | e_source_webdav_get_avoid_ifmatch ()
void | e_source_webdav_set_avoid_ifmatch ()
gboolean | e_source_webdav_get_calendar_auto_schedule ()
void | e_source_webdav_set_calendar_auto_schedule ()
const gchar * | e_source_webdav_get_display_name ()
gchar * | e_source_webdav_dup_display_name ()
void | e_source_webdav_set_display_name ()
const gchar * | e_source_webdav_get_color ()
gchar * | e_source_webdav_dup_color ()
void | e_source_webdav_set_color ()
const gchar * | e_source_webdav_get_email_address ()
gchar * | e_source_webdav_dup_email_address ()
void | e_source_webdav_set_email_address ()
const gchar * | e_source_webdav_get_resource_path ()
gchar * | e_source_webdav_dup_resource_path ()
void | e_source_webdav_set_resource_path ()
const gchar * | e_source_webdav_get_resource_query ()
gchar * | e_source_webdav_dup_resource_query ()
void | e_source_webdav_set_resource_query ()
const gchar * | e_source_webdav_get_ssl_trust ()
gchar * | e_source_webdav_dup_ssl_trust ()
void | e_source_webdav_set_ssl_trust ()
GUri * | e_source_webdav_dup_uri ()
void | e_source_webdav_set_uri ()
void | e_source_webdav_update_ssl_trust ()
ETrustPromptResponse | e_source_webdav_verify_ssl_trust ()
void | e_source_webdav_unset_temporary_ssl_trust ()
ETrustPromptResponse | e_source_webdav_get_ssl_trust_response ()
void | e_source_webdav_set_ssl_trust_response ()
guint | e_source_webdav_get_order ()
void | e_source_webdav_set_order ()

## Types and Values

#define | E_SOURCE_EXTENSION_WEBDAV_BACKEND
struct | ESourceWebdav

## Object Hierarchy

        GObject
        ╰── ESourceExtension
            ╰── ESourceWebdav

## Includes

    #include <libedataserver/libedataserver.h>

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

## Functions

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

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.

#### Parameters

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.

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.

#### Parameters

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!

#### Parameters

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!

#### Parameters

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.

#### Parameters

extension | an ESourceWebdav |

#### Returns

the display name of the WebDAV resource.

[nullable]

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.

#### Parameters

extension | an ESourceWebdav |

#### Returns

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

[nullable]

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.

#### Parameters

extension | an ESourceWebdav |
display_name | the display name of the WebDAV resource, or `NULL`. | [nullable]

Since: 3.6

### e_source_webdav_get_color ()

    const gchar *
    e_source_webdav_get_color (ESourceWebdav *extension);

Returns the last known color of a WebDAV resource as provided by the server.

#### Parameters

extension | an ESourceWebdav |

#### Returns

the color of the WebDAV resource, if any set on the server.

[nullable]

Since: 3.30

### e_source_webdav_dup_color ()

    gchar *
    e_source_webdav_dup_color (ESourceWebdav *extension);

Thread-safe variation of `e_source_webdav_get_color()`. 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 ESourceWebdav |

#### Returns

a newly-allocated copy of “color”.

[nullable]

Since: 3.30

### e_source_webdav_set_color ()

    void
    e_source_webdav_set_color (ESourceWebdav *extension,
                               const gchar *color);

Updates the last known color of a WebDAV resource, as provided by the server.

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

#### Parameters

extension | an ESourceWebdav |
color | the color of the WebDAV resource, or `NULL`. | [nullable]

Since: 3.30

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

#### Parameters

extension | an ESourceWebdav |

#### Returns

the user's email address.

[nullable]

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.

#### Parameters

extension | an ESourceWebdav |

#### Returns

the newly-allocated copy of “email-address”.

[nullable]

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.

#### Parameters

extension | an ESourceWebdav |
email_address | the user's email address, or `NULL`. | [nullable]

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.

#### Parameters

extension | an ESourceWebdav |

#### Returns

the absolute path to a WebDAV resource.

[nullable]

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.

#### Parameters

extension | an ESourceWebdav |

#### Returns

the newly-allocated copy of “resource-path”.

[nullable]

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.

#### Parameters

extension | an ESourceWebdav |
resource_path | the absolute path to a WebDAV resource, or `NULL`. | [nullable]

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.

#### Parameters

extension | an ESourceWebdav |

#### Returns

the query to access a WebDAV resource.

[nullable]

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.

#### Parameters

extension | an ESourceWebdav |

#### Returns

the newly-allocated copy of “resource-query”.

[nullable]

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.

#### Parameters

extension | an ESourceWebdav |
resource_query | the query to access a WebDAV resource, or `NULL`. | [nullable]

Since: 3.6

### e_source_webdav_get_ssl_trust ()

    const gchar *
    e_source_webdav_get_ssl_trust (ESourceWebdav *extension);

Returns an SSL/TLS 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 SHA256 hash of the certificate. This is not meant to be changed by a caller, it is supposed to be manipulated with `e_source_webdav_update_ssl_trust()` and `e_source_webdav_verify_ssl_trust()`.

#### Parameters

extension | an ESourceWebdav |

#### Returns

an SSL/TLS certificate trust for the `extension` .

[nullable]

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.

#### Parameters

extension | an ESourceWebdav |

#### Returns

the newly-allocated copy of “ssl-trust”.

[nullable]

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/TLS certificate trust. See `e_source_webdav_get_ssl_trust()` for more infomation about its content and how to use it.

#### Parameters

extension | an ESourceWebdav |
ssl_trust | the ssl_trust to store, or `NULL` to unset. | [nullable]

Since: 3.8

### e_source_webdav_dup_uri ()

    GUri *
    e_source_webdav_dup_uri (ESourceWebdav *extension);

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

#### Parameters

extension | an ESourceWebdav |

#### Returns

a newly-allocated GUri.

[transfer full]

Since: 3.46

### e_source_webdav_set_uri ()

    void
    e_source_webdav_set_uri (ESourceWebdav *extension,
                             GUri *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.)

#### Parameters

extension | an ESourceWebdav |
uri | a GUri |

Since: 3.46

### e_source_webdav_update_ssl_trust ()

    void
    e_source_webdav_update_ssl_trust (ESourceWebdav *extension,
                                      const gchar *host,
                                      GTlsCertificate *cert,
                                      ETrustPromptResponse response);

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

#### Parameters

extension | an ESourceWebdav |
host | a host name to store the certificate for |
cert | the invalid certificate of the connection over which `host` is about to be sent |
response | user's response from a trust prompt for `cert` |

Since: 3.16

### e_source_webdav_verify_ssl_trust ()

    ETrustPromptResponse
    e_source_webdav_verify_ssl_trust (ESourceWebdav *extension,
                                      const gchar *host,
                                      GTlsCertificate *cert,
                                      GTlsCertificateFlags cert_errors);

Verifies SSL/TLS trust for the given `host` and `cert` , as previously stored in the `extension` with `e_source_webdav_update_ssl_trust()`.

#### Parameters

extension | an ESourceWebdav |
host | a host name to store the certificate for |
cert | the invalid certificate of the connection over which `host` is about to be sent |
cert_errors | a bit-or of GTlsCertificateFlags describing the reason for the `cert` to be considered invalid |

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

#### Parameters

extension | an ESourceWebdav |

Since: 3.8

### e_source_webdav_get_ssl_trust_response ()

    ETrustPromptResponse
    e_source_webdav_get_ssl_trust_response
                                   (ESourceWebdav *extension);

#### Parameters

extension | an ESourceWebdav |

#### Returns

the last SSL trust response, as ETrustPromptResponse, if none is set, then returns `E_TRUST_PROMPT_RESPONSE_UNKNOWN`

Since: 3.32

### e_source_webdav_set_ssl_trust_response ()

    void
    e_source_webdav_set_ssl_trust_response
                                   (ESourceWebdav *extension,
                                    ETrustPromptResponse response);

Set the SSL trust response, as ETrustPromptResponse, while keeping the certificate and host information as before. The function does nothing, when none SSL trust is set or when `E_TRUST_PROMPT_RESPONSE_UNKNOWN` is used as the `response` .

#### Parameters

extension | an ESourceWebdav |
response | an ETrustPromptResponse to set |

Since: 3.32

### e_source_webdav_get_order ()

    guint
    e_source_webdav_get_order (ESourceWebdav *extension);

#### Parameters

extension | an ESourceWebdav |

#### Returns

the sorting order of the resource, if known. The default is (guint) -1, which means unknown/unset.

Since: 3.40

### e_source_webdav_set_order ()

    void
    e_source_webdav_set_order (ESourceWebdav *extension,
                               guint order);

Set the sorting order of the resource.

#### Parameters

extension | an ESourceWebdav |
order | a sorting order |

Since: 3.40

## Types and Values

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

### struct ESourceWebdav

    struct ESourceWebdav;

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

Since: 3.6