Summary: Constants | Methods | Inherited Methods | [Expand All]
public class

# GcmNetworkManager

extends Object

java.lang.Object
↳ | com.google.android.gms.gcm.GcmNetworkManager

## Class Overview

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(MyGcmTaskService.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> ...

## Summary

Constants
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 Methods
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.
void | schedule(Task task) Entry point to schedule a task with the network manager.

[Expand] Inherited Methods
From class java.lang.Object
Object | clone()
boolean | equals(Object arg0)
void | finalize()
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()

## Constants

#### public static final int RESULT_FAILURE

Indicates a task has failed, but not to reschedule.

Constant Value: 2 (0x00000002)

#### public static final int RESULT_RESCHEDULE

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

Constant Value: 1 (0x00000001)

#### public static final int RESULT_SUCCESS

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

Constant Value: 0 (0x00000000)

## 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.

##### 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.

##### Parameters

tag | The tag to uniquely identify this task on this endpoint.
gcmTaskService | The endpoint for which you want to cancel all outstanding tasks.

#### 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 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)`

##### Parameters

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