An Introduction to Using Binder Framework on Android Operating System

    An Introduction to Using Binder Framework on Android Operating System
    ----------------------------------------------------------------------

We intend this write-up to serve two purposes: (1) be a document describing 
the Binder framework as implemented on Android operating system, and (2) be a
"how-to" guide for beginners who want to quickly develop Android applications 
in C++ using Binder API.

This document takes a "learning-while-programming" approach. It develops a 
simple service on Android, and in the process, introduces and defines terms, 
presents application code, reproduces source code snippets from the binder 
implementation, and discusses interesting aspects, all at once. We have found 
such an approach quite useful because it presents systemic perspectives right at
once, when it makes more sense. Also, it clears up questions when certain 
aspects appear non-trivial or vague.

Our approach is not without its drawbacks. For one, it assumes that the reader
is confident and competent enough to simultaneously think at different levels.
One should be prepared to switch between application and framework levels 
quickly. Otherwise, our approach has the potential to confuse people to an 
extent that they may feel intimidated and reject learning the whole thing. That,
unfortunately, is not an enjoyable experience at all.

The explanation that follows assumes that you are already familiar with at 
least one component technology such as CORBA, COM, or Java RMI. In order to 
understand what is discussed here, it is essential to have a reasonably good 
grasp of the following concepts: process boundaries (that is, address-space 
separation in modern operating systems), IPC, RPC, method invocation on remote 
objects, marshaling across process boundaries, and proxy objects that help in 
achieving location transparency. 

Binder framework on Android is implemented in C++. The implementation makes use
of template classes, template functions, multiple inheritance, virtual 
inheritance, macros that glue fields and member functions to template classes 
that use multiple inheritance, and base classes with methods that return 
pointers to derived class instances! We also assume a familiarity with smart
pointers. If you have used STL or Boost smart pointers, then you will not have
any difficulty following the Binder implementation details.

All in all, it is an intellectually rewarding exercise to put these pieces 
together in the context of binders. So, without further ado, let's approach 
Binder from its most interesting starting point.

Defining a Custom Interface
---------------------------
An interface defines a collection of functions, and informally specifies the 
semantics of the intended behavior. In Android, the Binder framework has a class
named 'IInterface' that is the base of all user-defined interfaces. 

We can define a custom interface named 'ISampleStack' as shown below:

        class ISampleStack : public Iinterface {
        public:
            virtual status_t push(int data)  = 0;
            virtual status_t peek(int *data) = 0;
            virtual void     pop()           = 0;
        };

ISampleStack defines three operations on stacks - push, pop, and peek.  
Each member function returns NO_ERROR when it successfully executes 
its intended operation. The member function 'push' returns ERROR_STK_FULL when
the stack has no room for the new element. The function 'peek' returns
ERROR_STK_EMPTY when an attempt is made to retrieve value from an empty stack.
The operation 'pop' does not return any value, nor does it indicate errors 
in its execution.

The definition of ISimpleStack elides a few details for brevity and clarity. In 
practice, we need to use a macro within the scope of ISimpleStack declaration 
in order to declare infrastructural data and code required to support binder 
objects. But more on it later - once we gather more information about the 
different pieces that make up a binder object.

Since we are looking for under-the-hood details, it is tempting to take a quick 
look at the declaration of IInterface, which we reproduce here:
        
        class IInterface : public virtual RefBase
        {
        public:
            sp<IBinder>         asBinder();
            sp<const IBinder>   asBinder() const;

        protected:
            virtual IBinder*    onAsBinder() = 0;
        };

At this point, it is adequate to know that the RefBase class implements basic
reference counting facility. Also, the template class 'sp' refers to strong 
pointer smart-pointer implementation. Both RefBase and sp types, which are still 
incomplete from the perspective of our current understanding, indicate that 
binder objects are reference counted, and that perhaps the use of smart pointers 
mitigates the difficulties of reference counting.

Note that IInterface provides access to an  object that implements 
IBinder. This shows that there is a much deeper connection between IInterface
and IBinder, something that will be become more and more clear as we progress.

The asBinder() member function's implementation is starightforward:
        sp<IBinder> IInterface::asBinder()
        {
            return this ? onAsBinder() : NULL;
        }
The framework does not provide an implementation for onAsBinder. It is a pure
virtual function that derived interfaces must override. 

There are at least four key points to note in the code above.First, asBinder() 
function returns a strong pointer to an object that implements
IBinder interface. Therefore, this function yields a reference counted binder 
object. The life of the binder object obtained using asBinder() is 
automatically tracked.

Second, the name 'asBinder' gives us enough hints that in most cases a single 
class implements both IInterface and IBinder. Perhaps, a concrete class employs 
multiple inheritance to bring together implementations derived from IInterface 
and IBinder. 
    
Third, by delegating to onAsBinder() and requiring it to be overridden by 
derived classes, the framework is enabling varieties of implementation. One can 
imagine lazy object creation, virtual proxies for real binder objects, 
decorators or interceptors to modify the behavior of the underlying binder 
object, and so on.

Fourth, asBinder() is overloaded. There is a const version and a non-const 
version of the function. This is useful when programs use const instances of 
classes derived from IIinterface. Although not completely shown here, both  
functions are implemented using the same 'asBinder' definition presented above. 
The const version of 'asBinder' merely const-casts 'this' pointer before calling
'onBinder'.
    
Equipped with the basic understanding of IInterface and ISimpleStack, we can 
turn our attention to another fundamental interface: IBinder. 

IBinder and Binder Objects
--------------------------
In the Binder API, there is a one-to-one relation between IInterface and 
IBinder. For each interface that the application wants to publish, there
should be a corresponding IBinder that abstracts location as well as 
the implementationvdetails of the object that actually realizes the interface.
    
A binder object is an instance of a class that implements the IBinder interface.
We use the term 'binder class' to refer to a concrete class whose instances are 
binder objects. In other words, a binder class directly or indirectly implements
IBinder, and its instances are binder objects.

It is important to know that in Android, a binder class should implement one
and only one interface derived from IInterface. Unlike COM and other component
technologies, Android's Binder implementation does not automatically enable
implementing multiple custom interfaces (that derive from IInterface).

For quick reference, we present a portion of IBinder declaration below. 

        class IBinder : public virtual RefBase {
        public:
            inline                  IBinder() { }
            virtual sp<IInterface>  queryLocalInterface(const String16& 
                                                                    descriptor);
            virtual String16        getInterfaceDescriptor() const = 0;

            virtual bool            isBinderAlive() const = 0;
            virtual status_t        pingBinder() = 0;
            virtual status_t        dump(int fd, 
                                            const Vector<String16>& args) = 0;

            virtual status_t        transact(uint32_t code,
                                                const Parcel& data,
                                                Parcel* reply,
                                                uint32_t flags = 0) = 0;
            
            virtual BBinder*        localBinder();
            virtual BpBinder*       remoteBinder();

            // remaining portion is elided
            ...
            
        protected:
            inline virtual          ~IBinder() { 
        };

Apart from noticing that binder objects are reference counted, there are
a few interesting aspects waiting to be understood before moving on. Notice the 
'queryLocalInterface' function. It takes a string 
descriptor representing an interface, and it returns a (strong) pointer to 
an object that implements IInterface. Also, notice the 'getInterfaceDescriptor' 
function that returns the string descriptor of the interface associated with 
this binder.

There is something interesting going on here. Recall that 'asBinder' 
function of IInterface gives out a pointer to a binder object. Using that binder
object one can 'getInterfaceDescriptor' followed by 'queryLocalInterface' to
get back the original IInterface reference. This demonstrates the one-to-one
relation that exists between the implementation of IInterface and IBinder in a
program.

The 'isBinderAlive' and 'pingBinder' functions are useful when the program wants 
to find out if a binder object can receive calls. If a local or remote binder
object is dead, then these functions will indicate that fact.

Some services may automatically take away binder objects that are not 
periodically 'pinged' by their active clients. This is a potential optimization 
strategy where a service may pool and reuse binder objects to reduce memory 
overhead and to cater to a large number of clients. 

The 'dump' function requests a binder object to persist its state to a stream
represented by the first argument - a file descriptor. The second argument - an
array of strings - represents an arbitrary collection of strings that the caller
wants the binder object to persist in the stream. One may imagine other uses of
this parameter also. For example, some values may alter the behavior of this
function, and some may define the amount of state information persisted.

In our example, the ISimpleStack implementation will store stack's size and 
contents in the given stream. 

The 'transact' function is arguably the most important function. It is from here
a binder object invokes functions that actually implement the behavior
published in the custom interface (for example, ISimpleStack in our case). Let 
us take a closer look at its complete declaration:

        virtual status_t transact(uint32_t code,
                                  const Parcel& data,
                                  Parcel* reply,
                                  uint32_t flags = 0) = 0;

As evident from this declaration, 'transact' is a pure virtual function that
local and remote binders must implement. The first argument - 'code' - denotes
the function that should be carried out. Typically, the binder object uses a
switch statement over the value of this argument to dispatch the actual
function. The second argument - 'data' - of type Parcel, represents the 
arguments that should be unmarshaled (at the callee site) before the binder 
object invokes the function. The third argument - 'reply' - again of type 
Parcel, represents the result of executing the function. It is the return value 
that should be unmarshaled at the caller site. The last argument -  'flags' - 
specifies the nature of IPC call and the contents of parcel objects. One of the 
values that we will be interested in is FLAG_ONEWAY (or TF_ONE_WAY depending on
the source files you look at), which is defined as an enumeration value:
        FLAG_ONEWAY = 0x00000001
This value indicates that the caller is not interested in the return value of 
the call, and that the caller does not block on the result of the remote method
invocation.