GcmNetworkManager

public class GcmNetworkManager extends Object

This class is deprecated.
As of November 1, 2020, GCMNetworkManager client libraries are no longer supported. GCMNetworkManager API calls no longer work on devices running Android M and later once your app targets future Android versions ( > Android 10).
Migrate to Jetpack WorkManager for your background scheduling needs.

Class to create apps with robust "send-to-sync", which is the mechanism to sync data with servers where new information is available.

You can use the API to schedule network-oriented tasks, and let Google Play services batch network operations across the system. This greatly simplifies the implementation of common patterns, such as waiting for network connectivity, network retries, and backoff.

Tasks must be scheduled based on an execution window in time. During this execution window the scheduler will use its discretion in picking an optimal execution time, based on network availability (whether the device has connectivity), network activity (whether packages are actively being transferred), and load (how many other pending tasks are available for execution at that point in time). If none of these factors are influential, the scheduler will always wait until the end of the specified window.

To receive the notification from the scheduler that a task is ready to be executed, your client app must implement a GcmTaskService and filter on the action SERVICE_ACTION_EXECUTE_TASK.

Note that tags of arbitrary length are not allowed; if the tag you provide is greater than 100 characters an exception will be thrown when you try to create your Task object.

The service should be protected by the permission com.google.android.gms.permission.BIND_NETWORK_TASK_SERVICE, which is used by Google Play Services. This prevents other code from invoking the broadcast receiver. Here is an excerpt from a sample manifest:


     <service android:name=".MyUploadService"
         android:exported="true"
         android:permission="com.google.android.gms.permission.BIND_NETWORK_TASK_SERVICE">
         <intent-filter>
            <action android:name="com.google.android.gms.gcm.ACTION_TASK_READY" />
         </intent-filter>
     </service>

An execution contains the tag identifier which your client app provides. This identifies one "task," or piece of work, that you mean to perform. Consider the tag to be the key to which your task logic is paired. Here's an example that schedules a one-time task:


     // Schedule a task to occur between five and fifteen minutes from now:
     OneoffTask myTask = new OneoffTask.Builder()
                          .setService(MyUploadService.class)
                          .setExecutionWindow(
                              5 * DateUtil.MINUTE_IN_SECONDS, 15 * DateUtil.MINUTE_IN_SECONDS)
                          .setTag("test-upload")
                          .build();
     GcmNetworkManager.getInstance(this).schedule(myTask);

The service implementation might look something like this:


     // Implement service logic to be notified when the task elapses
     class MyUploadService extends GcmTaskService {
         @Override
         public int onRunTask(TaskParams params) {
             // Do some upload work
             return GcmNetworkManager.RESULT_SUCCESS;
         }
     }

To aid in debugging tasks, you can dump the currently scheduled tasks using adb


     adb shell dumpsys activity service GcmService --endpoints <class1> <class2> ...

Constant Summary

int RESULT_FAILURE Indicates a task has failed, but not to reschedule.
int RESULT_RESCHEDULE Indicates a task has failed to execute, and must be retried with back-off.
int RESULT_SUCCESS Indicates a task has successfully been executed, and can be removed from the queue.

Public Method Summary

void
cancelAllTasks(Class<? extends GcmTaskService> gcmTaskService)
Cancels all tasks previously scheduled against the provided GcmTaskService.
void
cancelTask(String tag, Class<? extends GcmTaskService> gcmTaskService)
Cancel a task, specified by tag.
static GcmNetworkManager
getInstance(Context context)
Use this function to access the GcmNetworkManager API.
synchronized void
schedule(Task task)
Entry point to schedule a task with the network manager.

Inherited Method Summary

Constants

public static final int RESULT_FAILURE

Indicates a task has failed, but not to reschedule.

Constant Value: 2

public static final int RESULT_RESCHEDULE

Indicates a task has failed to execute, and must be retried with back-off.

Constant Value: 1

public static final int RESULT_SUCCESS

Indicates a task has successfully been executed, and can be removed from the queue.

Constant Value: 0

Public Methods

public void cancelAllTasks (Class<? extends GcmTaskService> gcmTaskService)

Cancels all tasks previously scheduled against the provided GcmTaskService. Note that a cancel will have no effect on an in-flight task.

Since this involves system IPC calls that can ocassionally be slow, it should be called on a background thread to avoid blocking the main (UI) thread.

Parameters
gcmTaskService The endpoint for which you want to cancel all outstanding tasks.

public void cancelTask (String tag, Class<? extends GcmTaskService> gcmTaskService)

Cancel a task, specified by tag. Note that a cancel will have no effect on an in-flight task.

Since this involves system IPC calls that can ocassionally be slow, it should be called on a background thread to avoid blocking the main (UI) thread.

Parameters
tag The tag to uniquely identify this task on this endpoint.
gcmTaskService The endpoint of the task to cancel.

public static GcmNetworkManager getInstance (Context context)

Use this function to access the GcmNetworkManager API.

Parameters
context Context of the calling app.
Returns
  • GcmNetworkManager object.

public synchronized void schedule (Task task)

Entry point to schedule a task with the network manager.

If Google Play services is unavailable (upgrading, missing, etc). This call will fail silently. You should wrap it in a call to isGooglePlayServicesAvailable(android.content.Context).

Since this involves system IPC calls that can ocassionally be slow, it should be called on a background thread to avoid blocking the main (UI) thread.

Rescheduling a currently executing task will release the corresponding wakelock, so this should be the last step in a onRunTask(TaskParams) implementation.

Parameters
task Task constructed using Task.Builder. Can be an instance of PeriodicTask or OneoffTask.