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 | |
synchronized void |
Inherited Method Summary
Constants
public static final int RESULT_FAILURE
Indicates a task has failed, but not to reschedule.
public static final int RESULT_RESCHEDULE
Indicates a task has failed to execute, and must be retried with back-off.
public static final int RESULT_SUCCESS
Indicates a task has successfully been executed, and can be removed from the queue.
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 . |
---|