Timeline events

Tracks the next or current timeline event for services that react to it. More...

Data Structures
struct	TimelineEventImpl
	Callbacks of a timeline event service. More...

Macros
#define	TIMELINE_EVENT_DELTA_INFINITE   (INT32_MAX)
	Delta meaning "unbounded" for timeline_event_starts_within().

Typedefs
typedef void(*	TimelineEventWillUpdateCallback) (void **context)
	Called before filtering and updating begins.
typedef bool(*	TimelineEventFilterCallback) (SerializedTimelineItemHeader *header, void **context)
	Called for every pin header to filter.
typedef void(*	TimelineEventDidUpdateCallback) (void **context)
	Called after filtering and updating, to tear down state set up by other callbacks.
typedef int(*	TimelineEventComparator) (SerializedTimelineItemHeader *new_header, SerializedTimelineItemHeader *old_header, void **context)
	Pick between two pins that passed filtering.
typedef uint32_t(*	TimelineEventUpdateCallback) (TimelineItem *item, void **context)
	Called with the selected pin, or NULL if no pin passed filtering.
typedef const TimelineEventImpl *(*	TimelineEventImplGetter) (void)
	Get the callbacks of a timeline event service.

Enumerations
enum	TimelineEventService { TimelineEventService_Calendar , TimelineEventService_Peek , TimelineEventServiceCount }
	Services using the timeline event service. More...

Functions
void	timeline_event_init (void)
	Initialize the timeline event service and all registered services.
void	timeline_event_deinit (void)
	Stop the timeline event service.
void	timeline_event_handle_blobdb_event (void)
	Resynchronize after a pin was added, deleted or changed.
void	timeline_event_refresh (void)
	Refresh the timeline event services.
bool	timeline_event_is_all_day (CommonTimelineItemHeader *common)
	Check whether an event is all day.
bool	timeline_event_is_ongoing (time_t now, time_t event_start, int event_duration_m)
	Check whether an event is ongoing.
bool	timeline_event_starts_within (CommonTimelineItemHeader *common, time_t now, int delta_start_s, int delta_end_s)
	Check whether a pin starts within a time range relative to now.

Detailed Description

Tracks the next or current timeline event for services that react to it.

Each registered service (calendar, Timeline Peek) supplies a TimelineEventImpl. Whenever pins change, a timer expires or a refresh is requested, the event service runs on KernelBG: it calls every will_update callback, passes each pin header through every filter, keeps one item per service, calls every update callback with it (or NULL), then every did_update callback. The next run is scheduled at the earliest of the timeouts returned by the update callbacks and the start or end of the selected item.

---

Data Structure Documentation

TimelineEventImpl

struct TimelineEventImpl

Callbacks of a timeline event service.

Data Fields
TimelineEventComparator	comparator	Comparator, may be NULL to always keep the earliest pin.
TimelineEventDidUpdateCallback	did_update	Called after updating, may be NULL.
TimelineEventFilterCallback	filter	Filter.
TimelineEventUpdateCallback	update	Update.
TimelineEventWillUpdateCallback	will_update	Called before filtering, may be NULL.

Macro Definition Documentation

TIMELINE_EVENT_DELTA_INFINITE

#define TIMELINE_EVENT_DELTA_INFINITE   (INT32_MAX)

Delta meaning "unbounded" for timeline_event_starts_within().

Typedef Documentation

TimelineEventComparator

typedef int(* TimelineEventComparator) (SerializedTimelineItemHeader *new_header, SerializedTimelineItemHeader *old_header, void **context)

Pick between two pins that passed filtering.

Parameters

new_header	Header of the pin that newly passed filtering.
old_header	Header of the pin that passed filtering earlier.
context	Pointer to the user context.

Returns

Negative to replace old_header with new_header; otherwise the earlier of the two is kept.

TimelineEventDidUpdateCallback

typedef void(* TimelineEventDidUpdateCallback) (void **context)

Called after filtering and updating, to tear down state set up by other callbacks.

Parameters

context

Pointer to the user context.

TimelineEventFilterCallback

typedef bool(* TimelineEventFilterCallback) (SerializedTimelineItemHeader *header, void **context)

Called for every pin header to filter.

Of the headers accepted, only one, the earliest unless the comparator says otherwise, is passed to the update callback.

Parameters

header	Header of the pin under consideration.
context	Pointer to the user context; the same pointer is passed to the update callback.

Returns

true to consider the pin for the update.

TimelineEventImplGetter

typedef const TimelineEventImpl *(* TimelineEventImplGetter) (void)

Get the callbacks of a timeline event service.

Returns

Callbacks.

TimelineEventUpdateCallback

typedef uint32_t(* TimelineEventUpdateCallback) (TimelineItem *item, void **context)

Called with the selected pin, or NULL if no pin passed filtering.

Parameters

item	Next or current pin (header only), or NULL.
context	Pointer to the user context, as set during filtering.

Returns

Milliseconds until the service wants to filter again, or 0 for no special timeout.

TimelineEventWillUpdateCallback

typedef void(* TimelineEventWillUpdateCallback) (void **context)

Called before filtering and updating begins.

Parameters

context

Pointer to the user context, which may be set up here for filtering and updating.

Enumeration Type Documentation

TimelineEventService

enum TimelineEventService

Services using the timeline event service.

Enumerator
TimelineEventService_Calendar	Calendar, for smart Do Not Disturb.
TimelineEventService_Peek	Timeline Peek.
TimelineEventServiceCount	Number of services.

Function Documentation

timeline_event_deinit()

void timeline_event_deinit

(

void

)

Stop the timeline event service.

Note

Used for factory resetting.

timeline_event_handle_blobdb_event()

void timeline_event_handle_blobdb_event

(

void

)

Resynchronize after a pin was added, deleted or changed.

Keeps the services from acting on stale data.

timeline_event_init()

void timeline_event_init

(

void

)

Initialize the timeline event service and all registered services.

Runs asynchronously on KernelBG. Pins inserted before initialization are taken into account.

timeline_event_is_all_day()

bool timeline_event_is_all_day

(

CommonTimelineItemHeader *

common

)

Check whether an event is all day.

Parameters

common

Header of the event.

Returns

true if flagged all day or lasting 24 hours or more.

timeline_event_is_ongoing()

bool timeline_event_is_ongoing	(	time_t	now,
		time_t	event_start,
		int	event_duration_m
	)

Check whether an event is ongoing.

Parameters

now	Current time, in seconds since the epoch.
event_start	Start of the event, in seconds since the epoch.
event_duration_m	Duration of the event, in minutes.

Returns

true if the event has started and not ended.

timeline_event_refresh()

void timeline_event_refresh

(

void

)

Refresh the timeline event services.

timeline_event_starts_within()

bool timeline_event_starts_within	(	CommonTimelineItemHeader *	common,
		time_t	now,
		int	delta_start_s,
		int	delta_end_s
	)

Check whether a pin starts within a time range relative to now.

Note

Only the start is compared; the duration is not considered. Items other than pins never match.

Parameters

common	Header of the event.
now	Current time, in seconds since the epoch.
delta_start_s	Seconds added to now to get the start of the range (exclusive), or TIMELINE_EVENT_DELTA_INFINITE for any past event.
delta_end_s	Seconds added to now to get the end of the range (exclusive), or TIMELINE_EVENT_DELTA_INFINITE for any future event.

Returns

true if the pin starts within the range.