ContactsContract.Directory

Class Overview

A Directory represents a contacts corpus, e.g. Local contacts, Google Apps Global Address List or Corporate Global Address List.

A Directory is implemented as a content provider with its unique authority and the same API as the main Contacts Provider. However, there is no expectation that every directory provider will implement this Contract in its entirety. If a directory provider does not have an implementation for a specific request, it should throw an UnsupportedOperationException.

The most important use case for Directories is search. A Directory provider is expected to support at least Contacts.CONTENT_FILTER_URI. If a Directory provider wants to participate in email and phone lookup functionalities, it should also implement CommonDataKinds.Email.CONTENT_FILTER_URI and CommonDataKinds.Phone.CONTENT_FILTER_URI.

A directory provider should return NULL for every projection field it does not recognize, rather than throwing an exception. This way it will not be broken if ContactsContract is extended with new fields in the future.

The client interacts with a directory via Contacts Provider by supplying an optional directory= query parameter.

When the Contacts Provider receives the request, it transforms the URI and forwards the request to the corresponding directory content provider. The URI is transformed in the following fashion:

• The URI authority is replaced with the corresponding DIRECTORY_AUTHORITY.
• The accountName= and accountType= parameters are added or replaced using the corresponding ACCOUNT_TYPE and ACCOUNT_NAME values.

Clients should send directory requests to Contacts Provider and let it forward them to the respective providers rather than constructing directory provider URIs by themselves. This level of indirection allows Contacts Provider to implement additional system-level features and optimizations. Access to Contacts Provider is protected by the READ_CONTACTS permission, but access to the directory provider is protected by BIND_DIRECTORY_SEARCH. This permission was introduced at the API level 17, for previous platform versions the provider should perform the following check to make sure the call is coming from the ContactsProvider:

 private boolean isCallerAllowed() {
   PackageManager pm = getContext().getPackageManager();
   for (String packageName: pm.getPackagesForUid(Binder.getCallingUid())) {
     if (packageName.equals("com.android.providers.contacts")) {
       return true;
     }
   }
   return false;
 }
 

The Directory table is read-only and is maintained by the Contacts Provider automatically.

It always has at least these two rows:

• The local directory. It has Directory._ID = Directory.DEFAULT. This directory can be used to access locally stored contacts. The same can be achieved by omitting the directory= parameter altogether.
• The local invisible contacts. The corresponding directory ID is Directory.LOCAL_INVISIBLE.

Custom Directories are discovered by the Contacts Provider following this procedure:

• It finds all installed content providers with meta data identifying them as directory providers in AndroidManifest.xml: <meta-data android:name="android.content.ContactDirectory" android:value="true" />

  This tag should be placed inside the corresponding content provider declaration.

• Then Contacts Provider sends a Directory.CONTENT_URI query to each of the directory authorities. A directory provider must implement this query and return a list of directories. Each directory returned by the provider must have a unique combination for the ACCOUNT_NAME and ACCOUNT_TYPE columns (nulls are allowed). Since directory IDs are assigned automatically, the _ID field will not be part of the query projection.
• Contacts Provider compiles directory lists received from all directory providers into one, assigns each individual directory a globally unique ID and stores all directory records in the Directory table.

Contacts Provider automatically interrogates newly installed or replaced packages. Thus simply installing a package containing a directory provider is sufficient to have that provider registered. A package supplying a directory provider does not have to contain launchable activities.

Every row in the Directory table is automatically associated with the corresponding package (apk). If the package is later uninstalled, all corresponding directory rows are automatically removed from the Contacts Provider.

When the list of directories handled by a directory provider changes (for instance when the user adds a new Directory account), the directory provider should call notifyDirectoryChange(ContentResolver) to notify the Contacts Provider of the change. In response, the Contacts Provider will requery the directory provider to obtain the new list of directories.

A directory row can be optionally associated with an existing account (see AccountManager). If the account is later removed, the corresponding directory rows are automatically removed from the Contacts Provider.

Summary

[Expand] Inherited Constants
From interface android.provider.BaseColumns String _COUNT The count of rows in a directory. String _ID The unique ID for a row.

[Expand] Inherited Methods

From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.