1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
<?php
declare(strict_types=1);
/**
* SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
namespace OCP\Calendar;
use DateTimeInterface;
/**
* Interface ICalendar
*
* @since 13.0.0
*
* @psalm-type CalendarSearchOptions = array{
* timerange?: array{start?: DateTimeInterface, end?: DateTimeInterface},
* uid?: string,
* types?: string[],
* }
*/
interface ICalendar {
/**
* @return string defining the technical unique key
* @since 13.0.0
*/
public function getKey(): string;
/**
* In comparison to getKey() this function returns a unique uri within the scope of the principal
* @since 24.0.0
*/
public function getUri(): string;
/**
* In comparison to getKey() this function returns a human readable (maybe translated) name
* @return null|string
* @since 13.0.0
*/
public function getDisplayName(): ?string;
/**
* Calendar color
* @return null|string
* @since 13.0.0
*/
public function getDisplayColor(): ?string;
/**
* Search the current calendar for matching events.
*
* This method searches for events in the calendar that match a given pattern within specified properties.
* The search is case-insensitive. It supports optional parameters such as a time range, limit, and offset.
* The results are sorted by start date, with the closest events appearing first.
*
* @param string $pattern A string to search for within the events. The search is done case-insensitive.
* @param array $searchProperties Defines the properties within which the pattern should match.
* @param array $options Optional parameters for the search:
* - 'timerange' element that can have 'start' (DateTimeInterface), 'end' (DateTimeInterface), or both.
* - 'uid' element to look for events with a given uid.
* - 'types' element to only return events for a given type (e.g. VEVENT or VTODO)
* @psalm-param CalendarSearchOptions $options
* @param int|null $limit Limit the number of search results.
* @param int|null $offset For paging of search results.
* @return array An array of events/journals/todos which are arrays of key-value-pairs. The events are sorted by start date (closest first, furthest last).
*
* Implementation Details:
*
* An event can consist of many sub-events, typically the case for events with recurrence rules. On a database level,
* there's only one event stored (with a matching first occurrence and last occurrence timestamp). Expanding an event
* into sub-events is done on the backend level. Using limit, offset, and timerange comes with some drawbacks.
* When asking the database for events, the result is ordered by the primary key to guarantee a stable order.
* After expanding the events into sub-events, they are sorted by the date (closest to furthest).
*
* Usage Examples:
*
* 1) Find 7 events within the next two weeks:
*
* $dateTime = (new DateTimeImmutable())->setTimestamp($this->timeFactory->getTime());
* $inTwoWeeks = $dateTime->add(new DateInterval('P14D'));
*
* $calendar->search(
* '',
* [],
* ['timerange' => ['start' => $dateTime, 'end' => $inTwoWeeks]],
* 7
* );
*
* Note: When combining timerange and limit, it's possible that the expected outcome is not in the order you would expect.
*
* Example: Create 7 events for tomorrow, starting from 11:00, 30 minutes each. Then create an 8th event for tomorrow at 10:00.
* The above code will list the event at 11:00 first, missing the event at 10:00. The reason is the ordering by the primary key
* and expanding on the backend level. This is a technical limitation. The easiest workaround is to fetch more events
* than you actually need, with the downside of needing more resources.
*
* Related:
* - https://github.com/nextcloud/server/pull/45222
* - https://github.com/nextcloud/server/issues/53002
*
* 2) Find all events where the location property contains the string 'Berlin':
*
* $calendar->search(
* 'Berlin',
* ['LOCATION']
* );
*
* @since 13.0.0
*/
public function search(string $pattern, array $searchProperties = [], array $options = [], ?int $limit = null, ?int $offset = null): array;
/**
* @return int build up using {@see \OCP\Constants}
* @since 13.0.0
*/
public function getPermissions(): int;
/**
* Indicates whether the calendar is in the trash bin
*
* @since 26.0.0
*/
public function isDeleted(): bool;
}
|
