BInformant Class Reference

#include <services/Informant.h>

Inheritance diagram for BInformant:

Detailed Description

A class that lets you notify others when something happens. This is to replace sublaunching. The basic idea here is that a service can subclass BInformant, and call Inform() when something needs broadcasting. Clients use the IInformant interface to register for events. They can notified by having a method called on an already existing object (RegisterForCallback()) or by having a component object created, and then having a particular method called on that newly created object (RegisterForCreation()).

Public Member Functions

BInformant (const SContext &context)

BInformant ()

virtual status_t HandleMessage (const SMessage &msg)

Subclasses override this to receive messages.

virtual status_t RegisterForCallback (const SValue &key, const sptr< IBinder > &target, const SValue &method, uint32_t flags=0, const SValue &cookie=B_UNDEFINED_VALUE)

virtual status_t RegisterForCreation (const SValue &key, const sptr< INode > &context, const sptr< IProcess > &process, const SString &component, const SValue &interface, const SValue &method, uint32_t flags, const SValue &cookie)

virtual status_t UnregisterForCallback (const SValue &key, const sptr< IBinder > &target, const SValue &method, uint32_t flags)

Remove an existing callback registration from the informant.

virtual status_t UnregisterForCreation (const SValue &key, const sptr< INode > &context, const sptr< IProcess > &process, const SString &component, const SValue &inspect, const SValue &method, uint32_t flags)

Remove an existing creation registration from the informant.

Protected Member Functions

virtual status_t FinishAtom (const void *id)

Objects can optionally override this function to extend the lifetime of an atom (past the last strong reference).

virtual status_t Inform (const SValue &key, const SValue &information)

virtual void InitAtom ()

Called the first time a strong reference is acquired. All significant object initialization should go here.

virtual ~BInformant ()

Constructor & Destructor Documentation

BInformant ( )

BInformant ( const SContext & context )

~BInformant ( ) [protected, virtual]

Member Function Documentation

status_t FinishAtom ( const void * id ) [protected, virtual]

Objects can optionally override this function to extend the lifetime of an atom (past the last strong reference).
If you return FINISH_ATOM_ASYNC here, your object's destructor will be called asynchronously from the current thread. This is highly recommend if you must acquire a lock in the destructor, to avoid unexpected deadlocks due to things like sptr<> going out of scope while a lock is held.
If you return an error code here, the object's destructor will not be called at this point.
The default implementation will return B_OK, allowing the SAtom destruction to proceed as normal. Don't override this method unless you want some other behavior. Like InitAtom(), you do not need to call the SAtom implementation.

See also:
DecStrong()

Reimplemented from SAtom.

status_t HandleMessage ( const SMessage & msg ) [virtual]

Subclasses override this to receive messages.

Reimplemented from SHandler.

status_t Inform ( const SValue & key,

const SValue & information

) [protected, virtual]

Call this to push out the key and the information
Implements IInformant.

void InitAtom ( ) [protected, virtual]

Called the first time a strong reference is acquired. All significant object initialization should go here.
You can override it and do any setup you need. Note that you do not need to call the SAtom implementation. (So you can derive from two different SAtom implementations and safely call down to both of their IncStrong() methods.)
See also:
IncStrong()

Reimplemented from SAtom.

virtual status_t RegisterForCallback ( const SValue & key,

const sptr< IBinder > & target,

const SValue & method,

uint32_t flags = 0,

const SValue & cookie = B_UNDEFINED_VALUE

) [virtual]

Register to be called when key is pushed.

Parameters:

key The key for which to register. Each subclass of BInformant will most likely push different keys.

target The object on which to call the supplied method.

method The method that will be called on your object when the key is pushed. The method is expressed as an SValue key, which will be a method if the target object is an interface, or it will be passed as the key parameter to Observed if target is a BObserver.

flags The flags to apply. Currently unused, defaults to 0.

cookie An SValue you will receive back when your method is called.

Implements IInformant.

status_t RegisterForCreation ( const SValue & key,

const sptr< INode > & context,

const sptr< IProcess > & process,

const SString & component,

const SValue & interface,

const SValue & method,

uint32_t flags,

const SValue & cookie

) [virtual]

Register to have your component created when key is pushed.
See the descriptions in RegisterForCallback for the key, method, flags and cookie parameters.

Parameters:

key The key for which to register. Each subclass of BInformant will most likely push different keys.

context The context to use when your component is created. Get this from the Root() method on your context, or use get_default_context() if you're in protein land and you don't need elevated security privileges.

process The process in which to create your component. If you pass NULL, a new process will be created just for you. Careful, this might be slow if your key is pushed a lot. WARNING: This passing NULL to get a new process is not yet implemented yet. If you do this, the component will currently end up in the same process as the service.

component The component name to instantiate, for example com.palmsource.apps.Address.Listener

interface The interface to inspect to on your object.

method The method that will be called on your object when the key is pushed. The method is expressed as an SValue key, which will be a method if the target object is an interface, or it will be passed as the key parameter to Observed if target is a BObserver.

flags The flags to apply. Currently unused, defaults to 0.

cookie An SValue you will receive back when your method is called.

Implements IInformant.

virtual status_t UnregisterForCallback ( const SValue & key,

const sptr< IBinder > & target,

const SValue & method,

uint32_t flags

) [virtual]

Remove an existing callback registration from the informant.

Parameters:

[in] key The previously registered kind of notification.

[in] target The previously registered target object.

[in] method The previously registered method name.

[in] flags The previously registered link flags.

Any callback registrations previously supplied to RegisterForCallback() and matching all of key, target, method, and flags will be removed from the informant.
Implements IInformant.

status_t UnregisterForCreation ( const SValue & key,

const sptr< INode > & context,

const sptr< IProcess > & process,

const SString & component,

const SValue & inspect,

const SValue & method,

uint32_t flags

) [virtual]

Remove an existing creation registration from the informant.

Parameters:

[in] key The previously registered kind of notification.

[in] context The previously registered SContext.

[in] process The previously registered process.

[in] component The previously registered component name.

[in] inspect The previously registered interface name.

[in] method The previously registered method name.

[in] flags The previously registered link flags.

Any creation registrations previously supplied to RegisterForCreation() and matching all of key, context, process, component, inspect, method, and flags will be removed from the informant.
Implements IInformant.

The documentation for this class was generated from the following files:


Public Member Functions
	BInformant (const SContext &context)
	BInformant ()
virtual status_t	HandleMessage (const SMessage &msg)
	Subclasses override this to receive messages.
virtual status_t	RegisterForCallback (const SValue &key, const sptr< IBinder > &target, const SValue &method, uint32_t flags=0, const SValue &cookie=B_UNDEFINED_VALUE)
virtual status_t	RegisterForCreation (const SValue &key, const sptr< INode > &context, const sptr< IProcess > &process, const SString &component, const SValue &interface, const SValue &method, uint32_t flags, const SValue &cookie)
virtual status_t	UnregisterForCallback (const SValue &key, const sptr< IBinder > &target, const SValue &method, uint32_t flags)
	Remove an existing callback registration from the informant.
virtual status_t	UnregisterForCreation (const SValue &key, const sptr< INode > &context, const sptr< IProcess > &process, const SString &component, const SValue &inspect, const SValue &method, uint32_t flags)
	Remove an existing creation registration from the informant.
Protected Member Functions
virtual status_t	FinishAtom (const void *id)
	Objects can optionally override this function to extend the lifetime of an atom (past the last strong reference).
virtual status_t	Inform (const SValue &key, const SValue &information)
virtual void	InitAtom ()
	Called the first time a strong reference is acquired. All significant object initialization should go here.
virtual	~BInformant ()