overview

Documentation

Overview

Binder IPC API overview.

Documents the Android Binder IPC architecture and the ndk/binder type hierarchy. Binder is Android's primary inter-process communication mechanism -- virtually all system service calls (SurfaceFlinger, Activity Manager, Package Manager, etc.) flow through Binder transactions.

Architecture:

Client process                          Server process
  |                                       |
  |-- AIBinder (proxy) ---[kernel]--> AIBinder (local)
  |       |                                |
  |   prepareTransaction              onTransact callback
  |       |                                |
  |   AParcel (write args) --------> AParcel (read args)
  |                                        |
  |   AParcel (read reply) <-------- AParcel (write reply)
  |       |                                |
  |   AStatus (check result)          AStatus (return result)

Type hierarchy in ndk/binder:

Class   - Defines a binder interface (its descriptor string and the
          three callbacks: onCreate, onDestroy, onTransact).
          Created via AIBinder_Class_define.
          Has no Close method -- the class definition is static
          and lives for the process lifetime.

Binder  - A handle to a binder object (local or remote proxy).
          Created via AIBinder_new (local) or obtained from the
          Android service manager (remote).
          Close() decrements the strong reference count.

Parcel  - A container for serialized transaction data. Supports
          writing/reading int32 values and strings.
          Close() deletes the parcel.

Status  - Represents the outcome of a binder transaction.
          Close() deletes the status object.

Error   - An error type wrapping NDK binder status codes.
          Implements the error interface. Constants like
          ErrDeadObject and ErrPermissionDenied map to the
          underlying STATUS_* codes from the NDK.

Transaction flow:

// 1. Define a binder class with callbacks.
//    (AIBinder_Class_define — not yet in high-level API)

// 2. Create a local binder instance.
//    (AIBinder_new — not yet in high-level API)

// 3. Prepare a transaction — allocates an input parcel.
//    (AIBinder_prepareTransaction — not yet in high-level API)

// 4. Marshal arguments into the input parcel.
//    parcel.WriteInt32(42)

// 5. Execute the transaction — sends input, receives output.
//    (AIBinder_transact — not yet in high-level API)

// 6. Unmarshal the reply from the output parcel.
//    parcel.ReadInt32(&result)

// 7. Clean up.
//    parcel.Close()
//    binder.Close()

On the server side, the onTransact callback receives the transaction code and input parcel, reads the arguments, performs the operation, writes the reply into the output parcel, and returns an AStatus.

Prerequisites:

• Android device or emulator with API level 29+ (Binder NDK API).
• The binder interface must be registered with the Android service manager for cross-process discovery. Local (in-process) binder objects can be created directly with AIBinder_new.
• SELinux policy must permit the binder transactions between the client and server security contexts.