Table of Contents

Events

Once you know which calendar to work with, TTMSFNCCloudMicrosoftOutlookCalendar retrieves its events within a date range, resolves a single event by ID, and creates, updates and deletes events. This chapter covers retrieving events and the full event CRUD cycle.

Retrieving events

GetCalendar — despite its singular, calendar-sounding name, this method retrieves events, not calendar metadata — lists the events of a calendar (or the default calendar when no ID is given) within a date range, paged with APageSize and APageIndex, raising OnGetCalendar; read the result from Items. GetItemByID resolves a single event directly by its identifier, raising OnGetCalendarItem.

procedure TForm1.ListThisWeeksEvents(const ACalendarID: string);
begin
  TMSFNCCloudMicrosoftOutlookCalendar1.OnGetCalendar := OutlookCalendarEventsListed;
  // GetCalendar retrieves events, despite the singular calendar-sounding name.
  TMSFNCCloudMicrosoftOutlookCalendar1.GetCalendar(ACalendarID, Date, Date + 7);
end;

procedure TForm1.OutlookCalendarEventsListed(Sender: TObject;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
var
  i: Integer;
  ev: TTMSFNCCloudMicrosoftOutlookCalendarItem;
begin
  if not ARequestResult.Success then
    Exit;

  for i := 0 to TMSFNCCloudMicrosoftOutlookCalendar1.Items.Count - 1 do
  begin
    ev := TMSFNCCloudMicrosoftOutlookCalendar1.Items[i];
    Memo1.Lines.Add(ev.Summary + ' @ ' + DateTimeToStr(ev.StartTime));
  end;
end;

procedure TForm1.LookUpEventByID(const AEventID: string);
begin
  TMSFNCCloudMicrosoftOutlookCalendar1.OnGetCalendarItem := OutlookCalendarEventFound;
  TMSFNCCloudMicrosoftOutlookCalendar1.GetItemByID(AEventID);
end;

procedure TForm1.OutlookCalendarEventFound(Sender: TObject;
  const AItem: TTMSFNCCloudMicrosoftOutlookCalendarItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add(AItem.Summary + ' in ' + AItem.Location);
end;

Creating an event

Add a new item to Items, populate its fields (subject, times, location, attendees), and call Add with it — Add reads the CalendarID from the event itself to know which calendar to create it in. Completion is reported through OnAddCalendarItem.

procedure TForm1.ScheduleReviewMeeting(const ACalendarID: string);
var
  ev: TTMSFNCCloudMicrosoftOutlookCalendarItem;
begin
  // Add the event through Items so the collection owns it - do not free it
  // yourself, the component keeps a reference to it until Add completes.
  ev := TMSFNCCloudMicrosoftOutlookCalendar1.Items.Add;
  ev.CalendarID := ACalendarID;
  ev.Summary := 'Design review';
  ev.Location := 'Conference room A';
  ev.StartTime := Now + 1;
  ev.EndTime := Now + 1 + (1 / 24);
  ev.Attendees.Add.Email := 'reviewer@example.com';

  TMSFNCCloudMicrosoftOutlookCalendar1.OnAddCalendarItem := OutlookCalendarEventAdded;
  TMSFNCCloudMicrosoftOutlookCalendar1.Add(ev);
end;

procedure TForm1.OutlookCalendarEventAdded(Sender: TObject;
  const AItem: TTMSFNCCloudMicrosoftOutlookCalendarItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Created event ' + AItem.ID);
end;

Updating and deleting an event

UpdateItem saves changes made to an already-retrieved event back to the service, raising OnUpdateCalendarItem. Delete removes an event, either by the event object or by its identifier, raising OnDeleteCalendarItem.

procedure TForm1.PostponeEvent(AEvent: TTMSFNCCloudMicrosoftOutlookCalendarItem);
begin
  AEvent.StartTime := AEvent.StartTime + 1;
  AEvent.EndTime := AEvent.EndTime + 1;

  TMSFNCCloudMicrosoftOutlookCalendar1.OnUpdateCalendarItem := OutlookCalendarEventUpdated;
  TMSFNCCloudMicrosoftOutlookCalendar1.UpdateItem(AEvent);
end;

procedure TForm1.OutlookCalendarEventUpdated(Sender: TObject;
  const AItem: TTMSFNCCloudMicrosoftOutlookCalendarItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Event moved to ' + DateTimeToStr(AItem.StartTime));
end;

procedure TForm1.CancelEventByID(const AEventID: string);
begin
  TMSFNCCloudMicrosoftOutlookCalendar1.OnDeleteCalendarItem := OutlookCalendarEventDeleted;
  TMSFNCCloudMicrosoftOutlookCalendar1.Delete(AEventID);
end;

procedure TForm1.OutlookCalendarEventDeleted(Sender: TObject; const AID: string;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Deleted event ' + AID);
end;

Combining a lookup with an update

Resolving an event by ID before changing it is the safe pattern when you only have an event's identifier (from a saved reference or a webhook) rather than an object already in Items:

procedure TForm1.PostponeEventByID(const AEventID: string);
begin
  TMSFNCCloudMicrosoftOutlookCalendar1.OnGetCalendarItem := OutlookCalendarEventFoundThenUpdated;
  TMSFNCCloudMicrosoftOutlookCalendar1.OnUpdateCalendarItem := OutlookCalendarEventRescheduled;
  TMSFNCCloudMicrosoftOutlookCalendar1.GetItemByID(AEventID);
end;

procedure TForm1.OutlookCalendarEventFoundThenUpdated(Sender: TObject;
  const AItem: TTMSFNCCloudMicrosoftOutlookCalendarItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if not ARequestResult.Success then
    Exit;

  AItem.StartTime := AItem.StartTime + 1;
  AItem.EndTime := AItem.EndTime + 1;
  TMSFNCCloudMicrosoftOutlookCalendar1.UpdateItem(AItem);
end;

procedure TForm1.OutlookCalendarEventRescheduled(Sender: TObject;
  const AItem: TTMSFNCCloudMicrosoftOutlookCalendarItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Rescheduled to ' + DateTimeToStr(AItem.StartTime));
end;

Common mistakes

  • Freeing an event right after Add/UpdateItem. The component keeps a reference to the event object until the request completes, to stamp the server-assigned ID (and other read-only fields) onto it — add the event through Items.Add (which the collection owns and frees) rather than a standalone instance you free yourself.
  • Setting CalendarID after calling Add. Add reads CalendarID from the event to build the request path; set it before calling Add, not after.
  • Confusing GetCalendar (events) with GetCalendars (calendars). The singular/plural naming is easy to misread — see the note above.

See also