java.lang.Object | |
↳ | com.google.android.gms.gcm.GcmNetworkManager |
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> ...
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 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Cancels all tasks previously scheduled against the provided GcmTaskService.
| |||||||||||
Cancel a task, specified by tag.
| |||||||||||
Use this function to access the GcmNetworkManager API.
| |||||||||||
Entry point to schedule a task with the network manager.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
![]() |
Indicates a task has failed, but not to reschedule.
Indicates a task has failed to execute, and must be retried with back-off.
Indicates a task has successfully been executed, and can be removed from the queue.
Cancels all tasks previously scheduled against the provided GcmTaskService. Note that a cancel will have no effect on an in-flight task.
Parameters | |
---|---|
gcmTaskService |
Class :
The endpoint for which you want to cancel all outstanding tasks.
|
Cancel a task, specified by tag. Note that a cancel will have no effect on an in-flight task.
Parameters | |
---|---|
tag |
String :
The tag to uniquely identify this task on this endpoint. |
gcmTaskService |
Class :
The endpoint for which you want to cancel all outstanding tasks.
|
Use this function to access the GcmNetworkManager API.
Parameters | |
---|---|
context |
Context :
Context of the calling app. |
Returns | |
---|---|
GcmNetworkManager |
GcmNetworkManager object. |
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 :
Task constructed using Task.Builder . Can be
an instance of PeriodicTask or
OneoffTask .
|