Skip to main content
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.

Retrieve events in a date range, or a single event by IDPascalC++
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;

void __fastcall TForm1::ListThisWeeksEvents(const System::UnicodeString ACalendarID)
{
  TMSFNCCloudMicrosoftOutlookCalendar1->OnGetCalendar = OutlookCalendarEventsListed;
  // GetCalendar retrieves events, despite the singular calendar-sounding name.
  TMSFNCCloudMicrosoftOutlookCalendar1->GetCalendar(ACalendarID, Date(), Date() + 7);
}

void __fastcall TForm1::OutlookCalendarEventsListed(TObject *Sender,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (!ARequestResult->Success)
    return;

  for (int i = 0; i < TMSFNCCloudMicrosoftOutlookCalendar1->Items->Count; i++)
  {
    TTMSFNCCloudMicrosoftOutlookCalendarItem *ev = TMSFNCCloudMicrosoftOutlookCalendar1->Items->Items[i];
    Memo1->Lines->Add(ev->Summary + " @ " + DateTimeToStr(ev->StartTime));
  }
}

void __fastcall TForm1::LookUpEventByID(const System::UnicodeString AEventID)
{
  TMSFNCCloudMicrosoftOutlookCalendar1->OnGetCalendarItem = OutlookCalendarEventFound;
  TMSFNCCloudMicrosoftOutlookCalendar1->GetItemByID(AEventID);
}

void __fastcall TForm1::OutlookCalendarEventFound(TObject *Sender,
  TTMSFNCCloudMicrosoftOutlookCalendarItem *AItem,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (ARequestResult->Success)
    Memo1->Lines->Add(AItem->Summary + " in " + AItem->Location);
}

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.

Create a calendar event with an attendeePascalC++
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;

void __fastcall TForm1::ScheduleReviewMeeting(const System::UnicodeString ACalendarID)
{
  // 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.
  TTMSFNCCloudMicrosoftOutlookCalendarItem *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.0 / 24);
  ev->Attendees->Add()->Email = "reviewer@example.com";

  TMSFNCCloudMicrosoftOutlookCalendar1->OnAddCalendarItem = OutlookCalendarEventAdded;
  TMSFNCCloudMicrosoftOutlookCalendar1->Add(ev);
}

void __fastcall TForm1::OutlookCalendarEventAdded(TObject *Sender,
  TTMSFNCCloudMicrosoftOutlookCalendarItem *AItem,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (ARequestResult->Success)
    Memo1->Lines->Add("Created event " + AItem->ID);
}

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.

Update and delete a calendar eventPascalC++
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;

void __fastcall TForm1::PostponeEvent(TTMSFNCCloudMicrosoftOutlookCalendarItem *AEvent)
{
  AEvent->StartTime = AEvent->StartTime + 1;
  AEvent->EndTime = AEvent->EndTime + 1;

  TMSFNCCloudMicrosoftOutlookCalendar1->OnUpdateCalendarItem = OutlookCalendarEventUpdated;
  TMSFNCCloudMicrosoftOutlookCalendar1->UpdateItem(AEvent);
}

void __fastcall TForm1::OutlookCalendarEventUpdated(TObject *Sender,
  TTMSFNCCloudMicrosoftOutlookCalendarItem *AItem,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (ARequestResult->Success)
    Memo1->Lines->Add("Event moved to " + DateTimeToStr(AItem->StartTime));
}

void __fastcall TForm1::CancelEventByID(const System::UnicodeString AEventID)
{
  TMSFNCCloudMicrosoftOutlookCalendar1->OnDeleteCalendarItem = OutlookCalendarEventDeleted;
  TMSFNCCloudMicrosoftOutlookCalendar1->Delete(AEventID);
}

void __fastcall TForm1::OutlookCalendarEventDeleted(TObject *Sender, const System::UnicodeString AID,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (ARequestResult->Success)
    Memo1->Lines->Add("Deleted event " + AID);
}

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:

Look up an event by ID, then reschedule itPascalC++
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;

void __fastcall TForm1::PostponeEventByID(const System::UnicodeString AEventID)
{
  TMSFNCCloudMicrosoftOutlookCalendar1->OnGetCalendarItem = OutlookCalendarEventFoundThenUpdated;
  TMSFNCCloudMicrosoftOutlookCalendar1->OnUpdateCalendarItem = OutlookCalendarEventRescheduled;
  TMSFNCCloudMicrosoftOutlookCalendar1->GetItemByID(AEventID);
}

void __fastcall TForm1::OutlookCalendarEventFoundThenUpdated(TObject *Sender,
  TTMSFNCCloudMicrosoftOutlookCalendarItem *AItem,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (!ARequestResult->Success)
    return;

  AItem->StartTime = AItem->StartTime + 1;
  AItem->EndTime = AItem->EndTime + 1;
  TMSFNCCloudMicrosoftOutlookCalendar1->UpdateItem(AItem);
}

void __fastcall TForm1::OutlookCalendarEventRescheduled(TObject *Sender,
  TTMSFNCCloudMicrosoftOutlookCalendarItem *AItem,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (ARequestResult->Success)
    Memo1->Lines->Add("Rescheduled to " + DateTimeToStr(AItem->StartTime));
}

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