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 <sys/cdefs.h> 22 23 __BEGIN_DECLS 24 25 /** 26 * This registers the service with the default service manager under this instance name. This does 27 * not take ownership of binder. 28 * 29 * WARNING: when using this API across an APEX boundary, do not use with unstable 30 * AIDL services. TODO(b/139325195) 31 * 32 * \param binder object to register globally with the service manager. 33 * \param instance identifier of the service. This will be used to lookup the service. 34 * 35 * \return EX_NONE on success. 36 */ 37 __attribute__((warn_unused_result)) binder_exception_t AServiceManager_addService( 38 AIBinder* binder, const char* instance) __INTRODUCED_IN(29); 39 40 /** 41 * Gets a binder object with this specific instance name. Will return nullptr immediately if the 42 * service is not available This also implicitly calls AIBinder_incStrong (so the caller of this 43 * function is responsible for calling AIBinder_decStrong). 44 * 45 * WARNING: when using this API across an APEX boundary, do not use with unstable 46 * AIDL services. TODO(b/139325195) 47 * 48 * \param instance identifier of the service used to lookup the service. 49 */ 50 __attribute__((warn_unused_result)) AIBinder* AServiceManager_checkService(const char* instance) 51 __INTRODUCED_IN(29); 52 53 /** 54 * Gets a binder object with this specific instance name. Blocks for a couple of seconds waiting on 55 * it. This also implicitly calls AIBinder_incStrong (so the caller of this function is responsible 56 * for calling AIBinder_decStrong). This does polling. A more efficient way to make sure you 57 * unblock as soon as the service is available is to use AIBinder_waitForService. 58 * 59 * WARNING: when using this API across an APEX boundary, do not use with unstable 60 * AIDL services. TODO(b/139325195) 61 * 62 * WARNING: when using this API, typically, you should call it in a loop. It's dangerous to 63 * assume that nullptr could mean that the service is not available. The service could just 64 * be starting. Generally, whether a service exists, this information should be declared 65 * externally (for instance, an Android feature might imply the existence of a service, 66 * a system property, or in the case of services in the VINTF manifest, it can be checked 67 * with AServiceManager_isDeclared). 68 * 69 * \param instance identifier of the service used to lookup the service. 70 */ 71 __attribute__((warn_unused_result)) AIBinder* AServiceManager_getService(const char* instance) 72 __INTRODUCED_IN(29); 73 74 /** 75 * Registers a lazy service with the default service manager under the 'instance' name. 76 * Does not take ownership of binder. 77 * The service must be configured statically with init so it can be restarted with 78 * ctl.interface.* messages from servicemanager. 79 * AServiceManager_registerLazyService cannot safely be used with AServiceManager_addService 80 * in the same process. If one service is registered with AServiceManager_registerLazyService, 81 * the entire process will have its lifetime controlled by servicemanager. 82 * Instead, all services in the process should be registered using 83 * AServiceManager_registerLazyService. 84 * 85 * \param binder object to register globally with the service manager. 86 * \param instance identifier of the service. This will be used to lookup the service. 87 * 88 * \return STATUS_OK on success. 89 */ 90 binder_status_t AServiceManager_registerLazyService(AIBinder* binder, const char* instance) 91 __INTRODUCED_IN(31); 92 93 /** 94 * Gets a binder object with this specific instance name. Efficiently waits for the service. 95 * If the service is not declared, it will wait indefinitely. Requires the threadpool 96 * to be started in the service. 97 * This also implicitly calls AIBinder_incStrong (so the caller of this function is responsible 98 * for calling AIBinder_decStrong). 99 * 100 * WARNING: when using this API across an APEX boundary, do not use with unstable 101 * AIDL services. TODO(b/139325195) 102 * 103 * \param instance identifier of the service used to lookup the service. 104 * 105 * \return service if registered, null if not. 106 */ 107 __attribute__((warn_unused_result)) AIBinder* AServiceManager_waitForService(const char* instance) 108 __INTRODUCED_IN(31); 109 110 /** 111 * Check if a service is declared (e.g. VINTF manifest). 112 * 113 * \param instance identifier of the service. 114 * 115 * \return true on success, meaning AServiceManager_waitForService should always 116 * be able to return the service. 117 */ 118 bool AServiceManager_isDeclared(const char* instance) __INTRODUCED_IN(31); 119 120 /** 121 * Returns all declared instances for a particular interface. 122 * 123 * For instance, if 'android.foo.IFoo/foo' is declared, and 'android.foo.IFoo' is 124 * passed here, then ["foo"] would be returned. 125 * 126 * See also AServiceManager_isDeclared. 127 * 128 * \param interface interface, e.g. 'android.foo.IFoo' 129 * \param context to pass to callback 130 * \param callback taking instance (e.g. 'foo') and context 131 */ 132 void AServiceManager_forEachDeclaredInstance(const char* interface, void* context, 133 void (*callback)(const char*, void*)) 134 __INTRODUCED_IN(31); 135 136 /** 137 * Check if a service is updatable via an APEX module. 138 * 139 * \param instance identifier of the service 140 * 141 * \return whether the interface is updatable via APEX 142 */ 143 bool AServiceManager_isUpdatableViaApex(const char* instance) __INTRODUCED_IN(31); 144 145 /** 146 * Prevent lazy services without client from shutting down their process 147 * 148 * This should only be used if it is every eventually set to false. If a 149 * service needs to persist but doesn't need to dynamically shut down, 150 * prefer to control it with another mechanism. 151 * 152 * \param persist 'true' if the process should not exit. 153 */ 154 void AServiceManager_forceLazyServicesPersist(bool persist) __INTRODUCED_IN(31); 155 156 /** 157 * Set a callback that is invoked when the active service count (i.e. services with clients) 158 * registered with this process drops to zero (or becomes nonzero). 159 * The callback takes a boolean argument, which is 'true' if there is 160 * at least one service with clients. 161 * 162 * \param callback function to call when the number of services 163 * with clients changes. 164 * \param context opaque pointer passed back as second parameter to the 165 * callback. 166 * 167 * The callback takes two arguments. The first is a boolean that represents if there are 168 * services with clients (true) or not (false). 169 * The second is the 'context' pointer passed during the registration. 170 * 171 * Callback return value: 172 * - false: Default behavior for lazy services (shut down the process if there 173 * are no clients). 174 * - true: Don't shut down the process even if there are no clients. 175 * 176 * This callback gives a chance to: 177 * 1 - Perform some additional operations before exiting; 178 * 2 - Prevent the process from exiting by returning "true" from the callback. 179 */ 180 void AServiceManager_setActiveServicesCallback(bool (*callback)(bool, void*), void* context) 181 __INTRODUCED_IN(31); 182 183 /** 184 * Try to unregister all services previously registered with 'registerService'. 185 * 186 * \return true on success. 187 */ 188 bool AServiceManager_tryUnregister() __INTRODUCED_IN(31); 189 190 /** 191 * Re-register services that were unregistered by 'tryUnregister'. 192 * This method should be called in the case 'tryUnregister' fails 193 * (and should be called on the same thread). 194 */ 195 void AServiceManager_reRegister() __INTRODUCED_IN(31); 196 197 __END_DECLS 198