> For the complete documentation index, see [llms.txt](https://assetstore.essentialkit.voxelbusters.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://assetstore.essentialkit.voxelbusters.com/v2/address-book/usage.md).

# Usage

Address Book allows access to contacts on mobile devices.

This feature allows you to read the contacts saved on the mobile devices. All Address Book features can be accessible from **AddressBook** static class. 

Before using any of the plugin's features, you need to import the namespace.

```
using VoxelBusters.EssentialKit;
```

After importing the namespace, AddressBook class is available for accessing all of the Address Book's features.

## Get Contacts Access Status

Get the contacts access status to see if it's allowed to access or denied by the user.\
\
**GetContactAccessStatus** method returns **AddressBookContactsAccessStatus** to identify if the status is NotDetermined/Restricted/Denied/Authorized.

```
AddressBookContactsAccessStatus status = AddressBook.GetContactsAccessStatus();
```

## Request Contact Access

Request the permission if the contact access is not determined yet. Calling RequestContactsAccess might show up a permission dialog on the mobile devices allowing the user to take an action.

You need to pass a callback method to get the status of the user action.

```csharp
AddressBook.RequestContactsAccess(callback: OnRequestContactsAccessFinish);
```

```csharp
private void OnRequestContactsAccessFinish(AddressBookRequestContactsAccessResult result, Error error)
{
    Debug.Log("Request for contacts access finished.");
    Debug.Log("Address book contacts access status: " + result.AccessStatus);
}
```

## Read Contacts

Fetch the contacts available for the user by calling ReadContacts method. You need to pass a callback to get the list of **IAddressBookContact** instances.

```
AddressBook.ReadContacts(OnReadContactsFinish);
```

```csharp
private void OnReadContactsFinish(AddressBookReadContactsResult result, Error error)
{
    if (error == null)
    {
        var     contacts    = result.Contacts;
        Debug.Log("Request to read contacts finished successfully.");
        Debug.Log("Total contacts fetched: " + contacts.Length);
        Debug.Log("Below are the contact details (capped to first 10 results only):");
        for (int iter = 0; iter < contacts.Length && iter < 10; iter++)
        {
            Debug.Log(string.Format("[{0}]: {1}", iter, contacts[iter]));
        }
    }
    else
    {
        Debug.Log("Request to read contacts failed with error. Error: " + error);
    }
}
```

## Read Contacts with User Permission

If you don't need much control on the permission access status but just want to go ahead with reading the contacts, you can call **ReadContactsWithUserPermission**. \
\
This call requests the permission internally and returns the contacts details if authorized or an error if user deny the permission.

```
AddressBook.ReadContactsWithUserPermission(OnReadContactsFinish);
```

```csharp
private void OnReadContactsFinish(AddressBookReadContactsResult result, Error error)
{
    if (error == null)
    {
        var     contacts    = result.Contacts;
        Debug.Log("Request to read contacts finished successfully.");
        Debug.Log("Total contacts fetched: " + contacts.Length);
        Debug.Log("Below are the contact details (capped to first 10 results only):");
        for (int iter = 0; iter < contacts.Length && iter < 10; iter++)
        {
            Debug.Log(string.Format("[{0}]: {1}", iter, contacts[iter]));
        }
    }
    else
    {
        Debug.Log("Request to read contacts failed with error. Error: " + error);
    }
}
```