# Class CallDirectory

java.lang.Object
com.codename1.call.directory.CallDirectory

public final class CallDirectory extends Object

Naming and blocking numbers, for calls that have nothing to do with this app.

This is the caller-ID and spam-blocking feature: an ordinary cellular call arrives, and the system asks the installed directories whether any of them recognises the number.

    DirectoryEntry[] entries = {
        new DirectoryEntry(14155551212L, "Acme Support"),
        new DirectoryEntry(14155559999L, null, true)     // blocked
    };
    CallDirectory.setEntries(entries).ready(v -> CallDirectory.reload());

##### It is a different process, and it is not fast

On iOS the numbers are read by a separate app extension that the system starts on its own schedule, with a tight memory limit and no access to anything this app holds in memory. The data therefore has to be written to a shared container before it can be used, which is what `setEntries(DirectoryEntry[])` does -- and why installing it and asking the system to read it are two steps.

##### The user has to switch it on

On iOS caller identification is off until the user enables this app in Settings, and nothing the app does can turn it on. Check `DirectoryStatus.isEnabled()` before concluding that a load failed.

##### Referencing this package does not make an app a calling app

This is deliberately separate from `com.codename1.call.session`: a caller-ID app carries no telephony permissions and no VoIP background mode, because it never owns a call.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static AsyncResource<DirectoryStatus>`
  `getStatus()`
  Asks the system what it currently thinks of this app's directory.
  `static boolean`
  `isSupported()`
  Whether this platform can install caller identification or blocking.
  `static AsyncResource<Boolean>`
  `reload()`
  Asks the system to re-read what `setEntries(DirectoryEntry[])` installed.
  `static AsyncResource<Boolean>`
  `requestScreeningRole()`
  Asks the user to let this app screen incoming calls.
  `static AsyncResource<Boolean>`
  `setEntries(DirectoryEntry[] entries)`
  Writes `entries` where the system can read them, sorting them first.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### isSupported

    public static boolean isSupported()
    Whether this platform can install caller identification or blocking.

  - ### setEntries

    public static AsyncResource<Boolean> setEntries(DirectoryEntry[] entries)

    Writes `entries` where the system can read them, sorting them first.

    The sort is not a convenience. Both platforms reject an out-of-order list wholesale, naming no row, so doing it here removes a failure mode that is otherwise very hard to diagnose from the error the platform gives.

    Duplicate numbers are collapsed, keeping the first, because a duplicate is also grounds for rejection.

  - ### reload

    public static AsyncResource<Boolean> reload()
    Asks the system to re-read what `setEntries(DirectoryEntry[])` installed.

  - ### getStatus

    public static AsyncResource<DirectoryStatus> getStatus()
    Asks the system what it currently thinks of this app's directory.

  - ### requestScreeningRole

    public static AsyncResource<Boolean> requestScreeningRole()

    Asks the user to let this app screen incoming calls.

    Android only; on iOS the equivalent is the user enabling the app in Settings, which an app cannot prompt for. Resolves false where the role was refused or does not exist.