IInformant Class Reference

#include <services/IInformant.h>

Inheritance diagram for IInformant:

Detailed Description

General API to register for and receiving event broadcasts.

This interface is often used as part of the informant service (published at /services/informant), however objects can also implement it themselves for a private notification registry.

Note:: While the IInformant interface and informant service can be useful in some circumstances, it often makes more sense to use an explicit Link instead. See, for example, the events and properties on the INode and IDatum interfaces.

The informant keeps tracks of objects interested in notifications (specified through the RegisterForCallback() or RegisterForCreation() APIs) and allows those notifications to be broadcast to them through Inform(). Normally an object registering for an informant notification implements the IInformed interface, whose method IInformed::OnInform() is the signature the informant uses when calling back.

Informant notifications are sent out asynchronously -- they are not called back in the same thread that calls Inform().

For using the informant from C++, Binder Recipes has many examples.

For using the informant from the shell, see Example: Informant.

Todo:: API should be updated to support a richer process model, where transient processes can be created to handle the RegisterForCreation() API.

Todo:: RegisterForCreation() should use an SValue instead of an SString for the component name, so that constructor arguments can be included.

See also:: IInformed, Binder Recipes, Example: Informant

Public Member Functions

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

Send informant notifications to registered objects.

status_t LinkInformant (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)

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

Register to receive notifications through a callback to an existing object.

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

Register to receive notifications through a newly instantiated component.

status_t UnlinkInformant (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)

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

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=0)=0

Remove an existing creation registration from the informant.

Protected Member Functions

IInformant ()

virtual ~IInformant ()

Constructor & Destructor Documentation

IInformant ( ) [inline, protected]

virtual ~IInformant ( ) [protected, virtual]

Member Function Documentation

virtual status_t Inform ( const SValue & key,

const SValue & information

) [pure virtual]

Send informant notifications to registered objects.

Parameters:

[in] key Kind of notification to send.

[in] information Information to go with the notification.

Calling this method broadcasts a notification to all callback and creation registrations for the same key. This broadcast will be done in a separate thread, not your own. That is, the notifications will be happening as your thread returns from this function.
Implemented in BInformant.

status_t LinkInformant ( const sptr< IBinder > & to,

const SValue & mappings,

uint32_t flags = 0

) [inline]

virtual status_t RegisterForCallback ( const SValue & key,

const sptr< IBinder > & target,

const SValue & method,

uint32_t flags = 0,

const SValue & cookie = B_UNDEFINED_VALUE

) [pure virtual]

Register to receive notifications through a callback to an existing object.

Parameters:

[in] key The kind of notification you are interested in.

[in] target The object to call when the informant notification is being sent.

[in] method The method to call on your object, often SValue::String("OnInform").

[in] flags Link flags, using the same values as IBinder::Link().

[in] cookie Any additional custom data to associate with your callback.

After calling this function, your object target will receive calls on its method whenever someone calls Inform() with the same key. Use UnregisterForCallback() to remove your object from the informant.
When receiving a notification, your function method will be called with the parameters (SValue information, SValue cookie, SValue key). The information is supplied by the caller to Inform().
Implemented in BInformant.

virtual status_t RegisterForCreation ( const SValue & key,

const sptr< INode > & context,

const sptr< IProcess > & process,

const SString & component,

const SValue & inspect,

const SValue & method,

uint32_t flags = 0,

const SValue & cookie = B_UNDEFINED_VALUE

) [pure virtual]

Register to receive notifications through a newly instantiated component.

Parameters:

[in] key The kind of notification you are interested in.

[in] context The Binder context (SContext) in which to instantiate your component.

[in] process The process in which to instantiate your component.

[in] component Name of your component to instantiate.

[in] inspect The interface to call on your component.

[in] method The method in interface to call on your object, often SValue::String("OnInform").

[in] flags Link flags, using the same values as IBinder::Link().

[in] cookie Any additional custom data to associate with your component.

This method is like RegisterForCallback(), except instead of requiring an existing object it will dynamically instantiate an object and then send the notification to that object.
When processing an informant notifications that this component is registered for, the informant will:

Call SContext(context).RemoteNew(component, process).
Call IBinder::Inspect() for the selected inspect interface.
Call IBinder::Invoke() of method on the final object.

Use UnregisterForCreation() to remove your component from the informant.
Implemented in BInformant.

status_t UnlinkInformant ( const sptr< IBinder > & to,

const SValue & mappings,

uint32_t flags = 0

) [inline]

virtual status_t UnregisterForCallback ( const SValue & key,

const sptr< IBinder > & target,

const SValue & method,

uint32_t flags = 0

) [pure 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.
Implemented in BInformant.

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 = 0

) [pure 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.
Implemented in BInformant.

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

IInformant.h


Public Member Functions
virtual status_t	Inform (const SValue &key, const SValue &information)=0
	Send informant notifications to registered objects.
status_t	LinkInformant (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)
virtual status_t	RegisterForCallback (const SValue &key, const sptr< IBinder > &target, const SValue &method, uint32_t flags=0, const SValue &cookie=B_UNDEFINED_VALUE)=0
	Register to receive notifications through a callback to an existing object.
virtual status_t	RegisterForCreation (const SValue &key, const sptr< INode > &context, const sptr< IProcess > &process, const SString &component, const SValue &inspect, const SValue &method, uint32_t flags=0, const SValue &cookie=B_UNDEFINED_VALUE)=0
	Register to receive notifications through a newly instantiated component.
status_t	UnlinkInformant (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)
virtual status_t	UnregisterForCallback (const SValue &key, const sptr< IBinder > &target, const SValue &method, uint32_t flags=0)=0
	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=0)=0
	Remove an existing creation registration from the informant.
Protected Member Functions
	IInformant ()
virtual	~IInformant ()