Android APIs
public abstract class

SettingInjectorService

extends Service
java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.location.SettingInjectorService

Class Overview

Dynamically specifies the enabled status of a preference injected into the list of app settings displayed by the system settings app

For use only by apps that are included in the system image, for preferences that affect multiple apps. Location settings that apply only to one app should be shown within that app, rather than in the system settings.

To add a preference to the list, a subclass of SettingInjectorService must be declared in the manifest as so: 

     <service android:name="com.example.android.injector.MyInjectorService" >
         <intent-filter>
             <action android:name="android.location.SettingInjectorService" />
         </intent-filter>

         <meta-data
             android:name="android.location.SettingInjectorService"
             android:resource="@xml/my_injected_location_setting" />
     </service>
The resource file specifies the static data for the setting: 
     <injected-location-setting xmlns:android="http://schemas.android.com/apk/res/android"
         android:title="@string/injected_setting_title"
         android:icon="@drawable/ic_acme_corp"
         android:settingsActivity="com.example.android.injector.MySettingActivity"
     />
Here:
  • title: The getTitle() value. The title should make it clear which apps are affected by the setting, typically by including the name of the developer. For example, "Acme Corp. ads preferences."
  • icon: The getIcon() value. Typically this will be a generic icon for the developer rather than the icon for an individual app.
  • settingsActivity: the activity which is launched to allow the user to modify the setting value. The activity must be in the same package as the subclass of SettingInjectorService. The activity should use your own branding to help emphasize to the user that it is not part of the system settings.
To ensure a good user experience, your onCreate(), and onGetEnabled() methods must all be fast. If either is slow, it can delay the display of settings values for other apps as well. Note further that these methods are called on your app's UI thread.

For compactness, only one copy of a given setting should be injected. If each account has a distinct value for the setting, then only settingsActivity should display the value for each account.

Summary

Constants
String ACTION_INJECTED_SETTING_CHANGED Intent action a client should broadcast when the value of one of its injected settings has changed, so that the setting can be updated in the UI.
String ACTION_SERVICE_INTENT Intent action that must be declared in the manifest for the subclass.
String ATTRIBUTES_NAME Name of the XML tag that includes the attributes for the setting.
String META_DATA_NAME Name of the meta-data tag used to specify the resource file that includes the settings attributes.
[Expand]
Inherited Constants
From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2
Public Constructors
SettingInjectorService(String name)
Constructor.
Public Methods
final IBinder onBind(Intent intent)
Return the communication channel to the service.
final void onStart(Intent intent, int startId)
This method is deprecated. Implement onStartCommand(Intent, int, int) instead.
final int onStartCommand(Intent intent, int flags, int startId)
Called by the system every time a client explicitly starts the service by calling startService(Intent), providing the arguments it supplied and a unique integer token representing the start request.
Protected Methods
abstract boolean onGetEnabled()
Returns the isEnabled() value.
String onGetSummary()
This method is deprecated. not called any more
[Expand]
Inherited Methods
From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks
From interface android.content.ComponentCallbacks2

Constants

public static final String ACTION_INJECTED_SETTING_CHANGED

Added in API level 19

Intent action a client should broadcast when the value of one of its injected settings has changed, so that the setting can be updated in the UI.

Constant Value: "android.location.InjectedSettingChanged"

public static final String ACTION_SERVICE_INTENT

Added in API level 19

Intent action that must be declared in the manifest for the subclass. Used to start the service to read the dynamic status for the setting.

Constant Value: "android.location.SettingInjectorService"

public static final String ATTRIBUTES_NAME

Added in API level 19

Name of the XML tag that includes the attributes for the setting.

Constant Value: "injected-location-setting"

public static final String META_DATA_NAME

Added in API level 19

Name of the meta-data tag used to specify the resource file that includes the settings attributes.

Constant Value: "android.location.SettingInjectorService"

Public Constructors

public SettingInjectorService (String name)

Added in API level 19

Constructor.

Parameters
name used to identify your subclass in log messages

Public Methods

public final IBinder onBind (Intent intent)

Added in API level 19

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Returns
  • Return an IBinder through which clients can call on to the service.

public final void onStart (Intent intent, int startId)

Added in API level 19

This method is deprecated.
Implement onStartCommand(Intent, int, int) instead.

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

Added in API level 19

Called by the system every time a client explicitly starts the service by calling startService(Intent), providing the arguments it supplied and a unique integer token representing the start request. Do not call this method directly.

For backwards compatibility, the default implementation calls onStart(Intent, int) and returns either START_STICKY or START_STICKY_COMPATIBILITY.

If you need your application to run on platform versions prior to API level 5, you can use the following model to handle the older onStart(Intent, int) callback in that case. The handleCommand method is implemented by you as appropriate: 

// This is the old onStart method that will be called on the pre-2.0
// platform.  On 2.0 or later we override onStartCommand() so this
// method will not be called.
@Override
public void onStart(Intent intent, int startId) {
    handleCommand(intent);
}

@Override
public int onStartCommand(Intent intent, int flags, int startId) {
    handleCommand(intent);
    // We want this service to continue running until it is explicitly
    // stopped, so return sticky.
    return START_STICKY;
}

Note that the system calls this on your service's main thread. A service's main thread is the same thread where UI operations take place for Activities running in the same process. You should always avoid stalling the main thread's event loop. When doing long-running operations, network calls, or heavy disk I/O, you should kick off a new thread, or use AsyncTask.

Parameters
intent The Intent supplied to startService(Intent), as given. This may be null if the service is being restarted after its process has gone away, and it had previously returned anything except START_STICKY_COMPATIBILITY.
flags Additional data about this start request. Currently either 0, START_FLAG_REDELIVERY, or START_FLAG_RETRY.
startId A unique integer representing this specific request to start. Use with stopSelfResult(int).
Returns
  • The return value indicates what semantics the system should use for the service's current started state. It may be one of the constants associated with the START_CONTINUATION_MASK bits.

Protected Methods

protected abstract boolean onGetEnabled ()

Added in API level 19

Returns the isEnabled() value. Should not perform unpredictably-long operations such as network access--see the running-time comments in the class-level javadoc.

Note that to prevent churn in the settings list, there is no support for dynamically choosing to hide a setting. Instead you should have this method return false, which will disable the setting and its link to your setting activity. One reason why you might choose to do this is if LOCATION_MODE is LOCATION_MODE_OFF.

It is possible that the user may click on the setting before this method returns, so your settings activity must handle the case where it is invoked even though the setting is disabled. The simplest approach may be to simply call finish() when disabled.

Returns

protected String onGetSummary ()

Added in API level 19

This method is deprecated.
not called any more

This method is no longer called, because status values are no longer shown for any injected setting.

Returns
  • ignored