Table of Contents

Managing contacts

Contacts are the heart of the People API. TTMSFNCCloudGooglePeople keeps the account's contacts in its Contacts collection and exposes asynchronous operations to fetch, create, edit, and delete them. Each operation returns immediately and reports completion through a matching On... event whose ARequestResult tells you whether it succeeded. This chapter covers retrieving the list, the create/update/delete cycle, and reading the rich detail fields a contact carries.

Retrieving contacts

Call GetContacts to load the account's contacts. When the request completes, OnGetContacts fires and the Contacts collection is populated; read it there or any time afterwards. Each TTMSFNCCloudGooglePeopleContact exposes a Names sub-object — Names.Name is the formatted display name, with FirstName and LastName for the parts.

procedure TForm1.LoadContacts;
begin
  // Asynchronous: returns immediately; the result arrives in OnGetContacts.
  FPeople.GetContacts;
end;

procedure TForm1.PeopleGetContacts(Sender: TObject;
  const AInfo: TTMSFNCCloudGooglePeopleContacts;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
var
  I: Integer;
begin
  if not ARequestResult.Success then
    Exit;

  // Contacts are also available afterwards through the component's Contacts collection.
  ListBox1.Clear;
  for I := 0 to FPeople.Contacts.Count - 1 do
    ListBox1.Items.Add(FPeople.Contacts[I].Names.Name);
end;

Creating, updating, and deleting contacts

The write cycle works through the same Contacts collection. Add a new entry with Contacts.Add, set its fields, and call CreateContact; edit an existing entry in place and call UpdateContact; remove one with DeleteContact. Each call is asynchronous and reports back through OnCreateContact, OnUpdateContact, or OnDeleteContact respectively — refresh your UI there rather than immediately after the call.

procedure TForm1.CreateContact(const AFirstName, ALastName: string);
var
  Contact: TTMSFNCCloudGooglePeopleContact;
begin
  Contact := FPeople.Contacts.Add;
  Contact.Names.FirstName := AFirstName;
  Contact.Names.LastName := ALastName;
  FPeople.CreateContact(Contact); // result arrives in OnCreateContact
end;

procedure TForm1.RenameContact(AIndex: Integer; const ANewLast: string);
var
  Contact: TTMSFNCCloudGooglePeopleContact;
begin
  Contact := FPeople.Contacts[AIndex];
  Contact.Names.LastName := ANewLast;
  FPeople.UpdateContact(Contact); // result arrives in OnUpdateContact
end;

procedure TForm1.RemoveContact(AIndex: Integer);
begin
  FPeople.DeleteContact(FPeople.Contacts[AIndex]); // result arrives in OnDeleteContact
end;

Reading contact detail fields

Beyond the name, a contact carries several multi-value collections — Emails, PhoneNumbers, PostalAddresses, and Websites — plus a BirthDay and an ImageURL. Each collection is indexed and counted like any list, so iterate it to show every value. This example reads the common detail fields of a selected contact into a form.

procedure TForm1.ShowContactDetails(AIndex: Integer);
var
  Contact: TTMSFNCCloudGooglePeopleContact;
  I: Integer;
begin
  Contact := FPeople.Contacts[AIndex];

  edID.Text := Contact.ID;
  Edit1.Text := Contact.Names.FirstName;
  Edit2.Text := Contact.Names.LastName;
  Edit4.Text := Contact.ImageURL;

  // A contact carries several multi-value collections.
  lbMails.Clear;
  for I := 0 to Contact.Emails.Count - 1 do
    lbMails.Items.Add(Contact.Emails[I].Address);

  lbTelNo.Clear;
  for I := 0 to Contact.PhoneNumbers.Count - 1 do
    lbTelNo.Items.Add(Contact.PhoneNumbers[I].Number);

  lbAddress.Clear;
  for I := 0 to Contact.PostalAddresses.Count - 1 do
    lbAddress.Items.Add(Contact.PostalAddresses[I].City);

  lbWebsite.Clear;
  for I := 0 to Contact.Websites.Count - 1 do
    lbWebsite.Items.Add(Contact.Websites[I].URL);

  edBirthYear.Text := IntToStr(Contact.BirthDay.Date.Year);
  edBirthMonth.Text := IntToStr(Contact.BirthDay.Date.Month);
  edBirthDay.Text := IntToStr(Contact.BirthDay.Date.Day);
end;

Pitfalls

  • Read results in the completion event, not right after the call. The operations are asynchronous; the Contacts collection and a created contact's server-assigned ID are only guaranteed once the matching On... event fires.
  • Check ARequestResult.Success before using returned data — a failed request still raises the event.
  • Edit the existing collection item for updates. Modify the TTMSFNCCloudGooglePeopleContact from Contacts (which keeps its ID) and pass it to UpdateContact; a detached instance has no identity to update.

See also