GcmTaskService

public abstract class GcmTaskService extends Service

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. Specifically you can return RESULT_RESCHEDULE to have this task be re-executed again shortly subject to exponential back-off. Returning RESULT_FAILURE for a periodic task will only affect the executing instance of the task, and future tasks will be executed as normal.

Once a task is running it will not be cancelled, however a newly scheduled task with the same tag will not be executed until the active task has completed. This newly scheduled task will replace the previous task, regardless of whether the previous task returned RESULT_RESCHEDULE.

Bear in mind that your service may receive multiple calls from the scheduler at once (specifically if you've made multiple schedule requests that overlap). If this is the case, your implementation of onRunTask(com.google.android.gms.gcm.TaskParams) must be thread-safe.

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

Your task will run at priority Process.THREAD_PRIORITY_BACKGROUND. If this is not appropriate, you should start your own service with suitably conditioned threads.

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

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.