e-webdav-discover: Evolution-Data-Server Reference Manual

## e-webdav-discover e-webdav-discover |

## Functions

void | e_webdav_discover_free_discovered_sources ()
void | e_webdav_discover_sources ()
gboolean | e_webdav_discover_sources_finish ()
gboolean | e_webdav_discover_sources_sync ()
ESource * | (*EWebDAVDiscoverRefSourceFunc) ()
void | e_webdav_discover_sources_full ()
gboolean | e_webdav_discover_sources_full_sync ()

## Types and Values

enum | EWebDAVDiscoverSupports
| EWebDAVDiscoveredSource

## Description

## Functions

### e_webdav_discover_free_discovered_sources ()

    void
    e_webdav_discover_free_discovered_sources
                                   (GSList *discovered_sources);

Frees a `GSList` of discovered sources returned from `e_webdav_discover_sources_finish()` or `e_webdav_discover_sources_sync()`.

#### Parameters

discovered_sources | A GSList of discovered sources. | [element-type EWebDAVDiscoveredSource]

Since: 3.18

### e_webdav_discover_sources ()

    void
    e_webdav_discover_sources (ESource *source,
                               const gchar *url_use_path,
                               guint32 only_supports,
                               const ENamedParameters *credentials,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Asynchronously runs discovery of the WebDAV sources (CalDAV and CardDAV), eventually limited by the `only_supports` filter, which can be `E_WEBDAV_DISCOVER_SUPPORTS_NONE` to search all types. Note that the list of returned calendars can be more general, thus check for its actual support type for further filtering of the results. The `url_use_path` can be used to override actual server path, or even complete URL, for the given `source` .

When the operation is finished, `callback` will be called. You can then call `e_webdav_discover_sources_finish()` to get the result of the operation.

#### Parameters

source | an ESource from which to take connection details |
url_use_path | optional URL override, or `NULL`. | [allow-none]
only_supports | bit-or of EWebDAVDiscoverSupports, to limit what type of sources to search |
credentials | credentials to use for authentication to the server. | [allow-none]
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | data to pass to the callback function. | [closure]

Since: 3.18

### e_webdav_discover_sources_finish ()

    gboolean
    e_webdav_discover_sources_finish (ESource *source,
                                      GAsyncResult *result,
                                      gchar **out_certificate_pem,
                                      GTlsCertificateFlags *out_certificate_errors,
                                      GSList **out_discovered_sources,
                                      GSList **out_calendar_user_addresses,
                                      GError **error);

Finishes the operation started with `e_webdav_discover_sources()`. If an error occurred, the function will set `error` and return `FALSE`. The function can return success and no discovered sources, the same as it can return failure, but still set some output arguments, like the certificate related output arguments with SOUP_STATUS_SSL_FAILED error.

The return value of `out_certificate_pem` should be freed with `g_free()` when no longer needed.

The return value of `out_discovered_sources` should be freed with `e_webdav_discover_free_discovered_sources()` when no longer needed.

The return value of `out_calendar_user_addresses` should be freed with g_slist_free_full (calendar_user_addresses, g_free); when no longer needed.

#### Parameters

source | an ESource on which the operation was started |
result | a GAsyncResult |
out_certificate_pem | optional return location for a server SSL certificate in PEM format, when the operation failed with an SSL error. | [out][allow-none]
out_certificate_errors | optional GTlsCertificateFlags, with certificate error flags when the operation failed with SSL error. | [out][allow-none]
out_discovered_sources | a GSList of all discovered sources. | [out][element-type EWebDAVDiscoveredSource]
out_calendar_user_addresses | a GSList of all discovered mail addresses for calendar sources. | [out][allow-none][element-type utf8]
error | return location for a GError, or `NULL`. | [allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

Since: 3.18

### e_webdav_discover_sources_sync ()

    gboolean
    e_webdav_discover_sources_sync (ESource *source,
                                    const gchar *url_use_path,
                                    guint32 only_supports,
                                    const ENamedParameters *credentials,
                                    gchar **out_certificate_pem,
                                    GTlsCertificateFlags *out_certificate_errors,
                                    GSList **out_discovered_sources,
                                    GSList **out_calendar_user_addresses,
                                    GCancellable *cancellable,
                                    GError **error);

Synchronously runs discovery of the WebDAV sources (CalDAV and CardDAV), eventually limited by the `only_supports` filter, which can be `E_WEBDAV_DISCOVER_SUPPORTS_NONE` to search all types. Note that the list of returned calendars can be more general, thus check for its actual support type for further filtering of the results. The `url_use_path` can be used to override actual server path, or even complete URL, for the given `source` .

If an error occurred, the function will set `error` and return `FALSE`. The function can return success and no discovered sources, the same as it can return failure, but still set some output arguments, like the certificate related output arguments with SOUP_STATUS_SSL_FAILED error.

The return value of `out_certificate_pem` should be freed with `g_free()` when no longer needed.

The return value of `out_discovered_sources` should be freed with `e_webdav_discover_free_discovered_sources()` when no longer needed.

The return value of `out_calendar_user_addresses` should be freed with g_slist_free_full (calendar_user_addresses, g_free); when no longer needed.

#### Parameters

source | an ESource from which to take connection details |
url_use_path | optional URL override, or `NULL`. | [allow-none]
only_supports | bit-or of EWebDAVDiscoverSupports, to limit what type of sources to search |
credentials | credentials to use for authentication to the server. | [allow-none]
out_certificate_pem | optional return location for a server SSL certificate in PEM format, when the operation failed with an SSL error. | [out][allow-none]
out_certificate_errors | optional GTlsCertificateFlags, with certificate error flags when the operation failed with SSL error. | [out][allow-none]
out_discovered_sources | a GSList of all discovered sources. | [out][element-type EWebDAVDiscoveredSource]
out_calendar_user_addresses | a GSList of all discovered mail addresses for calendar sources. | [out][allow-none][element-type utf8]
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
error | return location for a GError, or `NULL`. | [allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

Since: 3.18

### EWebDAVDiscoverRefSourceFunc ()

    ESource *
    (*EWebDAVDiscoverRefSourceFunc) (gpointer user_data,
                                     const gchar *uid);

#### Parameters

user_data | user data, as passed to `e_webdav_discover_sources_full()` or `e_webdav_discover_sources_full_sync()` |
uid | an ESource UID to return |

#### Returns

an ESource with UID `uid` , or `NULL`, if not found. Dereference the returned non-NULL ESource with `g_object_unref()`, when no longer needed.

[transfer full][nullable]

Since: 3.30

### e_webdav_discover_sources_full ()

    void
    e_webdav_discover_sources_full (ESource *source,
                                    const gchar *url_use_path,
                                    guint32 only_supports,
                                    const ENamedParameters *credentials,
                                    EWebDAVDiscoverRefSourceFunc ref_source_func,
                                    gpointer ref_source_func_user_data,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

This is the same as `e_webdav_discover_sources()`, it only allows to provide a callback function (with its user_data), to reference an additional ESource. It's good to avoid creating its own ESourceRegistry instance to get it.

When the operation is finished, `callback` will be called. You can then call `e_webdav_discover_sources_finish()` to get the result of the operation.

#### Parameters

source | an ESource from which to take connection details |
url_use_path | optional URL override, or `NULL`. | [nullable]
only_supports | bit-or of EWebDAVDiscoverSupports, to limit what type of sources to search |
credentials | credentials to use for authentication to the server. | [nullable]
ref_source_func | optional callback to use to get an ESource. | [nullable][scope async]
ref_source_func_user_data | user data for `ref_source_func` . | [nullable]
cancellable | optional GCancellable object, or `NULL` |
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | data to pass to the callback function. | [closure]

Since: 3.30

### e_webdav_discover_sources_full_sync ()

    gboolean
    e_webdav_discover_sources_full_sync (ESource *source,
                                         const gchar *url_use_path,
                                         guint32 only_supports,
                                         const ENamedParameters *credentials,
                                         EWebDAVDiscoverRefSourceFunc ref_source_func,
                                         gpointer ref_source_func_user_data,
                                         gchar **out_certificate_pem,
                                         GTlsCertificateFlags *out_certificate_errors,
                                         GSList **out_discovered_sources,
                                         GSList **out_calendar_user_addresses,
                                         GCancellable *cancellable,
                                         GError **error);

This is the same as `e_webdav_discover_sources_sync()`, it only allows to provide a callback function (with its user_data), to reference an additional ESource. It's good to avoid creating its own ESourceRegistry instance to get it.

#### Parameters

source | an ESource from which to take connection details |
url_use_path | optional URL override, or `NULL`. | [nullable]
only_supports | bit-or of EWebDAVDiscoverSupports, to limit what type of sources to search |
credentials | credentials to use for authentication to the server. | [nullable]
ref_source_func | optional callback to use to get an ESource. | [nullable][scope call]
ref_source_func_user_data | user data for `ref_source_func` . | [nullable]
out_certificate_pem | optional return location for a server SSL certificate in PEM format, when the operation failed with an SSL error. | [out][nullable]
out_certificate_errors | optional GTlsCertificateFlags, with certificate error flags when the operation failed with SSL error. | [out][nullable]
out_discovered_sources | a GSList of all discovered sources. | [out][element-type EWebDAVDiscoveredSource]
out_calendar_user_addresses | a GSList of all discovered mail addresses for calendar sources. | [out][nullable][element-type utf8]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on failure

Since: 3.30

## Types and Values

### enum EWebDAVDiscoverSupports

#### Members

E_WEBDAV_DISCOVER_SUPPORTS_NONE |  |
E_WEBDAV_DISCOVER_SUPPORTS_CONTACTS |  |
E_WEBDAV_DISCOVER_SUPPORTS_EVENTS |  |
E_WEBDAV_DISCOVER_SUPPORTS_MEMOS |  |
E_WEBDAV_DISCOVER_SUPPORTS_TASKS |  |

### EWebDAVDiscoveredSource

    typedef struct {
    	gchar *href;
    	guint32 supports;
    	gchar *display_name;
    	gchar *description;
    	gchar *color;
    } EWebDAVDiscoveredSource;