Document and type allowed values for calendar property searches

For API users it looked like any properties could be searched. But it
turned out to be a hand picked list of properties that we index and then
use for the search. To prevent application errors where special props
are not found, I suggest we document and type the allowed values.

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>

1 files changed, 57 insertions, 0 deletions

diff --git a/lib/public/Calendar/ICalendarQuery.php b/lib/public/Calendar/ICalendarQuery.php
index 142810d3fb9..6a1fff619f6 100644
--- a/lib/public/Calendar/ICalendarQuery.php
+++ b/lib/public/Calendar/ICalendarQuery.php
@@ -23,6 +23,7 @@ declare(strict_types=1);
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  *
  */
+
 namespace OCP\Calendar;
 
 use DateTimeImmutable;
@@ -35,6 +36,56 @@ use DateTimeImmutable;
 interface ICalendarQuery {
 
 	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_CATEGORIES = 'CATEGORIES';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_COMMENT = 'COMMENT';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_DESCRIPTION = 'DESCRIPTION';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_LOCATION = 'LOCATION';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_RESOURCES = 'RESOURCES';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_STATUS = 'STATUS';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_SUMMARY = 'SUMMARY';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_ATTENDEE = 'ATTENDEE';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_CONTACT = 'CONTACT';
+
+	/**
+	 * @since 24.0.0
+	 */
+	public const SEARCH_PROPERTY_ORGANIZER = 'ORGANIZER';
+
+	/**
 	 * Limit the results to the calendar uri(s)
 	 *
 	 * @since 23.0.0
@@ -51,6 +102,12 @@ interface ICalendarQuery {
 	/**
 	 * Define the property name(s) to search for
 	 *
+	 * Note: Nextcloud only indexes *some* properties. You can not search for
+	 *       arbitrary properties.
+	 *
+	 * @param string $value any of the ICalendarQuery::SEARCH_PROPERTY_* values
+	 * @psalm-param ICalendarQuery::SEARCH_PROPERTY_* $value
+	 *
 	 * @since 23.0.0
 	 */
 	public function addSearchProperty(string $value): void;