1 /* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.server; 18 19 import static android.os.IServiceManager.DUMP_FLAG_PRIORITY_DEFAULT; 20 21 import android.app.ActivityThread; 22 import android.content.Context; 23 import android.os.IBinder; 24 import android.os.ServiceManager; 25 import android.os.UserManager; 26 27 /** 28 * The base class for services running in the system process. Override and implement 29 * the lifecycle event callback methods as needed. 30 * <p> 31 * The lifecycle of a SystemService: 32 * </p><ul> 33 * <li>The constructor is called and provided with the system {@link Context} 34 * to initialize the system service. 35 * <li>{@link #onStart()} is called to get the service running. The service should 36 * publish its binder interface at this point using 37 * {@link #publishBinderService(String, IBinder)}. It may also publish additional 38 * local interfaces that other services within the system server may use to access 39 * privileged internal functions. 40 * <li>Then {@link #onBootPhase(int)} is called as many times as there are boot phases 41 * until {@link #PHASE_BOOT_COMPLETED} is sent, which is the last boot phase. Each phase 42 * is an opportunity to do special work, like acquiring optional service dependencies, 43 * waiting to see if SafeMode is enabled, or registering with a service that gets 44 * started after this one. 45 * </ul><p> 46 * NOTE: All lifecycle methods are called from the system server's main looper thread. 47 * </p> 48 * 49 * {@hide} 50 */ 51 public abstract class SystemService { 52 /* 53 * Boot Phases 54 */ 55 public static final int PHASE_WAIT_FOR_DEFAULT_DISPLAY = 100; // maybe should be a dependency? 56 57 /** 58 * After receiving this boot phase, services can obtain lock settings data. 59 */ 60 public static final int PHASE_LOCK_SETTINGS_READY = 480; 61 62 /** 63 * After receiving this boot phase, services can safely call into core system services 64 * such as the PowerManager or PackageManager. 65 */ 66 public static final int PHASE_SYSTEM_SERVICES_READY = 500; 67 68 /** 69 * After receiving this boot phase, services can safely call into device specific services. 70 */ 71 public static final int PHASE_DEVICE_SPECIFIC_SERVICES_READY = 520; 72 73 /** 74 * After receiving this boot phase, services can broadcast Intents. 75 */ 76 public static final int PHASE_ACTIVITY_MANAGER_READY = 550; 77 78 /** 79 * After receiving this boot phase, services can start/bind to third party apps. 80 * Apps will be able to make Binder calls into services at this point. 81 */ 82 public static final int PHASE_THIRD_PARTY_APPS_CAN_START = 600; 83 84 /** 85 * After receiving this boot phase, services can allow user interaction with the device. 86 * This phase occurs when boot has completed and the home application has started. 87 * System services may prefer to listen to this phase rather than registering a 88 * broadcast receiver for ACTION_BOOT_COMPLETED to reduce overall latency. 89 */ 90 public static final int PHASE_BOOT_COMPLETED = 1000; 91 92 private final Context mContext; 93 94 /** 95 * Initializes the system service. 96 * <p> 97 * Subclasses must define a single argument constructor that accepts the context 98 * and passes it to super. 99 * </p> 100 * 101 * @param context The system server context. 102 */ 103 public SystemService(Context context) { 104 mContext = context; 105 } 106 107 /** 108 * Gets the system context. 109 */ 110 public final Context getContext() { 111 return mContext; 112 } 113 114 /** 115 * Get the system UI context. This context is to be used for displaying UI. It is themable, 116 * which means resources can be overridden at runtime. Do not use to retrieve properties that 117 * configure the behavior of the device that is not UX related. 118 */ 119 public final Context getUiContext() { 120 // This has already been set up by the time any SystemServices are created. 121 return ActivityThread.currentActivityThread().getSystemUiContext(); 122 } 123 124 /** 125 * Returns true if the system is running in safe mode. 126 * TODO: we should define in which phase this becomes valid 127 */ 128 public final boolean isSafeMode() { 129 return getManager().isSafeMode(); 130 } 131 132 /** 133 * Called when the dependencies listed in the @Service class-annotation are available 134 * and after the chosen start phase. 135 * When this method returns, the service should be published. 136 */ 137 public abstract void onStart(); 138 139 /** 140 * Called on each phase of the boot process. Phases before the service's start phase 141 * (as defined in the @Service annotation) are never received. 142 * 143 * @param phase The current boot phase. 144 */ 145 public void onBootPhase(int phase) {} 146 147 /** 148 * Called when a new user is starting, for system services to initialize any per-user 149 * state they maintain for running users. 150 * @param userHandle The identifier of the user. 151 */ 152 public void onStartUser(int userHandle) {} 153 154 /** 155 * Called when an existing user is in the process of being unlocked. This 156 * means the credential-encrypted storage for that user is now available, 157 * and encryption-aware component filtering is no longer in effect. 158 * <p> 159 * While dispatching this event to services, the user is in the 160 * {@code STATE_RUNNING_UNLOCKING} state, and once dispatching is finished 161 * the user will transition into the {@code STATE_RUNNING_UNLOCKED} state. 162 * Code written inside system services should use 163 * {@link UserManager#isUserUnlockingOrUnlocked(int)} to handle both of 164 * these states. 165 * 166 * @param userHandle The identifier of the user. 167 */ 168 public void onUnlockUser(int userHandle) {} 169 170 /** 171 * Called when switching to a different foreground user, for system services that have 172 * special behavior for whichever user is currently in the foreground. This is called 173 * before any application processes are aware of the new user. 174 * @param userHandle The identifier of the user. 175 */ 176 public void onSwitchUser(int userHandle) {} 177 178 /** 179 * Called when an existing user is stopping, for system services to finalize any per-user 180 * state they maintain for running users. This is called prior to sending the SHUTDOWN 181 * broadcast to the user; it is a good place to stop making use of any resources of that 182 * user (such as binding to a service running in the user). 183 * 184 * <p>NOTE: This is the last callback where the callee may access the target user's CE storage. 185 * 186 * @param userHandle The identifier of the user. 187 */ 188 public void onStopUser(int userHandle) {} 189 190 /** 191 * Called when an existing user is stopping, for system services to finalize any per-user 192 * state they maintain for running users. This is called after all application process 193 * teardown of the user is complete. 194 * 195 * <p>NOTE: When this callback is called, the CE storage for the target user may not be 196 * accessible already. Use {@link #onStopUser} instead if you need to access the CE storage. 197 * 198 * @param userHandle The identifier of the user. 199 */ 200 public void onCleanupUser(int userHandle) {} 201 202 /** 203 * Publish the service so it is accessible to other services and apps. 204 * 205 * @param name the name of the new service 206 * @param service the service object 207 */ 208 protected final void publishBinderService(String name, IBinder service) { 209 publishBinderService(name, service, false); 210 } 211 212 /** 213 * Publish the service so it is accessible to other services and apps. 214 * 215 * @param name the name of the new service 216 * @param service the service object 217 * @param allowIsolated set to true to allow isolated sandboxed processes 218 * to access this service 219 */ 220 protected final void publishBinderService(String name, IBinder service, 221 boolean allowIsolated) { 222 publishBinderService(name, service, allowIsolated, DUMP_FLAG_PRIORITY_DEFAULT); 223 } 224 225 /** 226 * Publish the service so it is accessible to other services and apps. 227 * 228 * @param name the name of the new service 229 * @param service the service object 230 * @param allowIsolated set to true to allow isolated sandboxed processes 231 * to access this service 232 * @param dumpPriority supported dump priority levels as a bitmask 233 */ 234 protected final void publishBinderService(String name, IBinder service, 235 boolean allowIsolated, int dumpPriority) { 236 ServiceManager.addService(name, service, allowIsolated, dumpPriority); 237 } 238 239 /** 240 * Get a binder service by its name. 241 */ 242 protected final IBinder getBinderService(String name) { 243 return ServiceManager.getService(name); 244 } 245 246 /** 247 * Publish the service so it is only accessible to the system process. 248 */ 249 protected final <T> void publishLocalService(Class<T> type, T service) { 250 LocalServices.addService(type, service); 251 } 252 253 /** 254 * Get a local service by interface. 255 */ 256 protected final <T> T getLocalService(Class<T> type) { 257 return LocalServices.getService(type); 258 } 259 260 private SystemServiceManager getManager() { 261 return LocalServices.getService(SystemServiceManager.class); 262 } 263 } 264
