Binder
[Support Kit]


Detailed Description

Component-based framework for implementing application and system-level code.

The Binder Kit defines a basic object model (built on C++) that allows instantiated objects to be distributed across any processes desired, taking care of the details of IPC and tracking object references between them.


Files

file  Autobinder.h
 Binder automated marshalling code.
file  Binder.h
 Basic functionality of all Binder objects.
file  Context.h
 Global context that a Binder object runs in.
file  IBinder.h
 Abstract interface to a Binder object.
file  IInterface.h
 Common base class for abstract binderized interfaces.
file  IMemory.h
 Binder-based shared memory interfaces.
file  InstantiateComponent.h
 API to package executables that contain components.
file  KeyID.h
 Class representing a KeyID, used to marshall and unmarshall KeyIDs across Binder interfaces and to send through IPC.
file  Looper.h
 The Binder's per-thread state and utilities.
file  Memory.h
 Simple implementation of IMemoryHeap.
file  Observer.h
 Generic target of Binder links.
file  Package.h
 Interface to an executable image representing a Binder package.
file  Parcel.h
 Container for a raw block of data that can be transfered through IPC.
file  Process.h
 Implementation of the IProcess interface for the local process.
file  Selector.h
 Select something with the Binder!
file  TokenSource.h
 Binder-based access control.

Classes

struct  BAutobinderDef
class  BAutobinderDummiClass
struct  BEffectMethodDef
class  BMemoryHeap
 A simple IMemoryHeap implementation. More...
class  BObserver
 Generic target of Binder links. More...
struct  BParameterInfo
class  BProcess
 Representation of your currently running process. More...
class  BSerialObserver
 BObserver that ensures Observed() is thread-safe. More...
class  BSharedObject
 A representation of a loaded executable image. More...
class  BTokenSource
 A Binder class used to implement mutual access control. More...
class  IBinder
 Abstract generic (scripting) interface to a Binder object. More...
class  IInterface
 Base class for C++ language Binder interfaces. More...
class  IMemory
 Handle on a shared memory region. More...
class  IMemoryDealer
 Interface to a service that can perform shared memory allocations. More...
class  IMemoryHeap
 Handle on a shared memory heap. More...
class  IProcess
 Interface to an operating system process. More...
class  IProcessManager
 Simple interface for dynamically instantiating components into processes. More...
class  ISelector
 Watch data change. More...
class  IUuid
 Interface to request the creation of UUIDs/GUIDs. More...
class  IVirtualMachine
 Virtual machines implement this interface to generate their components. More...
struct  PPointerToMemberFunction
struct  PTypeMarshaller
class  SContext
 Representation of a global context (namespace). More...
class  SKeyID
 Class representing a kernel KeyID. More...
class  SMarshallerForType
class  SPackage
 and doing useful things with it. More...
class  SPackageSptr
 Keep your local executable image loaded. More...
class  SParcel
 Container for a raw block of data that can be transfered through IPC. More...
struct  SysPackageLaunchAttachImageType
struct  SysPackageLaunchGetInstantiateType

Defines

#define ATTRIBUTE_VISIBILITY_HIDDEN
#define B_DECLARE_META_INTERFACE(iname)
 Use this macro inside of your IInterface subclass to define the standard IInterface meta-API.
#define B_FIND_BINDER_I_CLASS_OFFSET(L)   ((((int)static_cast<IInterface*>((L*)10))-10))
#define B_FUNC_INFO(method)   { NULL }
#define B_IMPLEMENT_MARSHAL_PLAN(def, returnValue, remote, binding, which)
#define MEMORYDEALER_NAME_TEMPLATE   "/tmp/memoryarea.%s.%d"

Typedefs

typedef void(* attach_func )(const sptr< BSharedObject > &image)
typedef status_t(* autobinder_local_hook_t )(const sptr< IInterface > &target, SParcel *in, SParcel *out)
typedef void(BAutobinderDummiClass::* BSomeMethod )()
typedef sptr< IBinder >(* instantiate_component_func )(const SString &component, const SContext &context, const SValue &args)
typedef SPackageSptr SDontForgetThis
typedef void(* untyped_func )(void)

Enumerations

enum  { B_FORGET_CURRENT_ENVIRONMENT = 0x00000001 }
enum  { B_SERIAL_OBSERVER_MSG = 'sero' }
enum  {
  B_EFFECT_TRANSACTION = 'efct', B_INSPECT_TRANSACTION = 'insp', B_LINK_TRANSACTION = 'link', B_UNLINK_TRANSACTION = 'unlk',
  B_PING_TRANSACTION = 'ping', B_PUT_TRANSACTION = '_put', B_GET_TRANSACTION = '_get', B_INVOKE_TRANSACTION = 'invk'
}
 Standard IBinder transaction codes. More...
enum  { B_IN_PARAM = 0x00000001, B_OUT_PARAM = 0x00000002 }
enum  { B_WEAK_BINDER_LINK = 0x00000001, B_SYNC_BINDER_LINK = 0x00000002, B_NO_TRANSLATE_LINK = 0x00000004, B_UNLINK_ALL_TARGETS = 0x00000008 }
 Options for Binder links. More...

Functions

status_t autobinder_from_parcel (const BEffectMethodDef &def, SParcel &parcel, void **args, uint32_t *outDirs)
 Used by pidgen to unmarshal when receiving a call.
status_t autobinder_marshal_args (const BParameterInfo *pi, const BParameterInfo *pi_end, uint32_t dir, void **inArgs, SParcel &outParcel, uint32_t *outDirs)
 Marshal an argument list into a parcel.
status_t autobinder_to_parcel (const BEffectMethodDef &def, void **args, void *result, SParcel &parcel, uint32_t dirs)
 Used by pidgen to marshal result when receiving a call.
status_t autobinder_unmarshal_args (const BParameterInfo *pi, const BParameterInfo *pi_end, uint32_t dir, SParcel &inParcel, void **outArgs, uint32_t *outDirs)
 Unmarshal an argument list out of a parcel.
status_t execute_autobinder (uint32_t code, const sptr< IInterface > &target, SParcel &data, SParcel *reply, const BAutobinderDef **defs, size_t def_count, uint32_t flags)
template<class IFACE>
sptr< IFACE > interface_cast (const SValue &v)
 Convert an SValue containing a binder object to a concrete interface.
template<class IFACE>
sptr< IFACE > interface_cast (const sptr< IBinder > &b)
 Convert a generic IBinder to a concrete interface.
status_t InvokeAutobinderFunction (const BEffectMethodDef *def, void *object, const SValue &args, SValue *returnValue)
const SValueBAutobinderDef::key () const
SString SPackageSptr::LoadString (int32_t id, int32_t index=0) const ATTRIBUTE_VISIBILITY_HIDDEN
 Convenience to retrieve a string from your package.
SString SPackageSptr::LoadString (uint32_t index, const SString &locale=SString::EmptyString()) const ATTRIBUTE_VISIBILITY_HIDDEN
 Convenience to retrieve a string from your package via SPackage::LoadString().
SString SPackageSptr::LoadString (const SString &key, const SString &locale=SString::EmptyString()) const ATTRIBUTE_VISIBILITY_HIDDEN
 Convenience to retrieve a string from your package via SPackage::LoadString().
sptr< IByteInputSPackageSptr::OpenResource (uint32_t type, int32_t id) const ATTRIBUTE_VISIBILITY_HIDDEN
 Convenience to retrieve resource data from your package.
sptr< IByteInputSPackageSptr::OpenResource (const SString &fileName, const SString &locale=SString::EmptyString()) const ATTRIBUTE_VISIBILITY_HIDDEN
 Convenience to retrieve resource data from your package via SPackage::OpenResource().
_IMPEXP_SUPPORT const sptr<
ITextOutput > & 
operator<< (const sptr< ITextOutput > &io, const SParcel &value)
SPackage SPackageSptr::Package () const ATTRIBUTE_VISIBILITY_HIDDEN
status_t parameter_from_value (type_code type, const struct PTypeMarshaller *marshaller, const SValue &v, void *result)
status_t parameter_to_value (type_code type, const struct PTypeMarshaller *marshaller, const void *value, SValue *out)
void PerformRemoteBinderCall (int ebp, const BEffectMethodDef *def, unsigned char *returnValue, const sptr< IBinder > &remote, SValue binding, uint32_t which)
const sptr< BSharedObject > & SPackageSptr::SharedObject () const ATTRIBUTE_VISIBILITY_HIDDEN
 Retrieve your package object.
int32_t this_team ()
 SPackageSptr::~SPackageSptr () ATTRIBUTE_VISIBILITY_HIDDEN
 Note that the destructor is very intentionally NOT virtual.

Variables

const SPackage B_NO_PACKAGE
static const size_t SMarshallerForType::f1 = (size_t)&TYPE::PreMarshalParcel
static const size_t SMarshallerForType::f2 = (size_t)&TYPE::MarshalParcel
static const size_t SMarshallerForType::f3 = (size_t)&TYPE::UnmarshalParcel
static const size_t SMarshallerForType::f4 = (size_t)&TYPE::MarshalValue
static const size_t SMarshallerForType::f5 = (size_t)&TYPE::UnmarshalValue
static const size_t SMarshallerForType::marshaller = sizeof(PTypeMarshaller)


Define Documentation

#define ATTRIBUTE_VISIBILITY_HIDDEN
 

#define B_DECLARE_META_INTERFACE iname   ) 
 

Value:

\
        static  const BNS(::palmos::support::) SValue&                                                      \
            Descriptor();                                                                                   \
        static  BNS(::palmos::support::) sptr<I ## iname>                                                   \
            AsInterface(const BNS(::palmos::support::) sptr< BNS(::palmos::support::) IBinder> &o,          \
                        status_t* out_error = NULL);                                                        \
        static  BNS(::palmos::support::) sptr<I ## iname>                                                   \
            AsInterface(const BNS(::palmos::support::) SValue &v,                                           \
                        status_t* out_error = NULL);                                                        \
        static  BNS(::palmos::support::) sptr<I ## iname>                                                   \
            AsInterfaceNoInspect(const BNS(::palmos::support::) sptr< BNS(::palmos::support::) IBinder> &o, \
                                 status_t* out_error = NULL);                                               \
        static  BNS(::palmos::support::) sptr<I ## iname>                                                   \
            AsInterfaceNoInspect(const BNS(::palmos::support::) SValue &v,                                  \
                                 status_t* out_error = NULL);                                               \
Use this macro inside of your IInterface subclass to define the standard IInterface meta-API.

You will not normally use this, instead letting pidgen generate similar code from an IDL file.

#define B_FIND_BINDER_I_CLASS_OFFSET  )     ((((int)static_cast<IInterface*>((L*)10))-10))
 

#define B_FUNC_INFO method   )     { NULL }
 

Use this macro to create a static array of func_info structs. It's not really necessary, but it does the casting for you.

XXX Put example here.

#define B_IMPLEMENT_MARSHAL_PLAN def,
returnValue,
remote,
binding,
which   ) 
 

Value:

{ \
            int ebp;                                    \
            __asm__ __volatile__ (" movl %%ebp, %0;" :"=r"(ebp) );      \
            PerformRemoteBinderCall(ebp, (def), (unsigned char *)(returnValue), (remote), (binding), (which));  \
        }

#define MEMORYDEALER_NAME_TEMPLATE   "/tmp/memoryarea.%s.%d"
 


Typedef Documentation

typedef void(* attach_func)(const sptr< BSharedObject > &image)
 

typedef status_t(* autobinder_local_hook_t)(const sptr< IInterface > &target, SParcel *in, SParcel *out)
 

typedef void(BAutobinderDummiClass::* BSomeMethod)()
 

typedef sptr<IBinder>(* instantiate_component_func)(const SString &component, const SContext &context, const SValue &args)
 

typedef SPackageSptr SDontForgetThis
 

typedef void(* untyped_func)(void)
 


Enumeration Type Documentation

anonymous enum
 

Enumerator:
B_FORGET_CURRENT_ENVIRONMENT 

anonymous enum
 

Enumerator:
B_SERIAL_OBSERVER_MSG 

anonymous enum
 

Standard IBinder transaction codes.

Enumerator:
B_EFFECT_TRANSACTION  Generic IBinder::Effect().
B_INSPECT_TRANSACTION  IBinder::Inspect().
B_LINK_TRANSACTION  IBinder::Link().
B_UNLINK_TRANSACTION  IBinder::Unlink().
B_PING_TRANSACTION  IBinder::PingBinder().
B_PUT_TRANSACTION  IBinder::AutobinderPut().
B_GET_TRANSACTION  IBinder::AutobinderGet().
B_INVOKE_TRANSACTION  IBinder::AutobinderInvoke().

anonymous enum
 

Enumerator:
B_IN_PARAM 
B_OUT_PARAM 

anonymous enum
 

Options for Binder links.

Use with IBinder::Link(), IBinder::Unlink(), IBinder::LinkToDeath(), and IBinder::UnlinkToDeath().

Enumerator:
B_WEAK_BINDER_LINK  The created link holds a weak pointer on the supplied target.

This allows your linked-to object to be destroyed while the link still exists. Be sure to still clean up the link, for example calling Unlink() (with B_WEAK_BINDER_LINK!) in your destructor.

Todo:
Should this be the default for links? It is safer than holding a strong reference, and usually what you want.
B_SYNC_BINDER_LINK  Your object will process the link without unsafely acquiring locks.

Links are normally pushed asynchronously, to avoid deadlocks if a lock is held at the time of the push. By setting this flag, you say that the sender doesn't need to push asychronously to your target, avoiding that overhead. When this flag is set, you must not acquire any locks during processing that could cause a deadlock with the sender. For example, just calling PostMessage() on an SHandler would always be safe to do synchronously.

B_NO_TRANSLATE_LINK  The link mapping will be pushed directly, without translation.

The property/arguments being pushed by the sender are ignored.

B_UNLINK_ALL_TARGETS  Unlink all links to the given target.

Use with IBinder::Unlink() and IBinder::UnlinkToDeath(). The given bindings and other flags will be ignored, simply removing every link that has the given target.


Function Documentation

status_t autobinder_from_parcel const BEffectMethodDef def,
SParcel parcel,
void **  args,
uint32_t *  outDirs
 

Used by pidgen to unmarshal when receiving a call.

In pidgen's generated code, this function is called to unmarshal arguments before performing a local function call.

status_t autobinder_marshal_args const BParameterInfo pi,
const BParameterInfo pi_end,
uint32_t  dir,
void **  inArgs,
SParcel outParcel,
uint32_t *  outDirs
 

Marshal an argument list into a parcel.

status_t autobinder_to_parcel const BEffectMethodDef def,
void **  args,
void *  result,
SParcel parcel,
uint32_t  dirs
 

Used by pidgen to marshal result when receiving a call.

In pidgen's generated code, this function is called to marshal any results after performing a local function call. 'dirs' must be the result of 'outDirs' in autobinder_from_parcel(); or if autobinder_from_parcel() was not used (there were no incoming parameters) it can by 0.

status_t autobinder_unmarshal_args const BParameterInfo pi,
const BParameterInfo pi_end,
uint32_t  dir,
SParcel inParcel,
void **  outArgs,
uint32_t *  outDirs
 

Unmarshal an argument list out of a parcel.

status_t execute_autobinder uint32_t  code,
const sptr< IInterface > &  target,
SParcel data,
SParcel reply,
const BAutobinderDef **  defs,
size_t  def_count,
uint32_t  flags
 

sptr<IFACE> interface_cast const SValue v  ) 
 

Convert an SValue containing a binder object to a concrete interface.

sptr<IFACE> interface_cast const sptr< IBinder > &  b  ) 
 

Convert a generic IBinder to a concrete interface.

status_t InvokeAutobinderFunction const BEffectMethodDef def,
void *  object,
const SValue args,
SValue returnValue
 

Unmarshall the parameters from the SValue, call the function, and put the return value from that function into rv

Object must be the base class where the virtual method you're trying to call was originally declared.

const SValue & key  )  const [inline, inherited]
 

SString LoadString int32_t  id,
int32_t  index = 0
const [inline, inherited]
 

Convenience to retrieve a string from your package.

SString LoadString uint32_t  index,
const SString locale = SString::EmptyString()
const [inline, inherited]
 

Convenience to retrieve a string from your package via SPackage::LoadString().

SString LoadString const SString key,
const SString locale = SString::EmptyString()
const [inline, inherited]
 

Convenience to retrieve a string from your package via SPackage::LoadString().

sptr< IByteInput > OpenResource uint32_t  type,
int32_t  id
const [inline, inherited]
 

Convenience to retrieve resource data from your package.

sptr< IByteInput > OpenResource const SString fileName,
const SString locale = SString::EmptyString()
const [inline, inherited]
 

Convenience to retrieve resource data from your package via SPackage::OpenResource().

_IMPEXP_SUPPORT const sptr<ITextOutput>& operator<< const sptr< ITextOutput > &  io,
const SParcel value
 

SPackage Package  )  const [inline, inherited]
 

status_t parameter_from_value type_code  type,
const struct PTypeMarshaller marshaller,
const SValue v,
void *  result
 

status_t parameter_to_value type_code  type,
const struct PTypeMarshaller marshaller,
const void *  value,
SValue out
 

void PerformRemoteBinderCall int  ebp,
const BEffectMethodDef def,
unsigned char *  returnValue,
const sptr< IBinder > &  remote,
SValue  binding,
uint32_t  which
 

Marshall the parameters, make the remote binder call, and unmarshall the return value.

const sptr< BSharedObject > & SharedObject  )  const [inline, inherited]
 

Retrieve your package object.

int32_t this_team  ) 
 

~SPackageSptr  )  [inline, inherited]
 

Note that the destructor is very intentionally NOT virtual.

It wouldn't cause problems if it was virtual, but there is no reason to do so and it causes unneeded code to be generated.


Variable Documentation

const SPackage B_NO_PACKAGE
 

const size_t f1 = (size_t)&TYPE::PreMarshalParcel [static, inherited]
 

const size_t f2 = (size_t)&TYPE::MarshalParcel [static, inherited]
 

const size_t f3 = (size_t)&TYPE::UnmarshalParcel [static, inherited]
 

const size_t f4 = (size_t)&TYPE::MarshalValue [static, inherited]
 

const size_t f5 = (size_t)&TYPE::UnmarshalValue [static, inherited]
 

const size_t marshaller = sizeof(PTypeMarshaller) [static, inherited]