1 /* 2 * Copyright (C) 2024 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 <sys/socket.h> 21 22 __BEGIN_DECLS 23 24 /** 25 * @defgroup ABinderRpc Binder RPC 26 * 27 * This set of APIs makes it possible for a process to use the AServiceManager 28 * APIs to get binder objects for services that are available over sockets 29 * instead of the traditional kernel binder with the extra ServiceManager 30 * process. 31 * 32 * These APIs are used to supply libbinder with enough information to create 33 * and manage the socket connections underneath the ServiceManager APIs so the 34 * clients do not need to know the service implementation details or what 35 * transport they use for communication. 36 * 37 * @{ 38 */ 39 40 /** 41 * This represents an IAccessor implementation from libbinder that is 42 * responsible for providing a pre-connected socket file descriptor for a 43 * specific service. The service is an RpcServer and the pre-connected socket is 44 * used to set up a client RpcSession underneath libbinder's IServiceManager APIs 45 * to provide the client with the service's binder for remote communication. 46 */ 47 typedef struct ABinderRpc_Accessor ABinderRpc_Accessor; 48 49 /** 50 * This represents an object that supplies ABinderRpc_Accessors to libbinder 51 * when they are requested. They are requested any time a client is attempting 52 * to get a service through IServiceManager APIs when the services aren't known by 53 * servicemanager. 54 */ 55 typedef struct ABinderRpc_AccessorProvider ABinderRpc_AccessorProvider; 56 57 /** 58 * This represents information necessary for libbinder to be able to connect to a 59 * remote service. 60 * It supports connecting to linux sockets and is created using sockaddr 61 * types for sockets supported by libbinder like sockaddr_in, sockaddr_un, 62 * sockaddr_vm. 63 */ 64 typedef struct ABinderRpc_ConnectionInfo ABinderRpc_ConnectionInfo; 65 66 /** 67 * These APIs provide a way for clients of binder services to be able to get a 68 * binder object of that service through the existing libbinder/libbinder_ndk 69 * Service Manager APIs when that service is using RPC Binder over sockets 70 * instead kernel binder. 71 * 72 * Some of these APIs are used on Android hosts when kernel binder is supported 73 * and the usual servicemanager process is available. Some of these APIs are 74 * only required when there is no kernel binder or extra servicemanager process 75 * such as the case of microdroid or similar VMs. 76 */ 77 78 /** 79 * This callback is responsible for returning ABinderRpc_Accessor objects for a given 80 * service instance. These ABinderRpc_Accessor objects are implemented by 81 * libbinder_ndk and backed by implementations of android::os::IAccessor in 82 * libbinder. 83 * 84 * \param instance name of the service like 85 * `android.hardware.vibrator.IVibrator/default`. This string must remain 86 * valid and unchanged for the duration of this function call. 87 * \param data the data that was associated with this instance when the callback 88 * was registered. 89 * \return The ABinderRpc_Accessor associated with the service `instance`. This 90 * callback gives up ownership of the object once it returns it. The 91 * caller of this callback (libbinder_ndk) is responsible for deleting it 92 * with ABinderRpc_Accessor_delete. 93 */ 94 typedef ABinderRpc_Accessor* _Nullable (*ABinderRpc_AccessorProvider_getAccessorCallback)( 95 const char* _Nonnull instance, void* _Nullable data); 96 97 /** 98 * This callback is responsible deleting the `void* data` object that is passed 99 * in to ABinderRpc_registerAccessorProvider for the ABinderRpc_AccessorProvider_getAccessorCallback 100 * to use. That object is owned by the ABinderRpc_AccessorProvider and must remain valid for the 101 * lifetime of the callback because it may be called and use the object. 102 * This _delete callback is called after the ABinderRpc_AccessorProvider is remove and 103 * is guaranteed never to be called again. 104 * 105 * \param data a pointer to data that the ABinderRpc_AccessorProvider_getAccessorCallback uses which 106 * is to be deleted by this call. 107 */ 108 typedef void (*ABinderRpc_AccessorProviderUserData_deleteCallback)(void* _Nullable data); 109 110 /** 111 * Inject an ABinderRpc_AccessorProvider_getAccessorCallback into the process for 112 * the Service Manager APIs to use to retrieve ABinderRpc_Accessor objects associated 113 * with different RPC Binder services. 114 * 115 * \param provider callback that returns ABinderRpc_Accessors for libbinder to set up 116 * RPC clients with. 117 * \param instances array of instances that are supported by this provider. It 118 * will only be called if the client is looking for an instance that is 119 * in this list. These instances must be unique per-process. If an 120 * instance is being registered that was previously registered, this call 121 * will fail and the ABinderRpc_AccessorProviderUserData_deleteCallback 122 * will be called to clean up the data. 123 * This array of strings must remain valid and unchanged for the duration 124 * of this function call. 125 * \param number of instances in the instances array. 126 * \param data pointer that is passed to the ABinderRpc_AccessorProvider callback. 127 * IMPORTANT: The ABinderRpc_AccessorProvider now OWNS that object that data 128 * points to. It can be used as necessary in the callback. The data MUST 129 * remain valid for the lifetime of the provider callback. 130 * Do not attempt to give ownership of the same object to different 131 * providers through multiple calls to this function because the first 132 * one to be deleted will call the onDelete callback. 133 * \param onDelete callback used to delete the objects that `data` points to. 134 * This is called after ABinderRpc_AccessorProvider is guaranteed to never be 135 * called again. Before this callback is called, `data` must remain 136 * valid. 137 * \return nullptr on error if the data pointer is non-null and the onDelete 138 * callback is null or if an instance in the instances list was previously 139 * registered. In the error case of duplicate instances, if data was 140 * provided with a ABinderRpc_AccessorProviderUserData_deleteCallback, 141 * the callback will be called to delete the data. 142 * If nullptr is returned, ABinderRpc_AccessorProviderUserData_deleteCallback 143 * will be called on data immediately. 144 * Otherwise returns a pointer to the ABinderRpc_AccessorProvider that 145 * can be used to remove with ABinderRpc_unregisterAccessorProvider. 146 */ 147 ABinderRpc_AccessorProvider* _Nullable ABinderRpc_registerAccessorProvider( 148 ABinderRpc_AccessorProvider_getAccessorCallback _Nonnull provider, 149 const char* _Nullable const* const _Nonnull instances, size_t numInstances, 150 void* _Nullable data, ABinderRpc_AccessorProviderUserData_deleteCallback _Nullable onDelete) 151 __INTRODUCED_IN(36); 152 153 /** 154 * Remove an ABinderRpc_AccessorProvider from libbinder. This will remove references 155 * from the ABinderRpc_AccessorProvider and will no longer call the 156 * ABinderRpc_AccessorProvider_getAccessorCallback. 157 * 158 * Note: The `data` object that was used when adding the accessor will be 159 * deleted by the ABinderRpc_AccessorProviderUserData_deleteCallback at some 160 * point after this call. Do not use the object and do not try to delete 161 * it through any other means. 162 * Note: This will abort when used incorrectly if this provider was never 163 * registered or if it were already unregistered. 164 * 165 * \param provider to be removed and deleted 166 * 167 */ 168 void ABinderRpc_unregisterAccessorProvider(ABinderRpc_AccessorProvider* _Nonnull provider) 169 __INTRODUCED_IN(36); 170 171 /** 172 * Callback which returns the RPC connection information for libbinder to use to 173 * connect to a socket that a given service is listening on. This is needed to 174 * create an ABinderRpc_Accessor so it can connect to these services. 175 * 176 * \param instance name of the service to connect to. This string must remain 177 * valid and unchanged for the duration of this function call. 178 * \param data user data for this callback. The pointer is provided in 179 * ABinderRpc_Accessor_new. 180 * \return ABinderRpc_ConnectionInfo with socket connection information for `instance` 181 */ 182 typedef ABinderRpc_ConnectionInfo* _Nullable (*ABinderRpc_ConnectionInfoProvider)( 183 const char* _Nonnull instance, void* _Nullable data) __INTRODUCED_IN(36); 184 /** 185 * This callback is responsible deleting the `void* data` object that is passed 186 * in to ABinderRpc_Accessor_new for the ABinderRpc_ConnectionInfoProvider to use. That 187 * object is owned by the ABinderRpc_Accessor and must remain valid for the 188 * lifetime the Accessor because it may be used by the connection info provider 189 * callback. 190 * This _delete callback is called after the ABinderRpc_Accessor is removed and 191 * is guaranteed never to be called again. 192 * 193 * \param data a pointer to data that the ABinderRpc_AccessorProvider uses which is to 194 * be deleted by this call. 195 */ 196 typedef void (*ABinderRpc_ConnectionInfoProviderUserData_delete)(void* _Nullable data); 197 198 /** 199 * Create a new ABinderRpc_Accessor. This creates an IAccessor object in libbinder 200 * that can use the info from the ABinderRpc_ConnectionInfoProvider to connect to a 201 * socket that the service with `instance` name is listening to. 202 * 203 * \param instance name of the service that is listening on the socket. This 204 * string must remain valid and unchanged for the duration of this 205 * function call. 206 * \param provider callback that can get the socket connection information for the 207 * instance. This connection information may be dynamic, so the 208 * provider will be called any time a new connection is required. 209 * \param data pointer that is passed to the ABinderRpc_ConnectionInfoProvider callback. 210 * IMPORTANT: The ABinderRpc_ConnectionInfoProvider now OWNS that object that data 211 * points to. It can be used as necessary in the callback. The data MUST 212 * remain valid for the lifetime of the provider callback. 213 * Do not attempt to give ownership of the same object to different 214 * providers through multiple calls to this function because the first 215 * one to be deleted will call the onDelete callback. 216 * \param onDelete callback used to delete the objects that `data` points to. 217 * This is called after ABinderRpc_ConnectionInfoProvider is guaranteed to never be 218 * called again. Before this callback is called, `data` must remain 219 * valid. 220 * \return an ABinderRpc_Accessor instance. This is deleted by the caller once it is 221 * no longer needed. 222 */ 223 ABinderRpc_Accessor* _Nullable ABinderRpc_Accessor_new( 224 const char* _Nonnull instance, ABinderRpc_ConnectionInfoProvider _Nonnull provider, 225 void* _Nullable data, ABinderRpc_ConnectionInfoProviderUserData_delete _Nullable onDelete) 226 __INTRODUCED_IN(36); 227 228 /** 229 * Delete an ABinderRpc_Accessor 230 * 231 * \param accessor to delete 232 */ 233 void ABinderRpc_Accessor_delete(ABinderRpc_Accessor* _Nonnull accessor) __INTRODUCED_IN(36); 234 235 /** 236 * Return the AIBinder associated with an ABinderRpc_Accessor. This can be used to 237 * send the Accessor to another process or even register it with servicemanager. 238 * 239 * \param accessor to get the AIBinder for 240 * \return binder of the supplied accessor with one strong ref count 241 */ 242 AIBinder* _Nullable ABinderRpc_Accessor_asBinder(ABinderRpc_Accessor* _Nonnull accessor) 243 __INTRODUCED_IN(36); 244 245 /** 246 * Return the ABinderRpc_Accessor associated with an AIBinder. The instance must match 247 * the ABinderRpc_Accessor implementation. 248 * This can be used when receiving an AIBinder from another process that the 249 * other process obtained from ABinderRpc_Accessor_asBinder. 250 * 251 * \param instance name of the service that the Accessor is responsible for. 252 * This string must remain valid and unchanged for the duration of this 253 * function call. 254 * \param accessorBinder proxy binder from another process's ABinderRpc_Accessor. 255 * This function preserves the refcount of this binder object and the 256 * caller still owns it. 257 * \return ABinderRpc_Accessor representing the other processes ABinderRpc_Accessor 258 * implementation. The caller owns this ABinderRpc_Accessor instance and 259 * is responsible for deleting it with ABinderRpc_Accessor_delete or 260 * passing ownership of it elsewhere, like returning it through 261 * ABinderRpc_AccessorProvider_getAccessorCallback. 262 * nullptr on error when the accessorBinder is not a valid binder from 263 * an IAccessor implementation or the IAccessor implementation is not 264 * associated with the provided instance. 265 */ 266 ABinderRpc_Accessor* _Nullable ABinderRpc_Accessor_fromBinder(const char* _Nonnull instance, 267 AIBinder* _Nonnull accessorBinder) 268 __INTRODUCED_IN(36); 269 270 /** 271 * Wrap an ABinderRpc_Accessor proxy binder with a delegator binder. 272 * 273 * The IAccessorDelegator binder delegates all calls to the proxy binder. 274 * 275 * This is required only in very specific situations when the process that has 276 * permissions to connect the to RPC service's socket and create the FD for it 277 * is in a separate process from this process that wants to serve the Accessor 278 * binder and the communication between these two processes is binder RPC. This 279 * is needed because the binder passed over the binder RPC connection can not be 280 * used as a kernel binder, and needs to be wrapped by a kernel binder that can 281 * then be registered with service manager. 282 * 283 * \param instance name of the service associated with the Accessor 284 * \param binder the AIBinder* from the ABinderRpc_Accessor from the 285 * ABinderRpc_Accessor_asBinder. The other process across the binder RPC 286 * connection will have called this and passed the AIBinder* across a 287 * binder interface to the process calling this function. 288 * \param outDelegator the AIBinder* for the kernel binder that wraps the 289 * 'binder' argument and delegates all calls to it. The caller now owns 290 * this object with one strong ref count and is responsible for removing 291 * that ref count with with AIBinder_decStrong when the caller wishes to 292 * drop the reference. 293 * \return STATUS_OK on success. 294 * STATUS_UNEXPECTED_NULL if instance or binder arguments are null. 295 * STATUS_BAD_TYPE if the binder is not an IAccessor. 296 * STATUS_NAME_NOT_FOUND if the binder is an IAccessor, but not 297 * associated with the provided instance name. 298 */ 299 binder_status_t ABinderRpc_Accessor_delegateAccessor(const char* _Nonnull instance, 300 AIBinder* _Nonnull binder, 301 AIBinder* _Nullable* _Nonnull outDelegator) 302 __INTRODUCED_IN(36); 303 304 /** 305 * Create a new ABinderRpc_ConnectionInfo with sockaddr. This can be supported socket 306 * types like sockaddr_vm (vsock) and sockaddr_un (Unix Domain Sockets). 307 * 308 * \param addr sockaddr pointer that can come from supported socket 309 * types like sockaddr_vm (vsock) and sockaddr_un (Unix Domain Sockets). 310 * \param len length of the concrete sockaddr type being used. Like 311 * sizeof(sockaddr_vm) when sockaddr_vm is used. 312 * \return the connection info based on the given sockaddr 313 */ 314 ABinderRpc_ConnectionInfo* _Nullable ABinderRpc_ConnectionInfo_new(const sockaddr* _Nonnull addr, 315 socklen_t len) 316 __INTRODUCED_IN(36); 317 318 /** 319 * Delete an ABinderRpc_ConnectionInfo object that was created with 320 * ABinderRpc_ConnectionInfo_new. 321 * 322 * \param info object to be deleted 323 */ 324 void ABinderRpc_ConnectionInfo_delete(ABinderRpc_ConnectionInfo* _Nonnull info) __INTRODUCED_IN(36); 325 326 /** @} */ 327 328 __END_DECLS 329