GcmTaskService

public abstract class GcmTaskService extends Service

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.

Implemented by the client application to provide an endpoint for the GcmNetworkManager to call back to when a task is ready to be executed.

Clients must add this service to their manifest and implement onRunTask(com.google.android.gms.gcm.TaskParams). This service must provide an IntentFilter on the action SERVICE_ACTION_EXECUTE_TASK. Here's an example:

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

The return value of onRunTask(TaskParams) will determine what the manager does with subsequent executions of this task. Returning either RESULT_FAILURE or RESULT_SUCCESS will signal that this invocation is finished. In the case of a periodic task, future invocations of the same task will continue to be executed according to the intervals that were originally assigned. Returning RESULT_RESCHEDULE will cause the task to be retried after an initially short backoff delay that grows exponentially with the number of retries requested.

Once a task is running, it will not be stopped. You can change the schedule for a task by rescheduling using the same tag and service class, however if a task with the same identity is currently running then it will be allowed to finish. The new schedule then takes place, regardless of the value that the old task returned.

Per service, two tasks with the same tag will never execute concurrently. Should a newly-scheduled task arrive while an existing task is still running, the new task will be dropped. In addition, different tasks may be scheduled concurrently, each invoked in a separate thread, if their schedules overlap. It is up to you to ensure thread safety when scheduling multiple tasks.

The scheduler will hold a PowerManager.WakeLock for your service, however after three minutes of execution if your task has not returned it will be considered to have timed out, and the wakelock will be released. Rescheduling your task (returning RESULT_RESCHEDULE) at this point will have no effect.

If you suspect your task will run longer than this, you should start your own service explicitly or use some other mechanism; this API is intended for relatively quick network operations.

Constant Summary

String SERVICE_ACTION_EXECUTE_TASK Action broadcast by the GcmNetworkManager to the requesting package when a scheduled task is ready for execution.
String SERVICE_ACTION_INITIALIZE Action that a GcmTaskService is started with when the service needs to initialize its tasks.
String SERVICE_PERMISSION You must protect your service with this permission to avoid being bound to by an application other than Google Play Services.

Inherited Constant Summary

Public Constructor Summary

GcmTaskService()

Public Method Summary

IBinder
onBind(Intent intent)
Receives the command to begin doing work, for which it spawns another thread.
void
onCreate()
void
onDestroy()
void
onInitializeTasks()
When your package is removed or updated, all of its network tasks are cleared by the GcmNetworkManager.
abstract int
onRunTask(TaskParams params)
Override this function to provide the logic for your task execution.
int
onStartCommand(Intent intent, int flags, int startId)
Receives the command to begin doing work, for which it spawns another thread.

Inherited Method Summary

Constants

public static final String SERVICE_ACTION_EXECUTE_TASK

Action broadcast by the GcmNetworkManager to the requesting package when a scheduled task is ready for execution.

Constant Value: "com.google.android.gms.gcm.ACTION_TASK_READY"

public static final String SERVICE_ACTION_INITIALIZE

Action that a GcmTaskService is started with when the service needs to initialize its tasks.

Constant Value: "com.google.android.gms.gcm.SERVICE_ACTION_INITIALIZE"

public static final String SERVICE_PERMISSION

You must protect your service with this permission to avoid being bound to by an application other than Google Play Services.

Constant Value: "com.google.android.gms.permission.BIND_NETWORK_TASK_SERVICE"

Public Constructors

public GcmTaskService ()

Public Methods

public IBinder onBind (Intent intent)

Receives the command to begin doing work, for which it spawns another thread. If you override this, be sure your implementation calls super.onBind(), otherwise your task will not be started correctly.

public void onCreate ()

public void onDestroy ()

public void onInitializeTasks ()

When your package is removed or updated, all of its network tasks are cleared by the GcmNetworkManager. You can override this method to reschedule them in the case of an updated package. This is not called when your application is first installed.

This is called on your application's main thread.

public abstract int onRunTask (TaskParams params)

Override this function to provide the logic for your task execution.

Parameters
params Parameters provided at schedule time with setTag(String)
Returns

public int onStartCommand (Intent intent, int flags, int startId)

Receives the command to begin doing work, for which it spawns another thread. If you override this, be sure your implementation calls super.onStartCommand(), otherwise your task will not be started correctly.