Merge [Readonly] Calendar API

[mattleibow]

Description of Change

Final tweaks for #1010 so we can merge it into the next version.

Calendars API for reading calendar/event information seamlessly across uwp, iOS and Android
(Issue #996)

API

API

public static class Calendars
{
    // Retrieve all calendars for device
    public static Task<IEnumerable<Calendar>> GetCalendarsAsync();

    // Retrieve the calendar for a specific ID
    public static Task<Calendar> GetCalendarAsync(string calendarId);

    // Retrieve all events for a specified range/calendar
    // Null values for parameters will result in default values being used: 
    //     calendarId will return events from all calendars
    //     startDate will default to the Now
    //     endDate will default to startDate+14 days
    public static Task<IEnumerable<CalendarEvent>> GetEventsAsync(string calendarId = null, DateTimeOffset? startDate = null, DateTimeOffset? endDate = null);

    // Gets more detailed information about a specific event by the event ID
    public static Task<CalendarEvent> GetEventAsync(string eventId);
}

Types

public class Calendar
{
    public Calendar();
    public Calendar(string id, string name);

    public string Id { get; set; }
    public string Name { get; set; }
}

public class CalendarEvent
{
    public CalendarEvent();
    public CalendarEvent(string id, string calendarId, string title);

    public string Id { get; set; }
    public string CalendarId { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public string Location { get; set; }
    public bool AllDay { get; set; }
    public DateTimeOffset StartDate { get; set; }
    public DateTimeOffset EndDate { get; set; }
    public TimeSpan Duration { get; } // if this is AllDay, then the Duration will be 1 day
    public IEnumerable<CalendarEventAttendee> Attendees { get; set; }
}

public class CalendarEventAttendee
{
    public CalendarEventAttendee();
    public CalendarEventAttendee(string name, string email);

    public string Name { get; set; }
    public 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
  • macOS: Support on iOS for the API
  • Android: Support on Android for the API
  • UWP: Support on UWP for the API
  • Tizen: Pending a PR from @rookiejava

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)

Contributors

@ScottBTR
@mkieres
@nickrandolph

[mattleibow]

Still in DRAFT to wait for Tizen implementation.

[Mrnikbobjeff]

Minor things I noticed

[Mrnikbobjeff]

ConfigureAwait(false) could be added here

[Mrnikbobjeff]

This is used only, a simple select could replace this method

[Mrnikbobjeff]

Also used once and could also be a select

[Mrnikbobjeff]

Same as above but this is more optional here as we do not delegate construction further down the line

[Mrnikbobjeff]

Could be a list as well, all platforms return lists.

[jfversluis]

@mattleibow seems like this is more something for .NET MAUI at this point? Should we close it here and make sure to get it on the list for .NET MAUI?

[jfversluis]

Alright closing this here. If anyone is still interested in this, please open an issue on the .NET MAUI repo, thanks!