ECalDataModel: GNOME Calendar Reference Manual

## ECalDataModel ECalDataModel |

## Functions

void | (*EThreadJobFunc) ()
ECalDataModel * | e_cal_data_model_new ()
ECalDataModel * | e_cal_data_model_new_clone ()
GCancellable * | e_cal_data_model_submit_thread_job ()
gboolean | e_cal_data_model_get_disposing ()
void | e_cal_data_model_set_disposing ()
gboolean | e_cal_data_model_get_expand_recurrences ()
void | e_cal_data_model_set_expand_recurrences ()
icaltimezone * | e_cal_data_model_get_timezone ()
void | e_cal_data_model_set_timezone ()
void | e_cal_data_model_set_filter ()
gchar * | e_cal_data_model_dup_filter ()
void | e_cal_data_model_add_client ()
void | e_cal_data_model_remove_client ()
ECalClient * | e_cal_data_model_ref_client ()
GList * | e_cal_data_model_get_clients ()
GSList * | e_cal_data_model_get_components ()
gboolean | (*ECalDataModelForeachFunc) ()
gboolean | e_cal_data_model_foreach_component ()
void | e_cal_data_model_subscribe ()
void | e_cal_data_model_unsubscribe ()
gboolean | e_cal_data_model_get_subscriber_range ()
void | e_cal_data_model_freeze_views_update ()
void | e_cal_data_model_thaw_views_update ()
gboolean | e_cal_data_model_is_views_update_frozen ()

## Properties

gboolean | expand-recurrences | Read / Write
gpointer | timezone | Read / Write

## Signals

void | view-state-changed | Run Last

## Types and Values

enum | ECalDataModelViewState

## Object Hierarchy

        GObject
        ╰── ECalDataModel

## Description

## Functions

### EThreadJobFunc ()

    void
    (*EThreadJobFunc) (gpointer user_data,
                       GCancellable *cancellable,
                       GError **error);

### e_cal_data_model_new ()

    ECalDataModel *
    e_cal_data_model_new (ECalDataModelSubmitThreadJobFunc func);

Creates a new instance of ECalDataModel. The `func` is mandatory, because it is used to create new thread jobs with UI feedback.

#### Parameters

func | a function to be called when the data model needs to create a thread job within UI |

#### Returns

A new ECalDataModel instance.

[transfer full]

Since: 3.14

### e_cal_data_model_new_clone ()

    ECalDataModel *
    e_cal_data_model_new_clone (ECalDataModel *src_data_model);

Creates a clone of `src_data_model` , which means a copy with the same clients, filter and other properties set (not the subscribers).

#### Parameters

src_data_model | an ECalDataModel to clone |

#### Returns

A new ECalDataModel instance deriving settings from `src_data_model` .

[transfer full]

Since: 3.14

### e_cal_data_model_submit_thread_job ()

    GCancellable *
    e_cal_data_model_submit_thread_job (ECalDataModel *data_model,
                                        EThreadJobFunc func,
                                        gpointer user_data,
                                        GDestroyNotify free_user_data);

Runs the `func` in a dedicated thread. Any error is propagated to UI. The cancellable passed into the `func` is a CamelOperation, thus the caller can overwrite progress and description message on it.

#### Parameters

data_model | an ECalDataModel |
description | user-friendly description of the job, to be shown in UI |
alert_ident | in case of an error, this alert identificator is used for EAlert construction |
alert_arg_0 | in case of an error, use this string as the first argument to the EAlert construction; the second argument is the actual error message; can be NULL, in which case only the error message is passed to the EAlert construction. | [allow-none]
func | function to be run in a dedicated thread |
user_data | custom data passed into `func` ; can be NULL. | [allow-none]
free_user_data | function to be called on `user_data` , when the job is over; can be NULL. | [allow-none]

#### Returns

Newly created GCancellable on success. The caller is responsible to `g_object_unref()` it when done with it.

Note: The `free_user_data` , if set, is called in the main thread.

Note: This is a blocking call, it waits until the thread job is submitted.

[transfer full]

Since: 3.14

### e_cal_data_model_get_disposing ()

    gboolean
    e_cal_data_model_get_disposing (ECalDataModel *data_model);

Obtains whether the `data_model` is disposing and will be freed (soon).

#### Parameters

data_model | an EDataModel instance |

#### Returns

Whether the `data_model` is disposing.

Since: 3.14

### e_cal_data_model_set_disposing ()

    void
    e_cal_data_model_set_disposing (ECalDataModel *data_model,
                                    gboolean disposing);

Sets whether the `data_model` is disposing itself (soon). If set to `TRUE`, then no updates are done on changes which would otherwise trigger view and subscriber updates.

#### Parameters

data_model | an EDataModel instance |
disposing | whether the object is disposing |

Since: 3.14

### e_cal_data_model_get_expand_recurrences ()

    gboolean
    e_cal_data_model_get_expand_recurrences
                                   (ECalDataModel *data_model);

Obtains whether the `data_model` expands recurrences of recurring components by default. The default value is FALSE, to not expand recurrences.

#### Parameters

data_model | an EDataModel instance |

#### Returns

Whether the `data_model` expands recurrences of recurring components.

Since: 3.14

### e_cal_data_model_set_expand_recurrences ()

    void
    e_cal_data_model_set_expand_recurrences
                                   (ECalDataModel *data_model,
                                    gboolean expand_recurrences);

Sets whether the `data_model` should expand recurrences of recurring components by default.

#### Parameters

data_model | an EDataModel instance |
expand_recurrences | whether to expand recurrences |

Since: 3.14

### e_cal_data_model_get_timezone ()

    icaltimezone *
    e_cal_data_model_get_timezone (ECalDataModel *data_model);

Obtains a timezone being used for calendar views. The returned timezone is owned by the `data_model` .

#### Parameters

data_model | an EDataModel instance |

#### Returns

An icaltimezone being used for calendar views.

[transfer none]

Since: 3.14

### e_cal_data_model_set_timezone ()

    void
    e_cal_data_model_set_timezone (ECalDataModel *data_model,
                                   icaltimezone *zone);

Sets a trimezone to be used for calendar views. This change regenerates all views.

#### Parameters

data_model | an EDataModel instance |
zone | an icaltimezone |

Since: 3.14

### e_cal_data_model_set_filter ()

    void
    e_cal_data_model_set_filter (ECalDataModel *data_model,
                                 const gchar *sexp);

Sets an additional filter for the views. The filter should not contain time constraints, these are meant to be defined by subscribers.

#### Parameters

data_model | an EDataModel instance |
sexp | an expression defining a filter |

Since: 3.14

### e_cal_data_model_dup_filter ()

    gchar *
    e_cal_data_model_dup_filter (ECalDataModel *data_model);

Obtains currently used filter (an expression) for the views.

#### Parameters

data_model | an EDataModel instance |

#### Returns

A copy of the currently used filter for views. Free it with `g_free()` when done with it. Returns NULL when there is no extra filter set.

[transfer full]

Since: 3.14

### e_cal_data_model_add_client ()

    void
    e_cal_data_model_add_client (ECalDataModel *data_model,
                                 ECalClient *client);

Adds a new `client` into the set of clients which should be used to populate data for subscribers. Adding the same client multiple times does nothing.

#### Parameters

data_model | an EDataModel instance |
client | an ECalClient |

Since: 3.14

### e_cal_data_model_remove_client ()

    void
    e_cal_data_model_remove_client (ECalDataModel *data_model,
                                    const gchar *uid);

Removes a client identified by `uid` from a set of clients which populate the data for subscribers. Removing the client which is not used in the `data_model` does nothing.

#### Parameters

uid | a UID of a client to remove |

Since: 3.14

### e_cal_data_model_ref_client ()

    ECalClient *
    e_cal_data_model_ref_client (ECalDataModel *data_model,
                                 const gchar *uid);

Obtains an ECalClient with given `uid` from the set of clients being used by the `data_modal` . Returns NULL, if no such client is used by the `data_model` .

#### Parameters

data_model | an EDataModel instance |
uid | a UID of a client to return |

#### Returns

An ECalClient with given `uid` being used by `data_model` , or NULL, when no such is used by the `data_model` . Unref returned (non-NULL) client with `g_object_unref()` when done with it.

[tranfer full]

Since: 3.14

### e_cal_data_model_get_clients ()

    GList *
    e_cal_data_model_get_clients (ECalDataModel *data_model);

Obtains a list of all clients being used by the `data_model` . Each client in the returned list is referenced and the list itself is also newly allocated, thus free it with g_list_free_full (list, g_object_unref); when done with it.

#### Parameters

data_model | an EDataModel instance |

#### Returns

A list of currently used ECalClient-s.

[transfer full]

Since: 3.14

### e_cal_data_model_get_components ()

    GSList *
    e_cal_data_model_get_components (ECalDataModel *data_model,
                                     time_t in_range_start,
                                     time_t in_range_end);

Obtains a list of components from the given time range. The time range is clamp by the actual time range defined by subscribers (if there is no subscriber, or all subscribers define times out of the given time range, then no components are returned).

#### Parameters

data_model | an EDataModel instance |
in_range_start | Start of the time range |
in_range_end | End of the time range |

#### Returns

A GSList of ECalComponent-s known for the given time range in the time of the call. The GSList, togher with the components, is owned by the caller, which should free it with g_slist_free_full (list, g_object_unref); when done with it.

Note: A special case when both `in_range_start` and `in_range_end` are zero is treated as a request for all known components.

[transfer full]

Since: 3.14

### ECalDataModelForeachFunc ()

    gboolean
    (*ECalDataModelForeachFunc) (ECalDataModel *data_model,
                                 ECalClient *client,
                                 const ECalComponentId *id,
                                 ECalComponent *comp,
                                 time_t instance_start,
                                 time_t instance_end,
                                 gpointer user_data);

### e_cal_data_model_foreach_component ()

    gboolean
    e_cal_data_model_foreach_component (ECalDataModel *data_model,
                                        time_t in_range_start,
                                        time_t in_range_end,
                                        ECalDataModelForeachFunc func,
                                        gpointer user_data);

Calls `func` for each component in the given time range. The time range is clamp by the actual time range defined by subscribers (if there is no subscriber, or all subscribers define times out of the given time range, then the function is not called at all and a FALSE is returned).

The `func` returns TRUE to continue the traversal. If it wants to stop the traversal earlier, then it returns FALSE.

#### Parameters

data_model | an EDataModel instance |
in_range_start | Start of the time range |
in_range_end | End of the time range |
func | a function to be called for each component in the given time range |
user_data | user data being passed into the `func` |

#### Returns

Whether all the components were checked. The returned value is usually TRUE, unless the `func` stops traversal earlier.

Note: A special case when both `in_range_start` and `in_range_end` are zero is treated as a request for all known components.

Since: 3.14

### e_cal_data_model_subscribe ()

    void
    e_cal_data_model_subscribe (ECalDataModel *data_model,
                                ECalDataModelSubscriber *subscriber,
                                time_t range_start,
                                time_t range_end);

Either adds a new `subscriber` to the set of subscribers for this `data_model` , or changes a time range used by the `subscriber` , in case it was added to the `data_model` earlier.

Reference count of the `subscriber` is increased by one, in case it is newly added. The reference count is decreased by one when `e_cal_data_model_unsubscribe()` is called.

Note: A special case when both `range_start` and `range_end` are zero is treated as a request with no time constraint. This limits the result only to those components which satisfy given filter.

#### Parameters

data_model | an EDataModel instance |
subscriber | an ECalDataModelSubscriber instance |
range_start | Start of the time range used by the `subscriber` |
range_end | End of the time range used by the `subscriber` |

Since: 3.14

### e_cal_data_model_unsubscribe ()

    void
    e_cal_data_model_unsubscribe (ECalDataModel *data_model,
                                  ECalDataModelSubscriber *subscriber);

Removes the `subscriber` from the set of subscribers for the `data_model` . Remove of the `subscriber` , which is not in the set of subscribers for the `data_model` does nothing.

Note: The `subscriber` is not notified about a removal of the components which could be added previously, while it was subscribed for the change notifications.

#### Parameters

data_model | an EDataModel instance |
subscriber | an ECalDataModelSubscriber instance |

Since: 3.14

### e_cal_data_model_get_subscriber_range ()

    gboolean
    e_cal_data_model_get_subscriber_range (ECalDataModel *data_model,
                                           ECalDataModelSubscriber *subscriber,
                                           time_t *range_start,
                                           time_t *range_end);

Obtains currently set time range for the `subscriber` . In case the subscriber is not found returns FALSE and both `range_start` and `range_end` are left untouched.

#### Parameters

data_model | an EDataModel instance |
subscriber | an ECalDataModelSubscriber instance |
range_start | time range start for the `subscriber` . | [out]
range_end | time range end for the `subscriber` . | [out]

#### Returns

Whether the `subscriber` was found and the `range_start` with the `range_end` were set to its current time range it uses.

Since: 3.14

### e_cal_data_model_freeze_views_update ()

    void
    e_cal_data_model_freeze_views_update (ECalDataModel *data_model);

Freezes any views updates until `e_cal_data_model_thaw_views_update()` is called. This can be called nested, then the same count of the calls of `e_cal_data_model_thaw_views_update()` is expected to unlock the views update.

#### Parameters

data_model | an EDataModel instance |

Since: 3.14

### e_cal_data_model_thaw_views_update ()

    void
    e_cal_data_model_thaw_views_update (ECalDataModel *data_model);

A pair function for `e_cal_data_model_freeze_views_update()`, to unlock views update.

#### Parameters

data_model | an EDataModel instance |

Since: 3.14

### e_cal_data_model_is_views_update_frozen ()

    gboolean
    e_cal_data_model_is_views_update_frozen
                                   (ECalDataModel *data_model);

Check whether any views updates are currently frozen. This is influenced by `e_cal_data_model_freeze_views_update()` and `e_cal_data_model_thaw_views_update()`.

#### Parameters

data_model | an EDataModel instance |

#### Returns

Whether any views updates are currently frozen.

Since: 3.14

## Types and Values

### enum ECalDataModelViewState

#### Members

E_CAL_DATA_MODEL_VIEW_STATE_START |  |
E_CAL_DATA_MODEL_VIEW_STATE_PROGRESS |  |
E_CAL_DATA_MODEL_VIEW_STATE_COMPLETE |  |
E_CAL_DATA_MODEL_VIEW_STATE_STOP |  |

## Property Details

### The `“expand-recurrences”` property

      “expand-recurrences”       gboolean

Flags: Read / Write

Default value: FALSE

### The `“timezone”` property

      “timezone”                 gpointer

Flags: Read / Write

## Signal Details

### The `“view-state-changed”` signal

    void
    user_function (ECalDataModel  *ecaldatamodel,
                   ECalClientView *arg1,
                   guint           arg2,
                   guint           arg3,
                   gchar          *arg4,
                   GError         *arg5,
                   gpointer        user_data)

Flags: Run Last