ECalMetaBackend: Evolution-Data-Server Reference Manual

## ECalMetaBackend ECalMetaBackend — An ECalBackend descendant for calendar backends |

## Functions

ECalMetaBackendInfo * | e_cal_meta_backend_info_new ()
ECalMetaBackendInfo * | e_cal_meta_backend_info_copy ()
void | e_cal_meta_backend_info_free ()
const gchar * | e_cal_meta_backend_get_capabilities ()
void | e_cal_meta_backend_set_ever_connected ()
gboolean | e_cal_meta_backend_get_ever_connected ()
void | e_cal_meta_backend_set_connected_writable ()
gboolean | e_cal_meta_backend_get_connected_writable ()
gchar * | e_cal_meta_backend_dup_sync_tag ()
void | e_cal_meta_backend_set_cache ()
ECalCache * | e_cal_meta_backend_ref_cache ()
icalcomponent * | e_cal_meta_backend_merge_instances ()
gboolean | e_cal_meta_backend_inline_local_attachments_sync ()
gboolean | e_cal_meta_backend_store_inline_attachments_sync ()
gboolean | e_cal_meta_backend_gather_timezones_sync ()
gboolean | e_cal_meta_backend_empty_cache_sync ()
void | e_cal_meta_backend_schedule_refresh ()
gboolean | e_cal_meta_backend_refresh_sync ()
gboolean | e_cal_meta_backend_ensure_connected_sync ()
gboolean | e_cal_meta_backend_split_changes_sync ()
gboolean | e_cal_meta_backend_process_changes_sync ()
gboolean | e_cal_meta_backend_connect_sync ()
gboolean | e_cal_meta_backend_disconnect_sync ()
gboolean | e_cal_meta_backend_get_changes_sync ()
gboolean | e_cal_meta_backend_list_existing_sync ()
gboolean | e_cal_meta_backend_load_component_sync ()
gboolean | e_cal_meta_backend_save_component_sync ()
gboolean | e_cal_meta_backend_remove_component_sync ()
gboolean | e_cal_meta_backend_search_sync ()
gboolean | e_cal_meta_backend_search_components_sync ()
gboolean | e_cal_meta_backend_requires_reconnect ()
gboolean | e_cal_meta_backend_get_ssl_error_details ()

## Types and Values

struct | ECalMetaBackend
struct | ECalMetaBackendClass

## Includes

    #include <libedata-cal/libedata-cal.h>

## Description

The ECalMetaBackend is an abstract ECalBackend descendant which aims to implement all evolution-data-server internals for the backend itself and lefts the backend do as minimum work as possible, like loading and saving components, listing available components and so on, thus the backend implementation can focus on things like converting (possibly) remote data into iCalendar objects and back.

As the ECalMetaBackend uses an ECalCache, the offline support is provided by default.

The structure is thread safe.

## Functions

### e_cal_meta_backend_info_new ()

    ECalMetaBackendInfo *
    e_cal_meta_backend_info_new (const gchar *uid,
                                 const gchar *revision,
                                 const gchar *object,
                                 const gchar *extra);

Creates a new ECalMetaBackendInfo prefilled with the given values.

#### Parameters

uid | a component UID; cannot be `NULL` |
revision | the component revision; can be `NULL`. | [nullable]
object | the component object as an iCalendar string; can be `NULL`. | [nullable]
extra | extra backend-specific data; can be `NULL`. | [nullable]

#### Returns

A new ECalMetaBackendInfo. Free it with `e_cal_meta_backend_info_free()`, when no longer needed.

[transfer full]

Since: 3.26

### e_cal_meta_backend_info_copy ()

    ECalMetaBackendInfo *
    e_cal_meta_backend_info_copy (const ECalMetaBackendInfo *src);

#### Parameters

src | a source ECalMetaBackendInfo to copy, or `NULL`. | [nullable]

#### Returns

Copy of the given `src` . Free it with `e_cal_meta_backend_info_free()` when no longer needed. If the `src` is `NULL`, then returns `NULL` as well.

[transfer full]

Since: 3.26

### e_cal_meta_backend_info_free ()

    void
    e_cal_meta_backend_info_free (gpointer ptr);

Frees the `ptr` structure, previously allocated with `e_cal_meta_backend_info_new()` or `e_cal_meta_backend_info_copy()`.

#### Parameters

ptr | an ECalMetaBackendInfo. | [nullable]

Since: 3.26

### e_cal_meta_backend_get_capabilities ()

    const gchar *
    e_cal_meta_backend_get_capabilities (ECalMetaBackend *meta_backend);

#### Parameters

meta_backend | an ECalMetaBackend |

#### Returns

an “capabilities” property to be used by the descendant in conjunction to the descendant's capabilities in the result of `e_cal_backend_get_backend_property()` with CLIENT_BACKEND_PROPERTY_CAPABILITIES.

Since: 3.26

### e_cal_meta_backend_set_ever_connected ()

    void
    e_cal_meta_backend_set_ever_connected (ECalMetaBackend *meta_backend,
                                           gboolean value);

Sets whether the `meta_backend` ever made a successful connection to its destination.

This is used by the `meta_backend` itself, during the opening phase, when it had not been connected yet, then it does so immediately, to eventually report settings error easily.

#### Parameters

meta_backend | an ECalMetaBackend |
value | value to set |

Since: 3.26

### e_cal_meta_backend_get_ever_connected ()

    gboolean
    e_cal_meta_backend_get_ever_connected (ECalMetaBackend *meta_backend);

#### Parameters

meta_backend | an ECalMetaBackend |

#### Returns

Whether the `meta_backend` ever made a successful connection to its destination.

Since: 3.26

### e_cal_meta_backend_set_connected_writable ()

    void
    e_cal_meta_backend_set_connected_writable
                                   (ECalMetaBackend *meta_backend,
                                    gboolean value);

Sets whether the `meta_backend` connected to a writable destination. This value has meaning only if `e_cal_meta_backend_get_ever_connected()` is `TRUE`.

This is used by the `meta_backend` itself, during the opening phase, to set the backend writable or not also in the offline mode.

#### Parameters

meta_backend | an ECalMetaBackend |
value | value to set |

Since: 3.26

### e_cal_meta_backend_get_connected_writable ()

    gboolean
    e_cal_meta_backend_get_connected_writable
                                   (ECalMetaBackend *meta_backend);

This value has meaning only if `e_cal_meta_backend_get_ever_connected()` is `TRUE`.

#### Parameters

meta_backend | an ECalMetaBackend |

#### Returns

Whether the `meta_backend` connected to a writable destination.

Since: 3.26

### e_cal_meta_backend_dup_sync_tag ()

    gchar *
    e_cal_meta_backend_dup_sync_tag (ECalMetaBackend *meta_backend);

Returns the last known synchronization tag, the same as used to call `e_cal_meta_backend_get_changes_sync()`.

Free the returned string with `g_free()`, when no longer needed.

#### Parameters

meta_backend | an ECalMetaBackend |

#### Returns

The last known synchronization tag, or `NULL`, when none is stored.

[transfer full][nullable]

Since: 3.28

### e_cal_meta_backend_set_cache ()

    void
    e_cal_meta_backend_set_cache (ECalMetaBackend *meta_backend,
                                  ECalCache *cache);

Sets the `cache` as the cache to be used by the `meta_backend` . By default, a cache.db in ECalBackend::cache-dir is created in the constructed method. This function can be used to override the default.

Note the `meta_backend` adds its own reference to the `cache` .

#### Parameters

meta_backend | an ECalMetaBackend |
cache | an ECalCache to use |

Since: 3.26

### e_cal_meta_backend_ref_cache ()

    ECalCache *
    e_cal_meta_backend_ref_cache (ECalMetaBackend *meta_backend);

#### Parameters

meta_backend | an ECalMetaBackend |

#### Returns

Referenced ECalCache, which is used by `meta_backend` . Unref it with `g_object_unref()` when no longer needed.

[transfer full]

Since: 3.26

### e_cal_meta_backend_merge_instances ()

    icalcomponent *
    e_cal_meta_backend_merge_instances (ECalMetaBackend *meta_backend,
                                        const GSList *instances,
                                        gboolean replace_tzid_with_location);

Merges all the instances provided in `instances` list into one VCALENDAR object, which would eventually contain also all the used timezones. The `instances` list should contain the master object and eventually all the detached instances for one component (they all have the same UID).

Any TZID property parameters can be replaced with corresponding timezone location, which will not influence the timezone itself.

#### Parameters

meta_backend | an ECalMetaBackend |
instances | component instances to merge. | [element-type ECalComponent]
replace_tzid_with_location | whether to replace TZID-s with locations |

#### Returns

an icalcomponent containing a VCALENDAR component which consists of all the given instances. Free the returned pointer with `icalcomponent_free()` when no longer needed.

See: `e_cal_meta_backend_save_component_sync()`.

[transfer full]

Since: 3.26

### e_cal_meta_backend_inline_local_attachments_sync ()

    gboolean
    e_cal_meta_backend_inline_local_attachments_sync
                                   (ECalMetaBackend *meta_backend,
                                    icalcomponent *component,
                                    GCancellable *cancellable,
                                    GError **error);

Changes all URL attachments which point to a local file in `component` to inline attachments, aka adds the file content into the `component` . It also populates FILENAME parameter on the attachment. This is called automatically before `e_cal_meta_backend_save_component_sync()`.

The reverse operation is `e_cal_meta_backend_store_inline_attachments_sync()`.

#### Parameters

meta_backend | an ECalMetaBackend |
component | an icalcomponent to work with |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_store_inline_attachments_sync ()

    gboolean
    e_cal_meta_backend_store_inline_attachments_sync
                                   (ECalMetaBackend *meta_backend,
                                    icalcomponent *component,
                                    GCancellable *cancellable,
                                    GError **error);

Changes all inline attachments to URL attachments in `component` , which will point to a local file instead. The function expects FILENAME parameter to be set on the attachment as the file name of it. This is called automatically after `e_cal_meta_backend_load_component_sync()`.

The reverse operation is `e_cal_meta_backend_inline_local_attachments_sync()`.

#### Parameters

meta_backend | an ECalMetaBackend |
component | an icalcomponent to work with |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_gather_timezones_sync ()

    gboolean
    e_cal_meta_backend_gather_timezones_sync
                                   (ECalMetaBackend *meta_backend,
                                    icalcomponent *vcalendar,
                                    gboolean remove_existing,
                                    GCancellable *cancellable,
                                    GError **error);

Extracts all VTIMEZONE components from the `vcalendar` and adds them to the memory cache, thus they are available when needed. The function does nothing when the `vcalendar` doesn't hold a VCALENDAR component.

Set the `remove_existing` argument to `TRUE` to remove all cached timezones first and then add the existing in the `vcalendar` , or set it to `FALSE` to preserver existing timezones and merge them with those in `vcalendar` .

#### Parameters

meta_backend | an ECalMetaBackend |
vcalendar | a VCALENDAR icalcomponent |
remove_existing | whether to remove any existing first |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_empty_cache_sync ()

    gboolean
    e_cal_meta_backend_empty_cache_sync (ECalMetaBackend *meta_backend,
                                         GCancellable *cancellable,
                                         GError **error);

Empties the local cache by removing all known components from it and notifies about such removal any opened views. It removes also all known time zones.

#### Parameters

meta_backend | an ECalMetaBackend |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_schedule_refresh ()

    void
    e_cal_meta_backend_schedule_refresh (ECalMetaBackend *meta_backend);

Schedules refresh of the content of the `meta_backend` . If there's any already scheduled, then the function does nothing.

Use `e_cal_meta_backend_refresh_sync()` to refresh the `meta_backend` immediately.

#### Parameters

meta_backend | an ECalMetaBackend |

Since: 3.26

### e_cal_meta_backend_refresh_sync ()

    gboolean
    e_cal_meta_backend_refresh_sync (ECalMetaBackend *meta_backend,
                                     GCancellable *cancellable,
                                     GError **error);

Refreshes the `meta_backend` immediately. To just schedule refresh operation call `e_cal_meta_backend_schedule_refresh()`.

#### Parameters

meta_backend | an ECalMetaBackend |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_ensure_connected_sync ()

    gboolean
    e_cal_meta_backend_ensure_connected_sync
                                   (ECalMetaBackend *meta_backend,
                                    GCancellable *cancellable,
                                    GError **error);

Ensures that the `meta_backend` is connected to its destination.

#### Parameters

meta_backend | an ECalMetaBackend |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_split_changes_sync ()

    gboolean
    e_cal_meta_backend_split_changes_sync (ECalMetaBackend *meta_backend,
                                           GSList *objects,
                                           GSList **out_created_objects,
                                           GSList **out_modified_objects,
                                           GSList **out_removed_objects,
                                           GCancellable *cancellable,
                                           GError **error);

Splits `objects` into created/modified/removed lists according to current local cache content. Only the `out_removed_objects` can be `NULL`, others cannot. The function modifies `objects` by moving its 'data' to corresponding out lists and sets the `objects` 'data' to `NULL`.

Each output GSList should be freed with g_slist_free_full (objects, e_cal_meta_backend_info_free); when no longer needed.

The caller is still responsible to free `objects` as well.

#### Parameters

meta_backend | an ECalMetaBackend |
objects | a GSList of ECalMetaBackendInfo object infos to split. | [inout caller-allocates][element-type ECalMetaBackendInfo]
out_created_objects | a GSList of ECalMetaBackendInfo object infos which had been created. | [out][element-type ECalMetaBackendInfo][transfer full]
out_modified_objects | a GSList of ECalMetaBackendInfo object infos which had been modified. | [out][element-type ECalMetaBackendInfo][transfer full]
out_removed_objects | a GSList of ECalMetaBackendInfo object infos which had been removed; it can be `NULL`, to not gather list of removed object infos. | [out][element-type ECalMetaBackendInfo][transfer full][nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_process_changes_sync ()

    gboolean
    e_cal_meta_backend_process_changes_sync
                                   (ECalMetaBackend *meta_backend,
                                    const GSList *created_objects,
                                    const GSList *modified_objects,
                                    const GSList *removed_objects,
                                    GCancellable *cancellable,
                                    GError **error);

Processes given changes by updating local cache content accordingly. The `meta_backend` processes the changes like being online and particularly requires to be online to load created and modified objects when needed.

#### Parameters

meta_backend | an ECalMetaBackend |
created_objects | a GSList of ECalMetaBackendInfo object infos which had been created. | [element-type ECalMetaBackendInfo][nullable]
modified_objects | a GSList of ECalMetaBackendInfo object infos which had been modified. | [element-type ECalMetaBackendInfo][nullable]
removed_objects | a GSList of ECalMetaBackendInfo object infos which had been removed. | [element-type ECalMetaBackendInfo][nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_connect_sync ()

    gboolean
    e_cal_meta_backend_connect_sync (ECalMetaBackend *meta_backend,
                                     const ENamedParameters *credentials,
                                     ESourceAuthenticationResult *out_auth_result,
                                     gchar **out_certificate_pem,
                                     GTlsCertificateFlags *out_certificate_errors,
                                     GCancellable *cancellable,
                                     GError **error);

This is called always before any operation which requires a connection to the remote side. It can fail with an E_CLIENT_ERROR_REPOSITORY_OFFLINE error to indicate that the remote side cannot be currently reached. Other errors are propagated to the caller/client side. This method is not called when the backend is offline.

The descendant should also call `e_cal_backend_set_writable()` after successful connect to the remote side. This value is stored for later use, when being opened offline.

The `credentials` parameter consists of the previously used credentials. It's always `NULL` with the first connection attempt. To get the credentials, just set the `out_auth_result` to `E_SOURCE_AUTHENTICATION_REQUIRED` for the first time and the function will be called again once the credentials are available. See the documentation of ESourceAuthenticationResult for other available results.

The out parameters are passed to `e_backend_schedule_credentials_required()` and are ignored when the descendant returns `TRUE`, aka they are used only if the connection fails. The `out_certificate_pem` and `out_certificate_errors` should be used together and they can be left untouched if the failure reason was not related to certificate. Use `out_auth_result` `E_SOURCE_AUTHENTICATION_UNKNOWN` to indicate other error than `credentials` error, otherwise the `error` is used according to `out_auth_result` value.

It is mandatory to implement this virtual method by the descendant.

#### Parameters

meta_backend | an ECalMetaBackend |
credentials | an ENamedParameters with previously used credentials, or `NULL`. | [nullable]
out_auth_result | an ESourceAuthenticationResult with an authentication result. | [out]
out_certificate_pem | a PEM encoded certificate on failure, or `NULL`. | [out][transfer full]
out_certificate_errors | a GTlsCertificateFlags on failure, or 0. | [out]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_disconnect_sync ()

    gboolean
    e_cal_meta_backend_disconnect_sync (ECalMetaBackend *meta_backend,
                                        GCancellable *cancellable,
                                        GError **error);

This is called when the backend goes into offline mode or when the disconnect is required. The implementation should not report any error when it is called and the `meta_backend` is not connected.

It is mandatory to implement this virtual method by the descendant.

#### Parameters

meta_backend | an ECalMetaBackend |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_get_changes_sync ()

    gboolean
    e_cal_meta_backend_get_changes_sync (ECalMetaBackend *meta_backend,
                                         const gchar *last_sync_tag,
                                         gboolean is_repeat,
                                         gchar **out_new_sync_tag,
                                         gboolean *out_repeat,
                                         GSList **out_created_objects,
                                         GSList **out_modified_objects,
                                         GSList **out_removed_objects,
                                         GCancellable *cancellable,
                                         GError **error);

Gathers the changes since the last check which had been done on the remote side.

The `last_sync_tag` can be used as a tag of the last check. This can be `NULL`, when there was no previous call or when the descendant doesn't store any such tags. The `out_new_sync_tag` can be populated with a value to be stored and used the next time.

The `out_repeat` can be set to `TRUE` when the descendant didn't finish read of all the changes. In that case the `meta_backend` calls this function again with the `out_new_sync_tag` as the `last_sync_tag` , but also notifies about the found changes immediately. The `is_repeat` is set to `TRUE` as well in this case, otherwise it's `FALSE`.

The descendant can populate also ECalMetaBackendInfo::object of the `out_created_objects` and `out_modified_objects` , if known, in which case this will be used instead of loading it with `e_cal_meta_backend_load_component_sync()`.

It is optional to implement this virtual method by the descendant. The default implementation calls `e_cal_meta_backend_list_existing_sync()` and then compares the list with the current content of the local cache and populates the respective lists appropriately.

Each output GSList should be freed with g_slist_free_full (objects, e_cal_meta_backend_info_free); when no longer needed.

#### Parameters

meta_backend | an ECalMetaBackend |
last_sync_tag | optional sync tag from the last check. | [nullable]
is_repeat | set to `TRUE` when this is the repeated call |
out_new_sync_tag | new sync tag to store on success. | [out][transfer full]
out_repeat | whether to repeat this call again; default is `FALSE`. | [out]
out_created_objects | a GSList of ECalMetaBackendInfo object infos which had been created since the last check. | [out][element-type ECalMetaBackendInfo][transfer full]
out_modified_objects | a GSList of ECalMetaBackendInfo object infos which had been modified since the last check. | [out][element-type ECalMetaBackendInfo][transfer full]
out_removed_objects | a GSList of ECalMetaBackendInfo object infos which had been removed since the last check. | [out][element-type ECalMetaBackendInfo][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_list_existing_sync ()

    gboolean
    e_cal_meta_backend_list_existing_sync (ECalMetaBackend *meta_backend,
                                           gchar **out_new_sync_tag,
                                           GSList **out_existing_objects,
                                           GCancellable *cancellable,
                                           GError **error);

Used to get list of all existing objects on the remote side. The descendant can optionally provide `out_new_sync_tag` , which will be stored on success, if not `NULL`. The descendant can populate also ECalMetaBackendInfo::object of the `out_existing_objects` , if known, in which case this will be used instead of loading it with `e_cal_meta_backend_load_component_sync()`.

It is mandatory to implement this virtual method by the descendant, unless it implements its own `get_changes_sync()`.

The `out_existing_objects` GSList should be freed with g_slist_free_full (objects, e_cal_meta_backend_info_free); when no longer needed.

#### Parameters

meta_backend | an ECalMetaBackend |
out_new_sync_tag | optional return location for a new sync tag. | [out][transfer full]
out_existing_objects | a GSList of ECalMetaBackendInfo object infos which are stored on the remote side. | [out][element-type ECalMetaBackendInfo][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_load_component_sync ()

    gboolean
    e_cal_meta_backend_load_component_sync
                                   (ECalMetaBackend *meta_backend,
                                    const gchar *uid,
                                    const gchar *extra,
                                    icalcomponent **out_component,
                                    gchar **out_extra,
                                    GCancellable *cancellable,
                                    GError **error);

Loads a component from the remote side. Any detached instances should be returned together with the master object. The `out_component` can be either a VCALENDAR component, which would contain the master object and all of its detached instances, eventually also used time zones, or the requested component of type VEVENT, VJOURNAL or VTODO.

It is mandatory to implement this virtual method by the descendant.

The returned `out_component` should be freed with `icalcomponent_free()`, when no longer needed.

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

#### Parameters

meta_backend | an ECalMetaBackend |
uid | a component UID |
extra | optional extra data stored with the component, or `NULL`. | [nullable]
out_component | a loaded component, as icalcomponent. | [out][transfer full]
out_extra | an extra data to store to ECalCache with this component. | [out][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_save_component_sync ()

    gboolean
    e_cal_meta_backend_save_component_sync
                                   (ECalMetaBackend *meta_backend,
                                    gboolean overwrite_existing,
                                    EConflictResolution conflict_resolution,
                                    const GSList *instances,
                                    const gchar *extra,
                                    gchar **out_new_uid,
                                    gchar **out_new_extra,
                                    GCancellable *cancellable,
                                    GError **error);

Saves one component into the remote side. The `instances` contain the master object and all the detached instances of the same component (all have the same UID). When the `overwrite_existing` is `TRUE`, then the descendant can overwrite an object with the same UID on the remote side (usually used for modify). The `conflict_resolution` defines what to do when the remote side had made any changes to the object since the last update.

The descendant can use `e_cal_meta_backend_merge_instances()` to merge the instances into one VCALENDAR component, which will contain also used time zones.

The components in `instances` have already converted locally stored attachments into inline attachments, thus it's not needed to call `e_cal_meta_backend_inline_local_attachments_sync()` by the descendant.

The `out_new_uid` can be populated with a UID of the saved component as the server assigned it to it. This UID, if set, is loaded from the remote side afterwards, also to see whether any changes had been made to the component by the remote side.

The `out_new_extra` can be populated with a new extra data to save with the component. Left it `NULL`, to keep the same value as the `extra` .

The descendant can use an E_CLIENT_ERROR_OUT_OF_SYNC error to indicate that the save failed due to made changes on the remote side, and let the `meta_backend` to resolve this conflict based on the `conflict_resolution` on its own. The E_CLIENT_ERROR_OUT_OF_SYNC error should not be used when the descendant is able to resolve the conflicts itself.

It is mandatory to implement this virtual method by the writable descendant.

#### Parameters

meta_backend | an ECalMetaBackend |
overwrite_existing | `TRUE` when can overwrite existing components, `FALSE` otherwise |
conflict_resolution | one of EConflictResolution, what to do on conflicts |
instances | instances of the component to save. | [element-type ECalComponent]
extra | extra data saved with the components in an ECalCache. | [nullable]
out_new_uid | return location for the UID of the saved component. | [out][transfer full]
out_new_extra | return location for the extra data to store with the component. | [out][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_remove_component_sync ()

    gboolean
    e_cal_meta_backend_remove_component_sync
                                   (ECalMetaBackend *meta_backend,
                                    EConflictResolution conflict_resolution,
                                    const gchar *uid,
                                    const gchar *extra,
                                    const gchar *object,
                                    GCancellable *cancellable,
                                    GError **error);

Removes a component from the remote side, with all its detached instances. The `object` is not `NULL` when it's removing locally deleted object in offline mode. Being it `NULL`, the descendant can obtain the object from the ECalCache.

It is mandatory to implement this virtual method by the writable descendant.

#### Parameters

meta_backend | an ECalMetaBackend |
conflict_resolution | an EConflictResolution to use |
uid | a component UID |
extra | extra data being saved with the component in the local cache, or `NULL`. | [nullable]
object | corresponding iCalendar object, as stored in the local cache, or `NULL`. | [nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_search_sync ()

    gboolean
    e_cal_meta_backend_search_sync (ECalMetaBackend *meta_backend,
                                    const gchar *expr,
                                    GSList **out_icalstrings,
                                    GCancellable *cancellable,
                                    GError **error);

Searches `meta_backend` with given expression `expr` and returns found components as a GSList of iCal strings `out_icalstrings` . Free the returned `out_icalstrings` with g_slist_free_full (icalstrings, g_free); when no longer needed. When the `expr` is `NULL`, all objects are returned. To get ECalComponent-s instead, call `e_cal_meta_backend_search_components_sync()`.

It is optional to implement this virtual method by the descendant. The default implementation searches `meta_backend` 's cache. It's also not required to be online for searching, thus `meta_backend` doesn't ensure it.

#### Parameters

meta_backend | an ECalMetaBackend |
expr | a search expression, or `NULL`. | [nullable]
out_icalstrings | return location for the found components as iCal strings. | [out][transfer full][element-type utf8]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_search_components_sync ()

    gboolean
    e_cal_meta_backend_search_components_sync
                                   (ECalMetaBackend *meta_backend,
                                    const gchar *expr,
                                    GSList **out_components,
                                    GCancellable *cancellable,
                                    GError **error);

Searches `meta_backend` with given expression `expr` and returns found components as a GSList of ECalComponent `out_components` . Free the returned `out_components` with g_slist_free_full (components, g_object_unref); when no longer needed. When the `expr` is `NULL`, all objects are returned. To get iCal strings instead, call `e_cal_meta_backend_search_sync()`.

It is optional to implement this virtual method by the descendant. The default implementation searches `meta_backend` 's cache. It's also not required to be online for searching, thus `meta_backend` doesn't ensure it.

#### Parameters

meta_backend | an ECalMetaBackend |
expr | a search expression, or `NULL`. | [nullable]
out_components | return location for the found ECalComponent-s. | [out][transfer full][element-type ECalComponent]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_cal_meta_backend_requires_reconnect ()

    gboolean
    e_cal_meta_backend_requires_reconnect (ECalMetaBackend *meta_backend);

Determines, whether current source content requires reconnect of the backend.

It is optional to implement this virtual method by the descendant. The default implementation compares `E_SOURCE_EXTENSION_AUTHENTICATION` and `E_SOURCE_EXTENSION_WEBDAV_BACKEND`, if existing in the source, with the values after the last successful connect and returns `TRUE` when they changed. It always return `TRUE` when there was no successful connect done yet.

#### Parameters

meta_backend | an ECalMetaBackend |

#### Returns

`TRUE`, when reconnect is required, `FALSE` otherwise.

Since: 3.26

### e_cal_meta_backend_get_ssl_error_details ()

    gboolean
    e_cal_meta_backend_get_ssl_error_details
                                   (ECalMetaBackend *meta_backend,
                                    gchar **out_certificate_pem,
                                    GTlsCertificateFlags *out_certificate_errors);

It is optional to implement this virtual method by the descendants. It is used to receive SSL error details when any online operation returns E_DATA_CAL_ERROR, TLSNotAvailable error.

#### Parameters

meta_backend | an ECalMetaBackend |
out_certificate_pem | SSL certificate encoded in PEM format. | [out]
out_certificate_errors | bit-or of GTlsCertificateFlags claiming the certificate errors. | [out]

#### Returns

`TRUE`, when the SSL error details had been available and the out parameters populated, `FALSE` otherwise.

Since: 3.28

## Types and Values

### struct ECalMetaBackend

    struct ECalMetaBackend {
    };

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

Since: 3.26

### struct ECalMetaBackendClass

    struct ECalMetaBackendClass {
    };

Class structure for the ECalMetaBackend class.

Since: 3.26