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.
// Schedule a task to occur between five and fifteen seconds 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.get(this).schedule(myTask);
...
// Implement service logic to be notified when the task elapses:
MyUploadService extends GcmTaskService {
@Override
public int onRunTask(TaskParams params) {
// Do some upload work.
return GcmNetworkManager.RESULT_SUCCESS;
}
}
To help in debugging your tasks, run adb shell dumpsys activity service GcmService --endpoints... where is the name of your GcmTaskService class.
If you want to execute your task immediately (for debugging) you can execute tasks from the command line via: adb shell am broadcast -a "com.google.android.gms.gcm.ACTION_TRIGGER_TASK" \ -e component <COMPONENT_NAME> -e tag <TAG> Where COMPONENT_NAME: The fullflattenToString()
returned for your implementation ofGcmTaskService
. TAG: the tag you want to have land inonRunTask(TaskParams)
Example usage for the gradle target GcmTestProxy service: adb shell am broadcast -a "com.google.android.gms.gcm.ACTION_TRIGGER_TASK" \ -e component "com.google.android.gms.gcm.test.proxy/.internal.nstest.TestNetworkTaskService" \ -e tag "upload" This is only available if the device is a test-keys build. This will replace any previously scheduled task with the same tag! This will have especially awkward effects if your original task was a periodic, because the debug task is scheduled as a one-off.
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.
gcmTaskService | 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.
tag | The tag to uniquely identify this task on this endpoint. |
---|---|
gcmTaskService | The endpoint for which you want to cancel all outstanding tasks. |
Use this function to access the GcmNetworkManager API.
context | Context of the calling app. |
---|
Entry point to schedule a task with the network manager.
If GooglePlayServices is unavailable (upgrading, missing, etc). This call will fail silently.
You should wrap it in a call to isGooglePlayServicesAvailable(android.content.Context)
task | Task constructed using Task.Builder . Can be
an instance of PeriodicTask or
OneoffTask .
|
---|