Accessing the address book on iOS and Android

Address Book development on iOS and Android

Accessing the Address Book on iOS and Android is a common request for many developers building line of business applications; quickly followed by “and how do I dial a phone number from code“. In this post I will explore how to explore the mobile Address Book using a common code base that works on iOS and Android using TAddressBook. (list to samples and documentation at the bottom of this article)

TAddressBook

With the launch of RAD Studio 10.1 Berlin, Delphi, C++ Builder,  comes a new component, TAddressBook, that enables easy access to the Address Book on iOS and Android.

The TAddressBook lives under Services section of the tool palette and consists of two and has very little in the way of Component properties. It does however have two events that are very useful, and a number of run time methods to call.

TAddressBook Component Events
TAddressBook Component Events

The two events provide notification when the address book has been changed (outside the application) and the result of the application asking for access to the address book.

Enabling TAddressBook Permissions

The request for Permissions is different on Android and iOS. On iOS, the OS asks the user via a dialog if they want to allow access. On Android, you need to set the permissions with the application and they are confirmed by the user to install the application. If you forget you will get a denied response.

To setup the manifest with permissions on Android, open the Project > Options and under Uses Permissions, select All configurations for Android near the top of the list and enable Contacts Read / Write as required for your application.

Enabling Android Contact Permissions for the Address Book
Enabling Android Contact Permissions for the Address Book

Confirming Address Book access via code

With permissions setup completed on Android (we will have to wait for the user to do it at run time on iOS) Its time to write the first line of code – This will ask the address book to check it has Permissions to access the address book.

procedure TForm1.FormCreate(Sender: TObject);
begin
  AddressBook1.RequestPermission;
end;

Obviously, you can do it where you want, but using FormCreate is a sensible place to easy ask the AddressBook to request permissions as you can then use the resulting method to update the UI accordingly if you have access.

procedure TForm1.AddressBook1PermissionRequest
 (ASender: TObject; const AMessage: string; 
  const AAccessGranted: Boolean);
begin
  btnRefresh.Visible := AAccessGranted;
end;

Loading Address Book Contacts

With the address book access confirmed for TAddressBook, we are now safe to call the address book to read / write to the contacts.

The address books on mobile have concepts of sources and groups (which seem to be used differently depending on iOS / Android and if you have used iCloud to add people or your phone etc..) Contacts can either be fetched completely or via a specific group.

Using TAddressBook you can manage the list of Groups (e.g. to add a group to maintain a list for your applications contacts) but I’ll not cover that here.  (see TAddressBook.CreateGroup, TAddressBook.RemoveGroup)

To fetch contacts you need to

  1. Create a TAddressBookContacts object to manage the contacts fetched.
  2. Call one of the following TAddressBook methods
    • AllContacts
    • AllContactsInGroup
    • AllContactsInGroups
  3. Do something with the TAddressBookContact instances returned into your TAddressBookContacts instance.
procedure TForm1.LoadContacts;
var
  ABC: TAddressBookContacts;
  C  : TAddressBookContact;
begin
  ABC := TAddressBookContacts.Create;
  try
    AddressBook1.AllContacts(ABC);
    for C  in ABC do begin
      // Do something with the contact
    end;
  finally
    ABC.Free;
  end;
end;

You can look up TAddressBookContact to see how the contact details are structured, or you can use code completion.

AddressBook Contact Display
Click image to enlarge example of adding contacts to a ListView manually

Phone numbers are listed as an array and you can see from the code completion the complete list of properties.

To fetch a specific contact you can use the ID to call

  • TAddressBook.ContactByID (passing in the ID integer).

To Add / Remove / Update contacts use the following methods

  • TAddressBook.CreateContact (that returns a new contact)
  • TAddressBook.SaveContact (passing in the contact to save)
  • TAddressBook.RemoveContact (pass in the contact to remove)

To Add / Remove Contacts from a group call

  • TAddressBook.AddContactIntoGroup (pass in group and contact)
  • TAddressBook.RemoveContactFromGroup (pass in group and contact)

TAddressBook sample and tutorial articles

Leave a Reply

Your email address will not be published. Required fields are marked *