OptionalContextProvider-specific escape hatch, matching GetMessagesParams.ContextData.
OptionalEndEnd of the window. See GetEventsParams.StartDateTime.
OptionalIdentifierWhose calendar to read - typically an email address. Optional for providers whose credentials
are already scoped to one calendar, matching GetMessagesParams.Identifier.
OptionalIncludeWhether to include events the organizer cancelled. Default false: a cancellation is normally noise, but a system that logs history needs it, and it cannot be recovered after the fact.
Hard cap on events returned. A window can be far larger than a caller wants to process.
A CAP, NOT A GUARANTEE OF COMPLETENESS. Providers are expected to translate this to their own page-size parameter, so the result is bounded by ONE provider page and a value above the provider's own maximum may be ignored, silently capped, or rejected — the behaviour is the provider's, not this contract's. A caller that needs every event in a window must narrow the window rather than raise this number.
OptionalStartStart of the window.
THE WINDOW SELECTS OVERLAP, NOT START TIMES. An event that began before StartDateTime and is
still running when the window opens is IN the result. Verified against Microsoft Graph
/calendarView, which is the reference implementation: an event starting 45 minutes before a
window boundary was returned by the window that opened mid-event.
The consequence is for callers, so it is stated here rather than left to be discovered: an event that straddles a boundary appears in BOTH adjacent windows. Incremental sync must dedupe on the event id — advancing a watermark past the window end and assuming each event is seen once will double-file every meeting that crosses it.
SUPPLYING BOTH BOUNDS CHANGES WHAT YOU GET, and providers must say which they did via
RecurrenceExpanded. With a window, a provider that can expand recurrence returns one entry
per OCCURRENCE; without one it returns series masters, and a weekly stand-up is a single row
whose start time is months old. For logging what actually happened, occurrences are what you
want — so callers doing incremental sync should pass both.
Calendar retrieval.
SEPARATE FROM GetMessages RATHER THAN A MODE OF IT. A calendar read is bounded by a TIME WINDOW, not by a count and a folder: "the next 200 messages" is a sensible request and "the next 200 events" is not — what a caller wants is "everything between these two instants". Folding that into
GetMessagesParamswould have leftNumMessagesmeaning something different depending on a flag.