os::Event Class Reference
[Various utillity classes.]

Events. More...

List of all members.

Public Member Functions
	Event ()
	Creates a new event.
	~Event ()
	Deletes an event.
status_t	SetToRemote (String zID, int nIndex=0)
	Sets the object to a specific event.
void	Unset ()
	Unsets the event.
bool	IsRemote ()
	Returns whether the object is set to a remote event.
status_t	GetRemoteInfo (proc_id *pnProcess, port_id *phPort, int *pnMessageCode, os::String *pzDesc)
	Returns information about a remote event.
status_t	GetRemoteChildren (std::vector< os::String > *pacList)
	Returns a list of children.
status_t	SetMonitorEnabled (bool bEnabled, Handler *pcTarget=NULL, int nMessageCode=-1)
	Enables/Disables a monitor to an id string.
bool	IsMonitorEnabled ()
	Returns whether monitoring of the event is enabled.
status_t	PostEvent (Message *pcData, Handler *pcReplyHandler=NULL, int nReplyCode=M_REPLY)
	Posts an event.
status_t	GetLastEventMessage (os::Message *cReply)
	Returns the last message sent to the monitors.
Static Public Member Functions
static Event *	Register (String zID, String zDescription, Handler *pcTarget, int nMessageCode, uint32 nFlags=0)
	Registers an event.
Classes
class	Private

---

Detailed Description

Description:

The event class provides methods for interprocess communication.

Registering and handling events:

All events are identified using an id string. Currently this can be any string but in future revisions it has to look like this: <class>/<subclass>/<name>

In this example we want to create an event named "app/TestApp/GetTestString".

A good place to register the event is in the constructor of your application window. Add a "os::Event* m_pcTestEvent" member to the class and add this code in the constructor:

 m_pcTestEvent = new os::Event();
 m_pcTestEvent->Register( "app/TestApp/GetTestString", "This is a test event" (description),
                        this (handler), MSG_GET_TEST_STRING );

That's it. If another application uses this event your window will receive a message with the code MSG_GET_TEST_STRING which can include additional data supplied by the caller.

In this example we want to send a reply. So we put this code into our HandleMessage() method:

 case MSG_GET_TEST_STRING:
 {
   if( !pcMessage->IsSourceWaiting() )
     break;
   int32 nCode;
   pcMessage->FindInt32( "reply_code", &nCode );
   os::Message cReply( nCode );
   cReply.AddString( "test_string", "This is a test" );
   pcMessage->SendReply( &cReply );
   break;
 }

As you can see we first check if the caller is waiting for a reply. If it is we create the reply message and set the code to the value supplied by the caller (the field is added by the os::Event class, not by the calling application itself). Please note that if you do not set the reply code, things will break.

If you follow the kernel log you will see that Syllable complains when you close your application because you haven´t deleted the event. Put this code into your destructor:

 delete( m_pcTestEvent );

Calling an event:

We now want to call this event from another application. This code will do this:

 os::Event cEvent;
 if( cEvent.SetToRemote( "app/TestApp/GetTestString", 0 (index) ) == 0 )
 {
   os::Message cMsg;
   cEvent.PostEvent( &cMsg, this (reply handler), MSG_REPLY (reply message code) );
 }

This code will send an empty message to the event and the reply is sent to the reply handler where we can extract the reply string:

 case MSG_REPLY:
 {
   os::String zTestString;
   if( pcMessage->FindString( "test_string", &zTestString ) != 0 )
        break;
   ...
   break;
 }

Event monitors:

If you want to know what events with a known id string are available, you could frequently use SetToRemote() to poll for the events. This requires additional code and reduces performance. To solve this problem you can set a monitor to events with a given id string. Some code:

 m_pcMonitorEvent = new os::Event();
 m_pcMonitorEvent->SetToRemote( "app/TestApp/GetTestString", -1 );
 m_pcMonitorEvent->SetMonitorEnabled( true, this (handler), MSG_EVENT_CHANGED (code) );

You might wonder what the index -1 means. If you use this index then the os::Event class will not try to get any information about the event because you cannot know if an event with this id string already exists. Make sure you delete the monitor before your application quits! The message sent to the handler will contain a boolean field "event_registered" or "event_unregistered". It can also happen that both fields are not present. The next chapter deals with this.

Broadcasting messages:

The event monitors can also be used to broadcast messages. If you call the PostEvent() method of an event object that you have registered yourself then the message is sent to all monitors. Please note that replies are not supported in this case.

Data storage:

Sometimes a direct communication is not really necessary if you just want to access some information supplied by another application. In this case this application can broadcast the message like in chapter 4. The application that wants to get the information doesn´t have to set a monitor to this event. They can use the GetLastEventMessage() method to get the last message which has been sent.

Author:

Arno Klenke

---

Constructor & Destructor Documentation

Event::Event

(

)

Description:

The event constructor prepares everything to make it possible to register or call events. The os::Application object has to be set up before you create a new os::Event object.

Author:

Arno Klenke ([email protected])

Event::~Event

(

)

Description:

The event destructor deletes a registered event.

Author:

Arno Klenke ([email protected])

---

Member Function Documentation

Event * Event::Register	(	String	zID,
		String	zDescription,
		os::Handler *	pcTarget,
		int	nMessageCode,
		uint32	nFlags = 0
	)			[static]

Description:

Registers an event that can be used for interprocess communication. All events are identified using an id string that has the form class/function/subfunction. An example: class/Mail/CreateNewMail.

Parameters:

	zID	- ID string.
	zDescription	- Description of the call.
	pcTarget	- Handler that will receive the calls. It needs to be added to a handler.
	nMessageCode	- The code of the message that will be sent to the looper. The message can include additional data provided by the caller.
	nFlags	- Flags.

Returns:

0 if successful.

Author:

Arno Klenke ([email protected])

status_t Event::SetToRemote	(	String	zID,
		int	nIndex = 0
	)

Description:

Sets the object to a specific remote event. If the index is set to -1 then only the id string is saved. This allows you to add a monitor to an event that doesn’t exist yet.

Note:

This method will fail if this object already monitors an event or is a registered event.

Parameters:

	zID	- ID string.
	nIndex	- Index of the string.

Returns:

0 if successful. Otherwise the call might not exist. The object is then in an invalid state.

See also:

Unset()

Author:

Arno Klenke ([email protected])

void Event::Unset

(

)

Description:

This method removes all references to the event.

Author:

Arno Klenke ([email protected])

bool Event::IsRemote

(

)

Description:

This method will return true if the object was set to a remote event using the SetToRemote() method.

Note:

If you passed -1 as the index to SetToRemote() then this method will return false.

Returns:

true is set to a remote event.

Author:

Arno Klenke ([email protected])

status_t Event::GetRemoteInfo	(	proc_id *	pnProcess,
		port_id *	phPort,
		int *	pnMessageCode,
		os::String *	pzDesc
	)

Description:

This method will return 0 if this event was successful. The provided variables will then contain information about the event.

Returns:

0 if successful.

Author:

Arno Klenke ([email protected])

status_t Event::GetRemoteChildren

(

std::vector< os::String > *

pacList

)

Description:

This method will fill the provided list with the names of all children of an event node, e.g. callling this for an event string called class/Mail might result in the list containing entries like CreateNewMail.

Note:

You should call SetToRemote() if the index -1 before because not every event node might contain its own events. The provided list is not cleared by this method.

Returns:

0 if successful.

Author:

Arno Klenke ([email protected])

status_t Event::SetMonitorEnabled	(	bool	bEnabled,
		os::Handler *	pcTarget = NULL,
		int	nMessageCode = -1
	)

Description:

With this method you can enable or disable a monitor to an id string. Please note that the monitor will cover all events with the specified id string, the index does not matter. You need to call SetToRemote() before you can use this feature. The received message will contain a boolean field "event_registered", "event_unregistered" or none if it is a notification message.

Note:

You can also add '*' to the end of the string to monitor events that start with this string.

Parameters:

	bEnabled	- Enables/Disables the monitor.
	pcTarget	- Handler that should receive the monitor messages.
	nMessageCode	- The code of the message that will be sent to the looper. The message can include additional data provided by the caller.

Returns:

0 if successful.

Author:

Arno Klenke ([email protected])

bool Event::IsMonitorEnabled

(

)

Description:

This method will return true if the event is monitored.

Returns:

true is set to a remote event.

Author:

Arno Klenke ([email protected])

status_t Event::PostEvent	(	Message *	pcData,
		Handler *	pcReplyHandler = NULL,
		int	nReplyCode = M_REPLY
	)

Description:

This method will post an event. If this object is set to an remote event using SetToRemote() then the message will be sent to the application that has registered the call. If you have registered the event using the Register() method then the message will be sent to all applications that have set a monitor to this id string.

Parameters:

	pcData	- Data that will be submitted.
	pcReplyHandler	- Handler for the reply message. Can be NULL for remote calls and has to be NULL if you have registered the event.
	nReplyCode	- The code for the reply.

Returns:

0 if successful.

Author:

Arno Klenke ([email protected])

status_t Event::GetLastEventMessage

(

os::Message *

cReply

)

Description:

This method will return the last message that has been sent by an event object to its monitors. This can be used to create a "data storage" in the appserver.

Note:

If you have called SetToRemote() with index -1 then the supplied message will itself contain messages with the code "last_message" and the content of every last message of events with the same id string.

Parameters:

pcReply

- The message content will be copied to this message.

Returns:

0 if successful.

Author:

Arno Klenke ([email protected])

---