1 /* 2 * Copyright (C) 2018 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 #pragma once 18 19 #include <android/binder_ibinder.h> 20 #include <android/binder_status.h> 21 #include <android/llndk-versioning.h> 22 #include <sys/cdefs.h> 23 24 __BEGIN_DECLS 25 26 enum AServiceManager_AddServiceFlag : uint32_t { 27 /** 28 * This allows processes with AID_ISOLATED to get the binder of the service added. 29 * 30 * Services with methods that perform file IO, web socket creation or ways to egress data must 31 * not be added with this flag for privacy concerns. 32 */ 33 ADD_SERVICE_ALLOW_ISOLATED = 1 << 0, 34 ADD_SERVICE_DUMP_FLAG_PRIORITY_CRITICAL = 1 << 1, 35 ADD_SERVICE_DUMP_FLAG_PRIORITY_HIGH = 1 << 2, 36 ADD_SERVICE_DUMP_FLAG_PRIORITY_NORMAL = 1 << 3, 37 ADD_SERVICE_DUMP_FLAG_PRIORITY_DEFAULT = 1 << 4, 38 }; 39 40 /** 41 * This registers the service with the default service manager under this instance name. This does 42 * not take ownership of binder. 43 * 44 * WARNING: when using this API across an APEX boundary, do not use with unstable 45 * AIDL services. TODO(b/139325195) 46 * 47 * \param binder object to register globally with the service manager. 48 * \param instance identifier of the service. This will be used to lookup the service. 49 * 50 * \return EX_NONE on success. 51 */ 52 __attribute__((warn_unused_result)) binder_exception_t AServiceManager_addService( 53 AIBinder* binder, const char* instance) __INTRODUCED_IN(29); 54 55 /** 56 * This registers the service with the default service manager under this instance name. This does 57 * not take ownership of binder. 58 * 59 * WARNING: when using this API across an APEX boundary, do not use with unstable 60 * AIDL services. TODO(b/139325195) 61 * 62 * \param binder object to register globally with the service manager. 63 * \param instance identifier of the service. This will be used to lookup the service. 64 * \param flags an AServiceManager_AddServiceFlag enum to denote how the service should be added. 65 * 66 * \return EX_NONE on success. 67 */ 68 __attribute__((warn_unused_result)) binder_exception_t AServiceManager_addServiceWithFlags( 69 AIBinder* binder, const char* instance, const AServiceManager_AddServiceFlag flags) 70 __INTRODUCED_IN(34); 71 72 /** 73 * Gets a binder object with this specific instance name. Will return nullptr immediately if the 74 * service is not available This also implicitly calls AIBinder_incStrong (so the caller of this 75 * function is responsible for calling AIBinder_decStrong). 76 * 77 * WARNING: when using this API across an APEX boundary, do not use with unstable 78 * AIDL services. TODO(b/139325195) 79 * 80 * \param instance identifier of the service used to lookup the service. 81 */ 82 __attribute__((warn_unused_result)) AIBinder* AServiceManager_checkService(const char* instance) 83 __INTRODUCED_IN(29); 84 85 /** 86 * Gets a binder object with this specific instance name. Blocks for a couple of seconds waiting on 87 * it. This also implicitly calls AIBinder_incStrong (so the caller of this function is responsible 88 * for calling AIBinder_decStrong). This does polling. A more efficient way to make sure you 89 * unblock as soon as the service is available is to use AIBinder_waitForService. 90 * 91 * WARNING: when using this API across an APEX boundary, do not use with unstable 92 * AIDL services. TODO(b/139325195) 93 * 94 * WARNING: when using this API, typically, you should call it in a loop. It's dangerous to 95 * assume that nullptr could mean that the service is not available. The service could just 96 * be starting. Generally, whether a service exists, this information should be declared 97 * externally (for instance, an Android feature might imply the existence of a service, 98 * a system property, or in the case of services in the VINTF manifest, it can be checked 99 * with AServiceManager_isDeclared). 100 * 101 * \param instance identifier of the service used to lookup the service. 102 */ 103 [[deprecated("this polls 5s, use AServiceManager_waitForService or AServiceManager_checkService")]] 104 __attribute__((warn_unused_result)) AIBinder* AServiceManager_getService(const char* instance) 105 __INTRODUCED_IN(29); 106 107 /** 108 * Registers a lazy service with the default service manager under the 'instance' name. 109 * Does not take ownership of binder. 110 * The service must be configured statically with init so it can be restarted with 111 * ctl.interface.* messages from servicemanager. 112 * AServiceManager_registerLazyService cannot safely be used with AServiceManager_addService 113 * in the same process. If one service is registered with AServiceManager_registerLazyService, 114 * the entire process will have its lifetime controlled by servicemanager. 115 * Instead, all services in the process should be registered using 116 * AServiceManager_registerLazyService. 117 * 118 * \param binder object to register globally with the service manager. 119 * \param instance identifier of the service. This will be used to lookup the service. 120 * 121 * \return STATUS_OK on success. 122 */ 123 binder_status_t AServiceManager_registerLazyService(AIBinder* binder, const char* instance) 124 __INTRODUCED_IN(31); 125 126 /** 127 * Gets a binder object with this specific instance name. Efficiently waits for the service. 128 * If the service is not ever registered, it will wait indefinitely. Requires the threadpool 129 * to be started in the service. 130 * This also implicitly calls AIBinder_incStrong (so the caller of this function is responsible 131 * for calling AIBinder_decStrong). 132 * 133 * WARNING: when using this API across an APEX boundary, do not use with unstable 134 * AIDL services. TODO(b/139325195) 135 * 136 * \param instance identifier of the service used to lookup the service. 137 * 138 * \return service if registered, null if not. 139 */ 140 __attribute__((warn_unused_result)) AIBinder* AServiceManager_waitForService(const char* instance) 141 __INTRODUCED_IN(31); 142 143 /** 144 * Function to call when a service is registered. The instance is passed as well as 145 * ownership of the binder named 'registered'. 146 * 147 * WARNING: a lock is held when this method is called in order to prevent races with 148 * AServiceManager_NotificationRegistration_delete. Do not make synchronous binder calls when 149 * implementing this method to avoid deadlocks. 150 * 151 * \param instance instance name of service registered 152 * \param registered ownership-passed instance of service registered 153 * \param cookie data passed during registration for notifications 154 */ 155 typedef void (*AServiceManager_onRegister)(const char* instance, AIBinder* registered, 156 void* cookie); 157 158 /** 159 * Represents a registration to servicemanager which can be cleared anytime. 160 */ 161 struct AServiceManager_NotificationRegistration; 162 163 /** 164 * Get notifications when a service is registered. If the service is already registered, 165 * you will immediately get a notification. 166 * 167 * WARNING: it is strongly recommended to use AServiceManager_waitForService API instead. 168 * That API will wait synchronously, which is what you usually want in cases, including 169 * using some feature or during boot up. There is a history of bugs where waiting for 170 * notifications like this races with service startup. Also, when this API is used, a service 171 * bug will result in silent failure (rather than a debuggable deadlock). Furthermore, there 172 * is a history of this API being used to know when a service is up as a proxy for whethre 173 * that service should be started. This should only be used if you are intending to get 174 * ahold of the service as a client. For lazy services, whether a service is registered 175 * should not be used as a proxy for when it should be registered, which is only known 176 * by the real client. 177 * 178 * WARNING: if you use this API, you must also ensure that you check missing services are 179 * started and crash otherwise. If service failures are ignored, the system rots. 180 * 181 * \param instance name of service to wait for notifications about 182 * \param onRegister callback for when service is registered 183 * \param cookie data associated with this callback 184 * 185 * \return the token for this registration. Deleting this token will unregister. 186 */ 187 __attribute__((warn_unused_result)) AServiceManager_NotificationRegistration* 188 AServiceManager_registerForServiceNotifications(const char* instance, 189 AServiceManager_onRegister onRegister, void* cookie) 190 __INTRODUCED_IN(34); 191 192 /** 193 * Unregister for notifications and delete the object. 194 * 195 * After this method is called, the callback is guaranteed to no longer be invoked. This will block 196 * until any in-progress onRegister callbacks have completed. It is therefore safe to immediately 197 * destroy the void* cookie that was registered when this method returns. 198 * 199 * \param notification object to dismiss 200 */ 201 void AServiceManager_NotificationRegistration_delete( 202 AServiceManager_NotificationRegistration* notification) __INTRODUCED_IN(34); 203 204 /** 205 * Check if a service is declared (e.g. VINTF manifest). 206 * 207 * \param instance identifier of the service. 208 * 209 * \return true on success, meaning AServiceManager_waitForService should always 210 * be able to return the service. 211 */ 212 bool AServiceManager_isDeclared(const char* instance) __INTRODUCED_IN(31); 213 214 /** 215 * Returns all declared instances for a particular interface. 216 * 217 * For instance, if 'android.foo.IFoo/foo' is declared, and 'android.foo.IFoo' is 218 * passed here, then ["foo"] would be returned. 219 * 220 * See also AServiceManager_isDeclared. 221 * 222 * \param interface interface, e.g. 'android.foo.IFoo' 223 * \param context to pass to callback 224 * \param callback taking instance (e.g. 'foo') and context 225 */ 226 void AServiceManager_forEachDeclaredInstance(const char* interface, void* context, 227 void (*callback)(const char*, void*)) 228 __INTRODUCED_IN(31); 229 230 /** 231 * Check if a service is updatable via an APEX module. 232 * 233 * \param instance identifier of the service 234 * 235 * \return whether the interface is updatable via APEX 236 */ 237 bool AServiceManager_isUpdatableViaApex(const char* instance) __INTRODUCED_IN(31); 238 239 /** 240 * Returns the APEX name if a service is declared as updatable via an APEX module. 241 * 242 * \param instance identifier of the service 243 * \param context to pass to callback 244 * \param callback taking the APEX name (e.g. 'com.android.foo') and context 245 */ 246 void AServiceManager_getUpdatableApexName(const char* instance, void* context, 247 void (*callback)(const char*, void*)) 248 __INTRODUCED_IN(__ANDROID_API_U__); 249 250 /** 251 * Opens a declared passthrough HAL. 252 * 253 * \param instance identifier of the passthrough service (e.g. "mapper") 254 * \param instance identifier of the implemenatation (e.g. "default") 255 * \param flag passed to dlopen() 256 * 257 * \return the result of dlopen of the specified HAL 258 */ 259 void* AServiceManager_openDeclaredPassthroughHal(const char* interface, const char* instance, 260 int flag) __INTRODUCED_IN(__ANDROID_API_V__) 261 __INTRODUCED_IN_LLNDK(202404); 262 263 /** 264 * Prevent lazy services without client from shutting down their process 265 * 266 * This should only be used if it is every eventually set to false. If a 267 * service needs to persist but doesn't need to dynamically shut down, 268 * prefer to control it with another mechanism. 269 * 270 * \param persist 'true' if the process should not exit. 271 */ 272 void AServiceManager_forceLazyServicesPersist(bool persist) __INTRODUCED_IN(31); 273 274 /** 275 * Set a callback that is invoked when the active service count (i.e. services with clients) 276 * registered with this process drops to zero (or becomes nonzero). 277 * The callback takes a boolean argument, which is 'true' if there is 278 * at least one service with clients. 279 * 280 * \param callback function to call when the number of services 281 * with clients changes. 282 * \param context opaque pointer passed back as second parameter to the 283 * callback. 284 * 285 * The callback takes two arguments. The first is a boolean that represents if there are 286 * services with clients (true) or not (false). 287 * The second is the 'context' pointer passed during the registration. 288 * 289 * Callback return value: 290 * - false: Default behavior for lazy services (shut down the process if there 291 * are no clients). 292 * - true: Don't shut down the process even if there are no clients. 293 * 294 * This callback gives a chance to: 295 * 1 - Perform some additional operations before exiting; 296 * 2 - Prevent the process from exiting by returning "true" from the callback. 297 */ 298 void AServiceManager_setActiveServicesCallback(bool (*callback)(bool, void*), void* context) 299 __INTRODUCED_IN(31); 300 301 /** 302 * Try to unregister all services previously registered with 'registerService'. 303 * 304 * \return true on success. 305 */ 306 bool AServiceManager_tryUnregister() __INTRODUCED_IN(31); 307 308 /** 309 * Re-register services that were unregistered by 'tryUnregister'. 310 * This method should be called in the case 'tryUnregister' fails 311 * (and should be called on the same thread). 312 */ 313 void AServiceManager_reRegister() __INTRODUCED_IN(31); 314 315 __END_DECLS 316