[Spec] Calendar Read-Only API

[nickrandolph]

Calendar Read-Only API

Calendar API for reading calendar/event information seamlessly across uwp, iOS and Android

API

Calendar

Methods

API	Description
Task<IEnumerable<DeviceCalendar>> GetCalendarsAsync()	Retrieve all calendars for device
Task<IEnumerable<DeviceEvent>> GetEventsAsync( string calendarId = null, DateTimeOffset? startDate = null, DateTimeOffset? endDate = null)	Retrieve all events for a specified range/calendar, null will use defaults: calendarId will default to all Calendars retrieved, startDate will default to use, DefaultStartDate , endDate will default to use DefaultEndDate
Task<DeviceEvent> GetEventByIdAsync(string eventId)	Gets more detailed information about a specific event by the event id

Classes

public class DeviceCalendar
{
    string Id { get; set; }

    string Name { get; set; }
}

public class DeviceEvent
{
    string Id { get; set; }

    string CalendarId { get; set; }

    string Title { get; set; }

    string Description { get; set; }

    string Location { get; set; }

    bool AllDay { get; set; }

    DateTimeOffset? Start { get; set; }

    DateTimeOffset? End { get; set; }

    TimeSpan? Duration { get; set; }

    IReadOnlyList<DeviceEventAttendee> Attendees { get; set; }
}

public class DeviceEventAttendee
{
    string Name { get; set; }

    string Email { get; set; }
}

Scenarios

• User wants to see upcoming events.
• User wants to see who is attending an upcoming event.
• User wants to know when they will be free.

Platform Compatibility

• Target Frameworks:
  • iOS: Support on iOS for the API
  • Android: Support on Android for the API
  • UWP: Support on UWP for the API

Backward Compatibility

• UWP: Windows 10 (introduced v10.0.10240.0)
  (https://docs.microsoft.com/en-us/uwp/api/windows.applicationmodel.appointments.appointment)
• Android: android:minSdkVersion="14"
  (https://developer.android.com/reference/android/provider/CalendarContract)
• iOS: All versions until reminders are added, then iOS 6
  (https://developer.apple.com/documentation/eventkit/ekeventstore)

Difficulty : low

[jamesmontemagno]

I don't think IsAvailable is required as if you query the calendars and it returns none, then it wouldn't be supported or no calendars available.

We also do not have any interfaces, but those would be your classes :)

I would copy/paste the Windows classes here for the API and just cut an intersection:

• Appointement
• AppointementInvitee

[nickrandolph]

• IsAvailable has been removed
• Changed to use classes instead of interfaces. I assume that the use of IReadOnlyList is ok?

Windows class for Appointment/AppointmentInvitee included below - I've bolded the fields that map to the proposed classes. We've renamed a couple of the properties but can realign to Windows naming if that's the preference.

We prefer the use of Event / Attendee rather than Appointment/Invitee but we can realign to the Windows naming for the classes if that's preferrable

Main difference is that we've suggested Start + End instead of Start + Duration. Is there a preference from others as to how to specify the start and end times for an event?

public class Appointment 
{
	**public string Location**

	**public bool AllDay**

	public AppointmentOrganizer Organizer

	**public TimeSpan Duration**

	**public string Details**

	public AppointmentBusyStatus BusyStatus

	public AppointmentRecurrence Recurrence

	**public string Subject**

	public System.Uri Uri

	**public DateTimeOffset StartTime**

	public AppointmentSensitivity Sensitivity

	public TimeSpan? Reminder

	**public IList<AppointmentInvitee> Invitees**

	public bool AllowNewTimeProposal

	public AppointmentParticipantResponse UserResponse

	public string RoamingId

	public DateTimeOffset? ReplyTime

	public bool IsResponseRequested

	public bool IsOrganizedByUser

	public bool IsCanceledMeeting

	public string OnlineMeetingLink

	public bool HasInvitees

	**public string CalendarId**

	**public string LocalId**

	public DateTimeOffset? OriginalStartTime

	public ulong RemoteChangeNumber

	public AppointmentDetailsKind DetailsKind

	public ulong ChangeNumber
}

public class AppointmentInvitee 
{
	public AppointmentParticipantRole Role

	public AppointmentParticipantResponse Response

	**public string DisplayName**

	**public string Address**
}