Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit db852950 authored by Devin Moore's avatar Devin Moore
Browse files

Fixes for NDK API Review feedback

- spell check
- define failure case for fromBinder
- Add @defgroup explaining the API at a high level.
- Define lifetime of 'instances'
- clarify fromBinder docs about lifetimes

Test: m
Bug: 370781703
Change-Id: Ia840342cfe3d7b76dda2702cac3f499ac4e84bec
parent 23d01733
Loading
Loading
Loading
Loading
+14 −11
Original line number Diff line number Diff line
@@ -94,7 +94,7 @@ struct OnDeleteProviderHolder {
    }
    void* mData;
    ABinderRpc_AccessorProviderUserData_deleteCallback mOnDelete;
    // needs to be copyable for std::function, but we will never copy it
    // needs to be copy-able for std::function, but we will never copy it
    OnDeleteProviderHolder(const OnDeleteProviderHolder&) {
        LOG_ALWAYS_FATAL("This object can't be copied!");
    }
@@ -113,7 +113,7 @@ ABinderRpc_AccessorProvider* ABinderRpc_registerAccessorProvider(
    }
    if (data && onDelete == nullptr) {
        ALOGE("If a non-null data ptr is passed to ABinderRpc_registerAccessorProvider, then a "
              "ABinderRpc_AccessorProviderUserData_deleteCallback must alse be passed to delete "
              "ABinderRpc_AccessorProviderUserData_deleteCallback must also be passed to delete "
              "the data object once the ABinderRpc_AccessorProvider is removed.");
        return nullptr;
    }
@@ -179,7 +179,7 @@ struct OnDeleteConnectionInfoHolder {
    }
    void* mData;
    ABinderRpc_ConnectionInfoProviderUserData_delete mOnDelete;
    // needs to be copyable for std::function, but we will never copy it
    // needs to be copy-able for std::function, but we will never copy it
    OnDeleteConnectionInfoHolder(const OnDeleteConnectionInfoHolder&) {
        LOG_ALWAYS_FATAL("This object can't be copied!");
    }
@@ -197,7 +197,7 @@ ABinderRpc_Accessor* ABinderRpc_Accessor_new(
    }
    if (data && onDelete == nullptr) {
        ALOGE("If a non-null data ptr is passed to ABinderRpc_Accessor_new, then a "
              "ABinderRpc_ConnectionInfoProviderUserData_delete callback must alse be passed to "
              "ABinderRpc_ConnectionInfoProviderUserData_delete callback must also be passed to "
              "delete "
              "the data object once the ABinderRpc_Accessor is deleted.");
        return nullptr;
@@ -304,7 +304,7 @@ ABinderRpc_Accessor* ABinderRpc_Accessor_fromBinder(const char* instance, AIBind

ABinderRpc_ConnectionInfo* ABinderRpc_ConnectionInfo_new(const sockaddr* addr, socklen_t len) {
    if (addr == nullptr || len < 0 || static_cast<size_t>(len) < sizeof(sa_family_t)) {
        ALOGE("Invalid arguments in Arpc_Connection_new");
        ALOGE("Invalid arguments in ABinderRpc_Connection_new");
        return nullptr;
    }
    // socklen_t was int32_t on 32-bit and uint32_t on 64 bit.
@@ -317,7 +317,8 @@ ABinderRpc_ConnectionInfo* ABinderRpc_ConnectionInfo_new(const sockaddr* addr, s
            return nullptr;
        }
        sockaddr_vm vm = *reinterpret_cast<const sockaddr_vm*>(addr);
        LOG_ACCESSOR_DEBUG("Arpc_ConnectionInfo_new found AF_VSOCK. family %d, port %d, cid %d",
        LOG_ACCESSOR_DEBUG(
                "ABinderRpc_ConnectionInfo_new found AF_VSOCK. family %d, port %d, cid %d",
                vm.svm_family, vm.svm_port, vm.svm_cid);
        return new ABinderRpc_ConnectionInfo(vm);
    } else if (addr->sa_family == AF_UNIX) {
@@ -327,7 +328,7 @@ ABinderRpc_ConnectionInfo* ABinderRpc_ConnectionInfo_new(const sockaddr* addr, s
            return nullptr;
        }
        sockaddr_un un = *reinterpret_cast<const sockaddr_un*>(addr);
        LOG_ACCESSOR_DEBUG("Arpc_ConnectionInfo_new found AF_UNIX. family %d, path %s",
        LOG_ACCESSOR_DEBUG("ABinderRpc_ConnectionInfo_new found AF_UNIX. family %d, path %s",
                           un.sun_family, un.sun_path);
        return new ABinderRpc_ConnectionInfo(un);
    } else if (addr->sa_family == AF_INET) {
@@ -337,12 +338,14 @@ ABinderRpc_ConnectionInfo* ABinderRpc_ConnectionInfo_new(const sockaddr* addr, s
            return nullptr;
        }
        sockaddr_in in = *reinterpret_cast<const sockaddr_in*>(addr);
        LOG_ACCESSOR_DEBUG("Arpc_ConnectionInfo_new found AF_INET. family %d, address %s, port %d",
        LOG_ACCESSOR_DEBUG(
                "ABinderRpc_ConnectionInfo_new found AF_INET. family %d, address %s, port %d",
                in.sin_family, inet_ntoa(in.sin_addr), ntohs(in.sin_port));
        return new ABinderRpc_ConnectionInfo(in);
    }

    ALOGE("ARpc APIs only support AF_VSOCK right now but the supplied sockadder::sa_family is: %hu",
    ALOGE("ABinderRpc APIs only support AF_VSOCK right now but the supplied sockaddr::sa_family "
          "is: %hu",
          addr->sa_family);
    return nullptr;
}
+43 −13
Original line number Diff line number Diff line
@@ -21,6 +21,22 @@

__BEGIN_DECLS

/**
 * @defgroup ABinderRpc Binder RPC
 *
 * This set of APIs makes it possible for a process to use the AServiceManager
 * APIs to get binder objects for services that are available over sockets
 * instead of the traditional kernel binder with the extra ServiceManager
 * process.
 *
 * These APIs are used to supply libbinder with enough information to create
 * and manage the socket connections underneath the ServiceManager APIs so the
 * clients do not need to know the service implementation details or what
 * transport they use for communication.
 *
 * @{
 */

/**
 * This represents an IAccessor implementation from libbinder that is
 * responsible for providing a pre-connected socket file descriptor for a
@@ -66,7 +82,8 @@ typedef struct ABinderRpc_ConnectionInfo ABinderRpc_ConnectionInfo;
 * libbinder.
 *
 * \param instance name of the service like
 *        `android.hardware.vibrator.IVibrator/default`
 *        `android.hardware.vibrator.IVibrator/default`. This string must remain
 *        valid and unchanged for the duration of this function call.
 * \param data the data that was associated with this instance when the callback
 *        was registered.
 * \return The ABinderRpc_Accessor associated with the service `instance`. This
@@ -103,13 +120,15 @@ typedef void (*ABinderRpc_AccessorProviderUserData_deleteCallback)(void* _Nullab
 *        instance is being registered that was previously registered, this call
 *        will fail and the ABinderRpc_AccessorProviderUserData_deleteCallback
 *        will be called to clean up the data.
 *        This array of strings must remain valid and unchanged for the duration
 *        of this function call.
 * \param number of instances in the instances array.
 * \param data pointer that is passed to the ABinderRpc_AccessorProvider callback.
 *        IMPORTANT: The ABinderRpc_AccessorProvider now OWNS that object that data
 *        points to. It can be used as necessary in the callback. The data MUST
 *        remain valid for the lifetime of the provider callback.
 *        Do not attempt to give ownership of the same object to different
 *        providers throguh multiple calls to this function because the first
 *        providers through multiple calls to this function because the first
 *        one to be deleted will call the onDelete callback.
 * \param onDelete callback used to delete the objects that `data` points to.
 *        This is called after ABinderRpc_AccessorProvider is guaranteed to never be
@@ -151,7 +170,8 @@ void ABinderRpc_unregisterAccessorProvider(ABinderRpc_AccessorProvider* _Nonnull
 * connect to a socket that a given service is listening on. This is needed to
 * create an ABinderRpc_Accessor so it can connect to these services.
 *
 * \param instance name of the service to connect to
 * \param instance name of the service to connect to. This string must remain
 *        valid and unchanged for the duration of this function call.
 * \param data user data for this callback. The pointer is provided in
 *        ABinderRpc_Accessor_new.
 * \return ABinderRpc_ConnectionInfo with socket connection information for `instance`
@@ -177,7 +197,9 @@ typedef void (*ABinderRpc_ConnectionInfoProviderUserData_delete)(void* _Nullable
 * that can use the info from the ABinderRpc_ConnectionInfoProvider to connect to a
 * socket that the service with `instance` name is listening to.
 *
 * \param instance name of the service that is listening on the socket
 * \param instance name of the service that is listening on the socket. This
 *        string must remain valid and unchanged for the duration of this
 *        function call.
 * \param provider callback that can get the socket connection information for the
 *           instance. This connection information may be dynamic, so the
 *           provider will be called any time a new connection is required.
@@ -219,18 +241,24 @@ AIBinder* _Nullable ABinderRpc_Accessor_asBinder(ABinderRpc_Accessor* _Nonnull a

/**
 * Return the ABinderRpc_Accessor associated with an AIBinder. The instance must match
 * the ABinderRpc_Accessor implementation, and the AIBinder must a proxy binder for a
 * remote service (ABpBinder).
 * This can be used when receivng an AIBinder from another process that the
 * the ABinderRpc_Accessor implementation.
 * This can be used when receiving an AIBinder from another process that the
 * other process obtained from ABinderRpc_Accessor_asBinder.
 *
 * \param instance name of the service that the Accessor is responsible for.
 * \param accessorBinder proxy binder from another processes ABinderRpc_Accessor.
 *        This string must remain valid and unchanged for the duration of this
 *        function call.
 * \param accessorBinder proxy binder from another process's ABinderRpc_Accessor.
 *        This function preserves the refcount of this binder object and the
 *        caller still owns it.
 * \return ABinderRpc_Accessor representing the other processes ABinderRpc_Accessor
 *         implementation. This function does not take ownership of the
 *         ABinderRpc_Accessor (so the caller needs to delete with
 *         ABinderRpc_Accessor_delete), and it preserves the recount of the bidner
 *         object.
 *         implementation. The caller owns this ABinderRpc_Accessor instance and
 *         is responsible for deleting it with ABinderRpc_Accessor_delete or
 *         passing ownership of it elsewhere, like returning it through
 *         ABinderRpc_AccessorProvider_getAccessorCallback.
 *         nullptr on error when the accessorBinder is not a valid binder from
 *         an IAccessor implementation or the IAccessor implementation is not
 *         associated with the provided instance.
 */
ABinderRpc_Accessor* _Nullable ABinderRpc_Accessor_fromBinder(const char* _Nonnull instance,
                                                              AIBinder* _Nonnull accessorBinder)
@@ -258,4 +286,6 @@ ABinderRpc_ConnectionInfo* _Nullable ABinderRpc_ConnectionInfo_new(const sockadd
 */
void ABinderRpc_ConnectionInfo_delete(ABinderRpc_ConnectionInfo* _Nonnull info) __INTRODUCED_IN(36);

/** @} */

__END_DECLS