binder

package
v0.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2026 License: CC0-1.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ReadStatus 

func ReadStatus(p *parcel.Parcel) error

ReadStatus reads an AIDL Status from a reply parcel. Returns nil if the status indicates success (ExceptionNone). Returns a *aidlerrors.StatusError if an exception is present.

Android Java services may prepend reply parcels with "fat reply headers":

  • EX_HAS_NOTED_APPOPS_REPLY_HEADER (-127): AppOps header, skip then read the real exception code.
  • EX_HAS_REPLY_HEADER (-128): StrictMode header, skip then treat as success.

func WriteBinderToParcel 

func WriteBinderToParcel(
	ctx context.Context,
	p *parcel.Parcel,
	b IBinder,
	transport Transport,
)

WriteBinderToParcel writes an IBinder to a parcel, choosing the correct wire format based on whether the binder is a local stub or a remote proxy.

For remote proxies (ProxyBinder), it writes BINDER_TYPE_HANDLE with the handle. For local stubs (StubBinder), it auto-registers the stub with the transport (if not already registered) and writes BINDER_TYPE_BINDER with the cookie.

func WriteStatus 

func WriteStatus(
	p *parcel.Parcel,
	err error,
)

WriteStatus writes an AIDL Status to a parcel. If err is nil, writes ExceptionNone (success). If err is a *aidlerrors.StatusError, writes its contents. Otherwise, wraps the error as ExceptionIllegalState.

Types

type CallerIdentity 

type CallerIdentity struct {
	PackageName    string
	AttributionTag string
	UserID         int32
	PID            int32
	UID            int32
}

CallerIdentity holds the caller's identity, used to auto-fill identity parameters in AIDL proxy method calls.

func DefaultCallerIdentity 

func DefaultCallerIdentity() CallerIdentity

DefaultCallerIdentity returns the identity for a shell-user process. The package name defaults to "com.android.shell"; callers should override PackageName for non-shell contexts (e.g., app or system service processes).

type Config 

type Config struct {
	MaxThreads uint32
	MapSize    uint32
}

Config holds Transport configuration.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns the default transport configuration.

type DeathRecipient 

type DeathRecipient interface {
	BinderDied()
}

DeathRecipient receives notifications when a remote Binder object dies.

type IBinder 

type IBinder interface {
	Transact(
		ctx context.Context,
		code TransactionCode,
		flags TransactionFlags,
		data *parcel.Parcel,
	) (_reply *parcel.Parcel, _err error)

	// ResolveCode maps an AIDL interface descriptor and method name
	// to the correct TransactionCode for the target device.
	// Returns an error if the method cannot be resolved (unsupported
	// device version or unknown method).
	ResolveCode(
		ctx context.Context,
		descriptor string,
		method string,
	) (TransactionCode, error)

	LinkToDeath(ctx context.Context, recipient DeathRecipient) (_err error)
	UnlinkToDeath(ctx context.Context, recipient DeathRecipient) (_err error)
	IsAlive(ctx context.Context) bool
	Handle() uint32
	Cookie() uintptr
	Transport() VersionAwareTransport
	Identity() CallerIdentity
}

IBinder is the high-level interface to a remote Binder object.

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option configures a Transport.

func WithMapSize 

func WithMapSize(n uint32) Option

WithMapSize sets the mmap size for the Binder driver.

func WithMaxThreads 

func WithMaxThreads(n uint32) Option

WithMaxThreads sets the maximum number of Binder threads.

type Options 

type Options []Option

Options is a slice of Option.

func (Options) Config 

func (opts Options) Config() Config

Config applies all options to the default configuration and returns the result.

type ProxyBinder 

type ProxyBinder struct {
	// contains filtered or unexported fields
}

ProxyBinder is a client-side handle to a remote Binder object. It delegates all operations to the underlying VersionAwareTransport.

func NewProxyBinder 

func NewProxyBinder(
	transport VersionAwareTransport,
	identity CallerIdentity,
	handle uint32,
) *ProxyBinder

NewProxyBinder creates a new ProxyBinder for the given transport, identity, and handle. The transport must implement VersionAwareTransport (use versionaware.NewTransport to wrap a raw kernelbinder.Driver).

func (*ProxyBinder) Cookie 

func (b *ProxyBinder) Cookie() uintptr

Cookie returns 0 for remote proxies (only local stubs have a cookie).

func (*ProxyBinder) Handle 

func (b *ProxyBinder) Handle() uint32

Handle returns the kernel-level handle for this Binder object.

func (*ProxyBinder) Identity 

func (b *ProxyBinder) Identity() CallerIdentity

Identity returns the caller identity associated with this ProxyBinder.

func (*ProxyBinder) IsAlive 

func (b *ProxyBinder) IsAlive(ctx context.Context) bool

IsAlive checks whether the remote Binder object is still alive via a ping transaction.

func (*ProxyBinder) LinkToDeath 

func (b *ProxyBinder) LinkToDeath(
	ctx context.Context,
	recipient DeathRecipient,
) (_err error)

LinkToDeath registers a DeathRecipient for this Binder object.

func (*ProxyBinder) ResolveCode 

func (b *ProxyBinder) ResolveCode(
	ctx context.Context,
	descriptor string,
	method string,
) (TransactionCode, error)

ResolveCode delegates to the underlying Transport.

func (*ProxyBinder) Transact 

func (b *ProxyBinder) Transact(
	ctx context.Context,
	code TransactionCode,
	flags TransactionFlags,
	data *parcel.Parcel,
) (_reply *parcel.Parcel, _err error)

Transact sends a transaction to the remote Binder object. FlagAcceptFDs is always set, matching Android's IPCThreadState::transact() behavior, so that replies containing file descriptors are not rejected by the kernel.

func (*ProxyBinder) Transport 

func (b *ProxyBinder) Transport() VersionAwareTransport

Transport returns the underlying VersionAwareTransport used by this ProxyBinder.

func (*ProxyBinder) UnlinkToDeath 

func (b *ProxyBinder) UnlinkToDeath(
	ctx context.Context,
	recipient DeathRecipient,
) (_err error)

UnlinkToDeath unregisters a DeathRecipient for this Binder object.

type StubBinder 

type StubBinder struct {
	Receiver TransactionReceiver
	// contains filtered or unexported fields
}

StubBinder is a server-side IBinder that wraps a TransactionReceiver. When passed as a binder parameter in a proxy method, it is written as a local binder object (BINDER_TYPE_BINDER) instead of a handle reference (BINDER_TYPE_HANDLE).

The cookie is assigned lazily the first time the stub is registered with a Transport (see RegisterWithTransport).

func NewStubBinder 

func NewStubBinder(
	receiver TransactionReceiver,
) *StubBinder

NewStubBinder creates a StubBinder wrapping the given TransactionReceiver.

func (*StubBinder) BinderPtr 

func (s *StubBinder) BinderPtr() uintptr

BinderPtr returns the stable address used as the binder node identity in the kernel (the flat_binder_object.binder field). This address is distinct from Cookie() -- the kernel uses BinderPtr to create/find the binder_node, and echoes Cookie back in BR_TRANSACTION for dispatch.

func (*StubBinder) Cookie 

func (s *StubBinder) Cookie() uintptr

Cookie returns the cookie assigned by RegisterWithTransport. Returns 0 if the stub has not been registered yet.

func (*StubBinder) Handle 

func (s *StubBinder) Handle() uint32

Handle returns 0 for local stubs. This is intentional: stubs are local objects and do not have a remote handle. Handle values are only meaningful for remote proxies (ProxyBinder). The value 0 is also used by ServiceManager's handle, but the two cannot be confused because a StubBinder is never used as a remote proxy.

func (*StubBinder) Identity 

func (s *StubBinder) Identity() CallerIdentity

Identity returns the default caller identity.

func (*StubBinder) IsAlive 

func (s *StubBinder) IsAlive(_ context.Context) bool

IsAlive always returns true for local stubs.

func (*StubBinder) LinkToDeath 

func (s *StubBinder) LinkToDeath(
	_ context.Context,
	_ DeathRecipient,
) error

LinkToDeath is a no-op for local stubs (they cannot die remotely).

func (*StubBinder) RegisterWithTransport 

func (s *StubBinder) RegisterWithTransport(
	ctx context.Context,
	t Transport,
) uintptr

RegisterWithTransport registers this stub's receiver with the given transport and stores the returned cookie. Subsequent calls are no-ops (the stub is only registered once). Returns the cookie.

func (*StubBinder) ResolveCode 

func (s *StubBinder) ResolveCode(
	_ context.Context,
	_ string,
	_ string,
) (TransactionCode, error)

ResolveCode is not supported on local stubs.

func (*StubBinder) Transact 

func (s *StubBinder) Transact(
	_ context.Context,
	_ TransactionCode,
	_ TransactionFlags,
	_ *parcel.Parcel,
) (*parcel.Parcel, error)

Transact is not supported on local stubs; calling it returns an error.

func (*StubBinder) Transport 

func (s *StubBinder) Transport() VersionAwareTransport

Transport returns the VersionAwareTransport stored during RegisterWithTransport, or nil if the stub has not been registered or the stored transport does not implement VersionAwareTransport.

func (*StubBinder) UnlinkToDeath 

func (s *StubBinder) UnlinkToDeath(
	_ context.Context,
	_ DeathRecipient,
) error

UnlinkToDeath is a no-op for local stubs.

type TransactionCode 

type TransactionCode uint32

TransactionCode identifies a method in a Binder interface. User-defined codes start at FirstCallTransaction. 

const (
	FirstCallTransaction TransactionCode = 0x00000001
	LastCallTransaction  TransactionCode = 0x00ffffff

	PingTransaction  TransactionCode = ('_' << 24) | ('P' << 16) | ('N' << 8) | 'G'
	DumpTransaction  TransactionCode = ('_' << 24) | ('D' << 16) | ('M' << 8) | 'P'
	ShellTransaction TransactionCode = ('_' << 24) | ('C' << 16) | ('M' << 8) | 'D'
	// InterfaceTransaction matches Android's INTERFACE_TRANSACTION =
	// B_PACK_CHARS('_','N','T','F') from IBinder.h.
	InterfaceTransaction TransactionCode = ('_' << 24) | ('N' << 16) | ('T' << 8) | 'F'
	SyspropsTransaction  TransactionCode = ('_' << 24) | ('S' << 16) | ('P' << 8) | 'R'
)

type TransactionFlags 

type TransactionFlags uint32

TransactionFlags control transaction behavior. 

const (
	FlagOneway             TransactionFlags = 0x00000001
	FlagCollectNotedAppOps TransactionFlags = 0x00000002
	// FlagAcceptFDs tells the binder kernel that this process can receive
	// file descriptors in the reply. Without this flag, the kernel rejects
	// replies containing FDs with BR_FAILED_REPLY. Android's
	// IPCThreadState::transact() always sets this flag.
	FlagAcceptFDs     TransactionFlags = 0x00000010
	FlagClearBuf      TransactionFlags = 0x00000020
	FlagPrivateVendor TransactionFlags = 0x10000000
)

type TransactionReceiver 

type TransactionReceiver interface {
	// Descriptor returns the AIDL interface descriptor (e.g.
	// "android.frameworks.cameraservice.device.ICameraDeviceCallback").
	// The binder driver queries this via INTERFACE_TRANSACTION to
	// verify the remote binder's class.
	Descriptor() string

	OnTransaction(
		ctx context.Context,
		code TransactionCode,
		data *parcel.Parcel,
	) (*parcel.Parcel, error)
}

TransactionReceiver processes incoming binder transactions. Implemented by generated Stub types that dispatch transaction codes to typed Go interface methods.

type Transport 

type Transport interface {
	Transact(
		ctx context.Context,
		handle uint32,
		code TransactionCode,
		flags TransactionFlags,
		data *parcel.Parcel,
	) (_reply *parcel.Parcel, _err error)

	AcquireHandle(ctx context.Context, handle uint32) (_err error)
	ReleaseHandle(ctx context.Context, handle uint32) (_err error)

	RegisterReceiver(
		ctx context.Context,
		receiver TransactionReceiver,
	) uintptr

	RequestDeathNotification(
		ctx context.Context,
		handle uint32,
		recipient DeathRecipient,
	) (_err error)

	ClearDeathNotification(
		ctx context.Context,
		handle uint32,
		recipient DeathRecipient,
	) (_err error)

	Close(ctx context.Context) (_err error)
}

Transport is the low-level interface to the Binder kernel driver. It is implemented by kernelbinder.Driver.

type VersionAwareTransport 

type VersionAwareTransport interface {
	Transport

	// ResolveCode maps an AIDL interface descriptor and method name
	// to the correct TransactionCode for the target device.
	// Returns an error if the method does not exist on the device's
	// API level/revision.
	ResolveCode(
		ctx context.Context,
		descriptor string,
		method string,
	) (TransactionCode, error)
}

VersionAwareTransport extends Transport with version-aware transaction code resolution. Implemented by versionaware.Transport.

Source Files

View all Source files

Directories

Path Synopsis
dex

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.