Call Control DataShare is a mechanism which allows other apps to interact with Call Control for Android application. It allows to enable powerful calls/texts blocking possibilities in 3rd party apps without significant effort.

The benefits of this approach:

• Call Control maintains the infrastructure, provides powerful features like Community IQ™ and other blocking features. No need to implement your own.
• Call Control takes care of user settings and allows the 3rd party apps to honor it effortlessly, providing slick user experience and eliminating the need to force user to have different settings in different apps for the same purpose.
• Very basic implementation is needed for 3rd party apps.

The implementation is based on Content Provider exposed by Call Control. Call Control provides the library with Contract Classes to ease the access.

The main idea is that for every phone number Call Control can tell whether or not it should be blocked and why. In addition to that, it may provide with the known name for the number, if any.

Due to Android implementation restrictions¹, the permission model is not used to control access to the exposed Content Provider.
In fact, Call Control doesn't require 3rd party applications to poses any extra permissions.
However, some declarations have to be made in the Manifest file, specifically in <application> element.

Call Control requires that any 3rd party application which uses DataShare integration declare the scope of the integration.
There are two scopes defined:

• com.callcontrol.datashare.calls for call filtering scope;
• com.callcontrol.datashare.messaging for text filtering scope;

These two can be used together as well as separately, but at least one scope should be defined in the <application> element of the application Manifest.

To define it, a <meta-data> element needs to be added as following:

<meta-data
    android:name="com.callcontrol.datashare.calls"
    android:value="true" />

or

<meta-data
    android:name="com.callcontrol.datashare.messaging"
    android:value="true" />

or both

<meta-data
    android:name="com.callcontrol.datashare.calls"
    android:value="true" />
<meta-data
    android:name="com.callcontrol.datashare.messaging"
    android:value="true" />

This is used not only to ensure the proper handling of the requests, but it also will suggest the applications declaring the certain scope of integration where applicable.
For example, when user is looking for messaging app, Call Control will automatically suggest all installed applications that declare com.callcontrol.datashare.messaging scope.

To query Call Control, Content Resolver is used. It requires you to specify Uri.
The Uri to query Call Control is built as follows:

content://com.callcontrol.datashare/lookup/CONTENT_TYPE/PHONE_NUMBER

For example, for checking a number (425) 555-3333 sent a text message, the following URI would be used:

content://com.callcontrol.datashare/lookup/text/(425) 555-3333

There is no restriction on number formatting, it is preferred to use the number in the form it originally came in — Call Control will do the magic.
Just use Uri.withAppendedPath(Uri, String) (see here) to add phone number to the Uri.

By default, the returned Cursor will contain a single row with the following columns:

The method is called using ContentResolver.query method. See Examples for more details.

Please Note: Call Control may do some background work in order to fulfill the request, which may, or may not involve network operations. This implies that all requests to the lookup Uri SHOULD NOT BE MADE FROM THE MAIN THREAD. Use background threads or AsyncTask to perform the request.
However, if there is absolutely no way avoiding the the main thread, you could pass the projection parameter containing only one column BLOCK_REASON to the query method, which will only return the block reason (if any) for the number. This operation is fast, simple and will not trigger any background processes or network activity.

Call Control provides an easy-to-use library containing contract classes for easy integration.

To integrate with Call Control DataShare you need to install Call Control from Google Play, then in your application's build.gradle add the following dependency:

dependencies {
	...
	implementation 'com.callcontrol:datashare:1.1.0'
	...
}

That's all you need to do to integrate, you can now use all power of Call Control!

For more details on contract classes, please refer to included javadoc

In addition to the Content Provider based implementation, Call Control provides an easier way to utilize its possibilities. There are Intent actions available to present certain Call Control UI screens eliminating the need to implement your own, plus providing some extra functionality otherwise unavailable, like numbers lookup.

The actions provided are explained below in corresponding sections.
The action descriptions can be found in javadoc.

Please Note: In order to protect Call Control, your application, and the user experience we build together, Call Control requires the intents to be "signed". This process is automated by the library so not described here. This process ensures that each application sending an intent to Call Control is actually the application it pretends to be.

This action allows to open Blocked List of Call Control application, so user can easily manage the numbers blocked.
In case you need to present the specific blocked record, you can pass an optional phone number and Call Control will open the screen specific for the number provided, if that is possible.

Library methods:
CallControl.openBlockedList(Context)
CallControl.openBlockedList(Context, int)
CallControl.openBlockedList(Context, String)
CallControl.openBlockedList(Context, String, int)

Please find more details in javadoc.
Please also check usage examples.

This action allows 3rd party apps to utilize the complete reporting UI provided by Call Control. In the UI shown, user will be able to provide additional details if necessary.

The reporting can be done for either a single number or an ArrayList of CallControl.Report objects, each with phone number being reported. Each reported number could also contain a name if known and the flag indicating whether this number is unwanted or wanted.

The bulk reporting is useful when user enables the integration and your application wants to let Call Control know about the previously blocked numbers.

Library methods:
CallControl.reportNumber(Context, Report)
CallControl.reportNumber(Context, Report, int)
CallControl.reportNumbers(Context, ArrayList<Report>)
CallControl.reportNumbers(Context, ArrayList<Report>, int)

Please find more details in javadoc.
Please also check usage examples.

Please Note: When reporting a list of numbers, the ifUnwanted flag must be set identical for all the numbers in the list. In other words, you can report a list of unwanted calls, or a list of wanted calls, but not a mixed list containing both.

This action opens a lookup screen which provides user with the information about the phone number. Our database is community supported and provides valuable names for the numbers not otherwise known to the user. There are also further lookup options.

Please suggest user to lookup the information about any number via this action where appropriate. This is especially useful for the numbers your application doesn't have any information for the number.

The number is preferred in "as is" formatting.

Library methods:
CallControl.lookupNumber(Context, String)
CallControl.lookupNumber(Context, String, int)

Please find more details in javadoc.
Please also check usage examples.

This action opens a screen which provides user control over which 3rd party apps have access to Call Control. User can allow or block access for any 3rd party apps ever accessed Call Control.

Library methods:
CallControl.openAccessSettings(Context)
CallControl.openAccessSettings(Context, int)

Please find more details in javadoc.
Please also check usage examples.

For example, let's assume a text messaging app received a new text and needs to check whether or not the text should be actually received and presented to user. The sender number is (555) 444-3333. The application performs the following query:

String phoneNumber = "(555) 444-3333";
Uri uri = Uri.withAppendedPath(CallControl.LOOKUP_TEXT_URI, phoneNumber);

try {
    Cursor c = context.contentResolver.query(uri, null, null, null, null);
    if (null != c && c.moveToFirst()) {
        String reason = c.getString(c.getColumnIndex(CallControl.Lookup.BLOCK_REASON));
        String name = c.getString(c.getColumnIndex(CallControl.Lookup.DISPLAY_NAME));
        if (null != reason) {
            //The text should be blocked and not presented to the user
        } else {
            //The sender should not be blocked, proceed normally
        }
        if (null != name) {
            //Regardless of BLOCK_REASON, the name may still be available, 
            //so it can be presented
        }
    }
    if (null != c) c.close();
} catch (Throwable e) { 
    e.printStackTrace();
}

To report a sender, for example, number 5554443333, application can do the following:

CallControl.reportNumber(context, new Report("5554443333"));

In case you want to report a set of numbers:

CallControl.reportNumber(context, new Report[] {
	new Report("5554443333", "Ex."),
	new Report("555")
});

To lookup number data:

String phoneNumber = "5554443333";
CallControl.lookup(context, phoneNumber);

To just open Blocked List:

CallControl.openBlockedList(context);

To open specific number in the Blocked List (if it exists):

String phoneNumber = "5554443333";
CallControl.openBlockedList(context, phoneNumber)

To open 3rd Party Access screen:

CallControl.openAccessSettings(context);

In all Intent-based actions you can specify intent flags, which will be set to the intent. To do that, you can use the appropriate method overload, like this:

CallControl.openAccessSettings(context, Intent.FLAG_ACTIVITY_NEW_TASK);

or like this:

String phoneNumber = "5554443333";
CallControl.lookup(context, phoneNumber, Intent.FLAG_ACTIVITY_NEW_TASK);

The calling app is constantly monitored and the activity is reported by Call Control to the user. In addition to that, the amount of requests a calling app can perform is limited to a certain amount of requests per time interval. In case Call Control detects any unusual, or undesirable activity it will block application access until further user intervention. User may also restrict interaction for certain apps.

Call Control will throw exception in case of error or access violations. The calling app must handle exceptions properly.

¹ The problem with permission model is that Android requires that application providing permission is installed prior to the application requiring the provided permission. In the opposite case the requiring app never gets the permission granted.

Call Control® is a registered trademark of Call Control, LLC