ESourceWebdav

ESourceWebdav — ESource extension for WebDAV settings

Functions

Properties

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

Types and Values

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 SoupURI is parsed into components and distributed across several other built-in extensions such as ESourceAuthentication and ESourceSecurity.

Access the extension as follows:

  #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

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”

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.

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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().

Parameters

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

Parameters

extension

an ESourceWebdav

 

soup_uri

a SoupURI

 

Since 3.6


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

extension

an ESourceWebdav

 

Since 3.8


e_source_webdav_get_ignore_invalid_cert ()

gboolean
e_source_webdav_get_ignore_invalid_cert
                               (ESourceWebdav *extension);

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.

Parameters

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

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.

Parameters

extension

an ESourceWebdav

 

ignore_invalid_cert

whether invalid SSL certificates should be ignored

 

Since 3.6

Types and Values

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


enum ETrustPromptResponse

XXX Document me!

Members

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

Property Details

The “avoid-ifmatch” property

  “avoid-ifmatch”            gboolean

Work around a bug in old Apache servers.

Flags: Read / Write / Construct

Default value: FALSE


The “calendar-auto-schedule” property

  “calendar-auto-schedule”   gboolean

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

Flags: Read / Write / Construct

Default value: FALSE


The “display-name” property

  “display-name”             gchar *

Display name of the WebDAV resource.

Flags: Read / Write / Construct

Default value: ""


The “email-address” property

  “email-address”            gchar *

The user's email address.

Flags: Read / Write / Construct

Default value: ""


The “ignore-invalid-cert” property

  “ignore-invalid-cert”      gboolean

Ignore invalid SSL certificates.

Flags: Read / Write / Construct

Default value: FALSE


The “resource-path” property

  “resource-path”            gchar *

Absolute path to a WebDAV resource.

Flags: Read / Write / Construct

Default value: NULL


The “resource-query” property

  “resource-query”           gchar *

Query to access a WebDAV resource.

Flags: Read / Write / Construct

Default value: NULL


The “soup-uri” property

  “soup-uri”                 SoupURI *

WebDAV service as a SoupURI.

Flags: Read / Write


The “ssl-trust” property

  “ssl-trust”                gchar *

SSL certificate trust setting, for invalid server certificates.

Flags: Read / Write / Construct

Default value: NULL