// Copyright 2024 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef BASE_ANDROID_BINDER_H_
#define BASE_ANDROID_BINDER_H_
#include <android/binder_ibinder.h>
#include <android/binder_parcel.h>
#include <android/binder_status.h>
#include <jni.h>
#include <cstdint>
#include <type_traits>
#include <utility>
#include <vector>
#include "base/android/scoped_java_ref.h"
#include "base/base_export.h"
#include "base/check.h"
#include "base/containers/span.h"
#include "base/files/scoped_file.h"
#include "base/memory/raw_ptr.h"
#include "base/memory/ref_counted.h"
#include "base/numerics/safe_conversions.h"
#include "base/synchronization/lock.h"
#include "base/types/expected.h"
#include "base/types/expected_macros.h"
// DEFINE_BINDER_CLASS() generates a definition for a unique binder class.
// Binder classes are used by the binder implementation to enforce a kind of
// type safety, requiring client IBinders to be associated with the same class
// as the remote object's original IBinder.
//
// Objects implementing SupportsBinder<T> must specify such a class as the T;
// and clients wishing to perform transactions against such objects must use a
// TypedBinderRef<T> to do so.
//
// See usage comments on SupportsBinder<T> below.
#define _BINDER_CLASS_LINE(line) _BINDER_CLASS_LINE2(line)
#define _BINDER_CLASS_LINE2(line) #line
#define DEFINE_BINDER_CLASS(name) \
struct name : public base::android::internal::BinderClassBase { \
using BinderRef = base::android::TypedBinderRef<name>; \
static inline AIBinder_Class* GetBinderClass() { \
static AIBinder_Class* const clazz = RegisterBinderClass( \
#name ":" __FILE__ ":" _BINDER_CLASS_LINE(__LINE__)); \
return clazz; \
} \
static inline base::android::TypedBinderRef<name> AdoptBinderRef( \
base::android::BinderRef binder) { \
return base::android::TypedBinderRef<name>::Adopt(std::move(binder)); \
} \
}
namespace base::android {
class BinderRef;
class Parcel;
template <typename T>
using BinderStatusOr = expected<T, binder_status_t>;
// Provides a read-only view into a AParcel. Does not retain ownership of the
// AParcel, which must outlive this object.
class BASE_EXPORT ParcelReader {
public:
explicit ParcelReader(const AParcel* parcel);
explicit ParcelReader(const Parcel& parcel);
ParcelReader(const ParcelReader&);
ParcelReader& operator=(const ParcelReader&);
~ParcelReader();
// A subset of the NDK functions defined for reading from an AParcel. Others
// may be exposed here as needed.
BinderStatusOr<BinderRef> ReadBinder() const;
BinderStatusOr<int32_t> ReadInt32() const;
BinderStatusOr<uint32_t> ReadUint32() const;
BinderStatusOr<uint64_t> ReadUint64() const;
BinderStatusOr<ScopedFD> ReadFileDescriptor() const;
// Reads a byte array from the parcel. `allocator` is called with a single
// size_t argument for the number of bytes in the array and must return a
// pointer to at least that much memory, into which ReadByteArray() will copy
// the array data before returning. If the parcel contains an empty or null
// byte array, `allocator` is not invoked. If `allocator` is invoked and
// returns null, ReadByteArray() returns an error.
template <typename Allocator>
BinderStatusOr<void> ReadByteArray(Allocator allocator) const {
auto c_allocator = [](void* context, int32_t length, int8_t** out) {
const auto& allocator = *static_cast<Allocator*>(context);
const auto size = saturated_cast<size_t>(length);
if (!size) {
*out = nullptr;
return true;
}
// Binder API wants int8_t for bytes, but we generally use uint8_t.
uint8_t* const data = allocator(size);
*out = reinterpret_cast<int8_t*>(data);
return !!data;
};
return ReadByteArrayImpl(c_allocator, &allocator);
}
private:
BinderStatusOr<void> ReadByteArrayImpl(AParcel_byteArrayAllocator allocator,
void* context) const;
raw_ptr<const AParcel> parcel_;
};
// Provides a writable view into a AParcel. Does not retain ownership of the
// AParcel, which must outlive this object.
class BASE_EXPORT ParcelWriter {
public:
explicit ParcelWriter(AParcel* parcel);
explicit ParcelWriter(Parcel& parcel);
ParcelWriter(const ParcelWriter&);
ParcelWriter& operator=(const ParcelWriter&);
~ParcelWriter();
// A subset of the NDK functions defined for writing to an AParcel. Others may
// be exposed here as needed.
BinderStatusOr<void> WriteBinder(BinderRef binder) const;
BinderStatusOr<void> WriteInt32(int32_t value) const;
BinderStatusOr<void> WriteUint32(uint32_t value) const;
BinderStatusOr<void> WriteUint64(uint64_t value) const;
BinderStatusOr<void> WriteByteArray(span<const uint8_t> bytes) const;
BinderStatusOr<void> WriteFileDescriptor(ScopedFD fd) const;
private:
raw_ptr<AParcel> parcel_;
};
// Wraps unique ownership of an AParcel. This is similar to the NDK's
// ScopedAParcel, but it uses our internal BinderApi to invoke NDK functions.
class BASE_EXPORT Parcel {
public:
Parcel();
explicit Parcel(AParcel* parcel);
Parcel(Parcel&& other);
Parcel& operator=(Parcel&& other);
~Parcel();
explicit operator bool() const { return parcel_ != nullptr; }
const AParcel* get() const { return parcel_; }
AParcel* get() { return parcel_; }
[[nodiscard]] AParcel* release() { return std::exchange(parcel_, nullptr); }
void reset();
ParcelReader reader() const { return ParcelReader(*this); }
ParcelWriter writer() { return ParcelWriter(*this); }
private:
raw_ptr<AParcel> parcel_ = nullptr;
};
// A BinderRef owns a strong ref-count on an AIBinder. This is like the NDK's
// SpAIBinder, but it uses our internal BinderApi to invoke NDK functions.
class BASE_EXPORT BinderRef {
public:
BinderRef();
explicit BinderRef(AIBinder* binder);
BinderRef(const BinderRef& other);
BinderRef& operator=(const BinderRef& other);
BinderRef(BinderRef&& other);
BinderRef& operator=(BinderRef&& other);
~BinderRef();
explicit operator bool() const { return binder_ != nullptr; }
AIBinder* get() const { return binder_; }
[[nodiscard]] AIBinder* release() { return std::exchange(binder_, nullptr); }
void reset();
// Returns a new strong reference to this binder as a local Java object
// reference.
ScopedJavaLocalRef<jobject> ToJavaBinder(JNIEnv* env) const;
// Returns a new strong reference to an existing Java binder as a BinderRef.
static BinderRef FromJavaBinder(JNIEnv* env, jobject java_binder);
// Attempts to associate this binder with `binder_class`. Generally should be
// used via TypedBinderRef<T>::Adopt() or the equivalent T::AdoptBinderRef()
// for some binder class T.
bool AssociateWithClass(AIBinder_Class* binder_class);
protected:
// Protected to force usage through a strongly typed subclass, ensuring that
// transaction clients have an associated binder class. See documentation on
// TypedBinderRef<T> below.
BinderStatusOr<Parcel> PrepareTransaction();
BinderStatusOr<Parcel> TransactImpl(transaction_code_t code,
Parcel parcel,
binder_flags_t flags);
protected:
raw_ptr<AIBinder> binder_ = nullptr;
};
namespace internal {
// Base class for classes generated by DEFINE_BINDER_CLASS().
class BASE_EXPORT BinderClassBase {
public:
static AIBinder_Class* RegisterBinderClass(const char* descriptor);
};
// Common implementation for SupportsBinder<T> below. Instances of this base
// class handle IBinder callbacks and forward events for destruction and
// incoming transactions to a templated subclass.
class BASE_EXPORT SupportsBinderBase
: public RefCountedThreadSafe<SupportsBinderBase> {
public:
explicit SupportsBinderBase(AIBinder_Class* binder_class);
// Called for every incoming transaction on the underlying IBinder. Note that
// this is called from the binder thread pool so implementations must be
// thread-safe.
virtual BinderStatusOr<void> OnBinderTransaction(transaction_code_t code,
const ParcelReader& in,
const ParcelWriter& out) = 0;
// Called any time the underlying IBinder is destroyed. Note that this may be
// invoked multiple times, as the underlying IBinder exists only as long as
// there are living BinderRefs referencing this object. If BinderRefs are
// created and then all destroyed, this will be invoked once. If subsequent
// BinderRefs are created and then all destroyed, this will be invoked again.
//
// Similar to OnBinderTransaction, this is invoked from the binder thread pool
// and implementations must be thread-safe.
virtual void OnBinderDestroyed();
protected:
friend class RefCountedThreadSafe<SupportsBinderBase>;
friend class BinderClassBase;
virtual ~SupportsBinderBase();
// Creates a strong reference to the underlying IBinder, allocating a new
// IBinder if one did not already exist for this object.
BinderRef GetBinder();
private:
void OnBinderDestroyedBase();
// Binder class callbacks.
static void* OnIBinderCreate(void* self);
static void OnIBinderDestroy(void* self);
static binder_status_t OnIBinderTransact(AIBinder* binder,
transaction_code_t code,
const AParcel* in,
AParcel* out);
const raw_ptr<AIBinder_Class> binder_class_;
Lock lock_;
// A weak reference to the underlying IBinder, if one exists.
raw_ptr<AIBinder_Weak> weak_binder_ GUARDED_BY(lock_) = nullptr;
// As long as any IBinder is alive for this object, we retain an extra ref
// count on `this` to ensure that transactions can be handled safely.
scoped_refptr<SupportsBinderBase> self_for_binder_ GUARDED_BY(lock_);
};
} // namespace internal
// A BinderRef which has been associated with a specific binder class.
template <typename T>
class TypedBinderRef : public BinderRef {
public:
static_assert(std::is_base_of_v<android::internal::BinderClassBase, T>,
"Invalid binder class type");
TypedBinderRef() = default;
// Asserts that the binder can be associated with class T. This is safe to
// call when it's known that the binder hasn't been associated with any other
// class in the calling process yet.
explicit TypedBinderRef(BinderRef binder) {
CHECK(!binder || binder.AssociateWithClass(T::GetBinderClass()));
binder_ = binder.release();
}
TypedBinderRef(const TypedBinderRef&) = default;
TypedBinderRef& operator=(const TypedBinderRef&) = default;
TypedBinderRef(TypedBinderRef&&) = default;
TypedBinderRef& operator=(TypedBinderRef&&) = default;
~TypedBinderRef() = default;
// Adopts a BinderRef that is not already associated with another binder
// class, associating it with T. If `binder` is already associated with T this
// is a no-op which only narrows the ref type.
//
// If `binder` was already associated with a binder class other than T, the
// reference is dropped and this returns null.
//
// For convenience clients may instead prefer to call this method via
// T::AdoptBinderRef() as defined by DEFINE_BINDER_CLASS(T).
static TypedBinderRef<T> Adopt(BinderRef binder) {
TypedBinderRef<T> typed_binder;
if (binder.AssociateWithClass(T::GetBinderClass())) {
typed_binder.binder_ = binder.release();
}
return typed_binder;
}
// Prepares a new transaction on this binder, returning a Parcel that can be
// populated and then sent via Transact() or TransactOneWay() below.
BinderStatusOr<Parcel> PrepareTransaction() {
return BinderRef::PrepareTransaction();
}
// Transact with a `parcel` created by a call to PrepareTransaction() on the
// same binder. Returns the output parcel from the transaction. `code` is
// an arbitrary value with interface-specific meaning.
BinderStatusOr<Parcel> Transact(transaction_code_t code, Parcel parcel) {
return TransactImpl(code, std::move(parcel), /*flags=*/0);
}
// Like Transact(), but this internally prepares a transacation and passes the
// allocated Parcel into `fn`. After `fn` returns the Parcel is transacted.
template <typename Fn>
BinderStatusOr<Parcel> Transact(transaction_code_t code, Fn fn) {
ASSIGN_OR_RETURN(auto parcel, PrepareTransaction());
RETURN_IF_ERROR(fn(ParcelWriter(parcel.get())));
return Transact(code, std::move(parcel));
}
// Like Transact() but asynchronous. Discards the empty response parcel.
BinderStatusOr<void> TransactOneWay(transaction_code_t code, Parcel parcel) {
RETURN_IF_ERROR(TransactImpl(code, std::move(parcel), FLAG_ONEWAY));
return ok();
}
// Like TransactOneWay(), but this internally prepares a transaction
// passes the allocated Parcel into `fn`. After `fn` returns the Parcel is
// transacted.
template <typename Fn>
BinderStatusOr<void> TransactOneWay(transaction_code_t code, Fn fn) {
ASSIGN_OR_RETURN(auto parcel, PrepareTransaction());
RETURN_IF_ERROR(fn(ParcelWriter(parcel.get())));
return TransactOneWay(code, std::move(parcel));
}
};
// Base class for objects which support native binder transactions. Example
// usage:
//
// // In some common header.
// DEFINE_BINDER_CLASS(ThingyInterface);
//
// // The interface implementation.
// class Thingy : public base::android::SupportsBinder<ThingyInterface> {
// public:
// ... (normal class stuff, plus overrides of SupportsBinder methods)
// };
//
// // The client. `ref` generally comes from the parent process untyped,
// // specifically from some SupportsBinder<T> subclass calling GetBinder().
// void UseThingy(BinderRef ref) {
// auto thingy = ThingyInterface::AdoptBinderRef(std::move(ref));
// ... (do transactions with `thingy`)
// }
template <typename T>
class BASE_EXPORT SupportsBinder : public internal::SupportsBinderBase {
public:
static_assert(std::is_base_of_v<android::internal::BinderClassBase, T>,
"Invalid binder class type");
SupportsBinder() : SupportsBinderBase(T::GetBinderClass()) {}
// Creates a strong reference to the underlying IBinder, allocating a new
// IBinder if one did not already exist for this object.
TypedBinderRef<T> GetBinder() {
return TypedBinderRef<T>(SupportsBinderBase::GetBinder());
}
protected:
~SupportsBinder() override = default;
};
// Indicates whether Binder NDK functionality is generally available to the
// caller. If this returns false, BinderRefs will always be null and
// SupportsBinder<T> implementations will never receive binder transactions; but
// definitions within this header are otherwise still safe to reference and use.
BASE_EXPORT bool IsNativeBinderAvailable();
// Stashes a global collection of BinderRefs for later retrieval by
// TakeBinderFromParent(). This is intended for use by generic multiprocess
// support code to retain interfaces from the parent process so application-
// specific logic in the child process can retrieve them later. It should be
// called at most once per process, and as early as possible.
BASE_EXPORT void SetBindersFromParent(std::vector<BinderRef> binders);
// Retrieves (by index) a BinderRef which was stashed earlier by
// SetBindersFromParent(). If there is no binder for the given index, the
// returned BinderRef is null. This consumes the binder for that index, so
// subsequent calls for the same index will always return null.
BASE_EXPORT BinderRef TakeBinderFromParent(size_t index);
} // namespace base::android
#endif // BASE_ANDROID_BINDER_H_
Codebase Browser
chromium