Connecting a Task to the Event Broker

Before a task can work with the event broker, it must connect to the event broker by sending a message that requests connection as a listener. To do so, the task sends a message of the flavor EB_Configure, using Portfolio's standard message-sending procedure. The message also specifies input focus, and indicates the event types in which the task is interested.

Creating a Message Port

Before creating a configuration message, a listener task must create its own message port to use as a reply port where the event broker will send messages. To do so, the listener uses the CreateMsgPort()call, which returns the item number of the new message port.

Creating a Configuration Message

After a listener task creates a message port, it must create a message using CreateMsg() or CreateBufferedMsg(). Both calls accept a string that names the message, supplies an optional priority number for the message, and provides the item number of the listener message port. CreateBufferedMsg() also takes the size of the buffer to allocate with the message. Both calls return the item number of the newly created message.

Creating a Configuration Block

To turn the newly created message into a configuration request, the listener task must create a configuration data block, which consists of the ConfigurationRequest structure, shown in Example 1.

Example 1: ConfigurationRequest structure.

typedef struct ConfigurationRequest
{
  EventBrokerHeader                            cr_Header;                     /* { EB_Configure } */
  enum ListenerCategory                            cr_Category;                      /* focus, monitor, or 
                                                 /* hybrid */
  uint32                            cr_TriggerMask[8]; /* events to trigger on */
  uint32                            cr_CaptureMask[8]; /* events to capture */
  int32                            cr_QueueMax;                       /* max # events in 

                                                 /* transit */
  uint32                            rfu[8];                           /* must be 0 for now */
} ConfigurationRequest;

The listener task must fill in the following fields to set the parameters of its configuration request:

cr_Header is an EventBrokerHeader data structure in which the event flavor EB_Configure must be set.
cr_Category defines the listener type of input focus. It has four possible values:

LC_FocusListener sets the task to be a focus-dependent listener. It must have the focus to receive any events.
LC_FocusUI sets the task to be a focus-interested listener. It must have the focus to receive user interface events, but gets all other event types regardless of focus.
LC_Observer sets the task to be a focus-independent listener. It gets all event types regardless of focus.
LC_NoSeeUm sets the task to ignore all events completely, the equivalent of not connecting to the event broker.

cr_TriggerMask and cr_CaptureMask contain the event masks that specify events in which the task is interested. The trigger mask specifies each event type that will trigger the event broker to notify the task; the capture mask specifies each event type that the event broker reports on whenever it notifies the task of an event triggering. These masks are discussed in The Event Broker Trigger Mechanism.
cr_QueueMax specifies the maximum number of event reports that the event broker posts at any one moment in the task's event queue. This value can be set to the constant EVENT_QUEUE_MAX_PERMITTED, which sets the currently defined maximum number of events in the queue (20 in this release), or the constant EVENT_QUEUE_DEFAULT, which sets the currently defined default number of events (three in this release). The queue must have a minimum depth of at least two events.
The rfu field is reserved for future use, and currently must be set to 0.

Event Types

The 256 different event types available through the event broker are divided into two main bodies:

System events. 128 system-defined generic events.
Custom events. 128 task-defined events primarily used for communicating events in one event broker listener to other listeners. Custom events are not currently implemented.

Both system events and custom events are divided into two types that are defined by the way the event broker reports them to focus-interested tasks:

UI events, which are not reported to a focus-interested task if a task does not hold the focus. The event broker provides 64 system and 64 custom UI events.
Non-UI events, which are reported to a focus-interested task even if the task does not hold the focus. The event broker provides 64 system and 64 custom non-UI events.

Table 1 shows how the 256 different bit values in a bit mask are divided into system and custom events, and then UI and non-UI events. Custom event types are not supported in this release of Portfolio.

Table 1:   Flag Bit constants defined in event.h.
-----------------------------------------------------------------
System UI Event Type Constants  |Event Definition                
-----------------------------------------------------------------
EVENTBIT0_ControlButtonPressed  |A controller pad button was     
                                |pressed.                        
-----------------------------------------------------------------
EVENTBIT0_ControlButtonReleased |A controller pad button was     
                                |released.                       
-----------------------------------------------------------------
EVENTBIT0_ControlButtonUpdate   |A controller pad button was     
                                |pressed or released, or control 
                                |button information may be lost  
                                |in an event queue overflow.     
-----------------------------------------------------------------
EVENTBIT0_ControlButtonArrived  |Data from a controller pad      
                                |button has arrived (it arrives  
                                |every field).                   
-----------------------------------------------------------------
EVENTBIT0_MouseButtonPressed    |A mouse button was pressed.     
-----------------------------------------------------------------
EVENTBIT0_MouseButtonReleased   |A mouse button was released.    
-----------------------------------------------------------------
EVENTBIT0_MouseUpdate           |A mouse button was pressed or   
                                |released, the mouse has moved,  
                                |or mouse info may be lost in an 
                                |event queue overflow.           
-----------------------------------------------------------------
EVENTBIT0_MouseMoved            |A mouse has moved.              
-----------------------------------------------------------------
EVENTBIT0_MouseDataArrived      |Data from a mouse has arrived   
                                |(it arrives every field).       
-----------------------------------------------------------------
EVENTBIT0_GunButtonPressed      |A gun button was pressed. This  
                                |is not currently implemented.   
-----------------------------------------------------------------
EVENTBIT0_GunButtonReleased     |A gun button was released. This 
                                |is not currently implemented.   
-----------------------------------------------------------------
EVENTBIT0_GunUpdate             |A gun button was pressed or     
                                |released, or gun button         
                                |information may be lost in an   
                                |event queue overflow. This is   
                                |not currently implemented.      
-----------------------------------------------------------------
EVENTBIT0_GunDataArrived        |Data from a gun has arrived (it 
                                |arrives every field). This is   
                                |not currently implemented.      
-----------------------------------------------------------------
EVENTBIT0_KeyboardKeyPressed    |A keyboard key was pressed. This
                                |is not currently implemented.   
-----------------------------------------------------------------
EVENTBIT0_KeyboardKeyReleased   |A keyboard key was released.    
                                |This is not currently           
                                |implemented.                    
-----------------------------------------------------------------
EVENTBIT0_KeyboardUpdate        |A keyboard key was pressed or   
                                |released, or keyboard           
                                |information may be lost in an   
                                |event queue overflow. This is   
                                |not currently implemented.      
-----------------------------------------------------------------
EVENTBIT0_KeyboardDataArrived   |Data from a keyboard has arrived
                                |(it arrives every field). This  
                                |is not currently implemented.   
-----------------------------------------------------------------
EVENTBIT0_CharacterEntered      |A character was entered. This is
                                |not currently implemented.      
-----------------------------------------------------------------
EVENTBIT0_GivingFocus           |This task was given focus.      
-----------------------------------------------------------------
EVENTBIT0_LosingFocus           |This task lost focus.           
-----------------------------------------------------------------
EVENTBIT0_LightGunButtonPressed |A light gun button was pressed. 
-----------------------------------------------------------------
EVENTBIT0_LightGunButtonReleased|A light gun button was released.
-----------------------------------------------------------------
EVENTBIT0_LightGunUpdate        |A light gun button was pressed  
                                |or released, or light gun button
                                |information may be lost in an   
                                |event queue overflow.           
-----------------------------------------------------------------
EVENTBIT0_LightGunFireTracking  |Data from a light gun is being  
                                |tracked.                        
-----------------------------------------------------------------
EVENTBIT0_LightGunDataArrived   |Data from a light gun has       
                                |arrived (it arrives every       
                                |field).                         
-----------------------------------------------------------------
EVENTBIT0_StickButtonPressed    |A joystick button was pressed.  
-----------------------------------------------------------------
EVENTBIT0_StickButtonReleased   |A joystick button was released. 
-----------------------------------------------------------------
EVENTBIT0_StickUpdate           |A joystick button was pressed or
                                |released, or joystick button    
                                |information may be lost in an   
                                |event queue overflow.           
-----------------------------------------------------------------
EVENTBIT0_StickMoved            |A joystick has moved.           
-----------------------------------------------------------------
EVENTBIT0_StickDataArrived      |Data from a joystick has arrived
                                |(it arrives every field).       
-----------------------------------------------------------------
EVENTBIT0_IRKeyPressed          |An IR key was pressed and a     
                                |button code is returned. This is
                                |device specific. This is not    
                                |currently implemented.          
-----------------------------------------------------------------
EVENTBIT0_IRKeyReleased         |An IR key was released and a    
                                |button code is returned. This is
                                |device specific. This is not    
                                |currently implemented.          
-----------------------------------------------------------------

Table 2 shows the flag bit constants defined in event.h for the system events, along with the meaning for each of the event types. These event type constants define flags for system-defined events, each of which can occur during a single control port polling.

Table 2:  Event type constants that define flags for system-defined events. 
---------------------------------------------------------------
System Non-UI Event Type      |Event Definition                
Constants                     |                                
---------------------------------------------------------------
EVENTBIT2_DeviceOnline        |Media was inserted in a device. 
---------------------------------------------------------------
EVENTBIT2_DeviceOffline       |A device was removed.           
---------------------------------------------------------------
EVENTBIT2_FilesystemMounted   |A file system was mounted.      
---------------------------------------------------------------
EVENTBIT2_FilesystemOffline   |A file system went off-line.    
---------------------------------------------------------------
EVENTBIT2_FilesystemDismounted|A file system was dismounted.   
---------------------------------------------------------------
EVENTBIT2_ControlPortChange   |A new device was plugged into or
                              |disconnected from the control   
                              |port.                           
---------------------------------------------------------------
EVENTBIT2_PleaseSaveAndExit   |This task was requested to save 
                              |current status and exit.        
---------------------------------------------------------------
EVENTBIT2_PleaseExitImmediatel|This task was requested to exit 
y                             |immediately.                    
---------------------------------------------------------------
EVENTBIT2_EventQueueOverflow  |This task's event queue has     
                              |overflowed and the task has lost
                              |events.                         
---------------------------------------------------------------

Setting the Trigger and Capture Masks

Each of the masks in the ConfigurationRequest data structure is an 8-element array of 32-bit words that provides 256 bits, 1 bit for each event type. To set a mask, the task logically ORs the desired constants defined for each word of the array, and stores the results in the appropriate word. The constant name identifies the appropriate word for storage. For example, all the desired flag constants starting with EVENTBIT0 must be logically ORed and then stored in word 0 of the array. All the desired flag constants starting with EVENTBIT2 must be logically ORed and then stored in the second word of the array.

Sending the Configuration Message

Once the ConfigurationRequest data structure has been created and filled in, the listener task must send the message to the event broker. To do this, the task first must find the event broker message port using the FindMsgPort() call, as shown in Example 2.

Example 2: FindMsgPort().

{
Item ebPortItem;

    ebPortItem = FindMsgPort(EventPortName);
    if (ebPortItem < 0)
    {
        /* big trouble, the event broker can't be found! */
    }
}

After the listener task has the event broker message port item number, the task sends its configuration message using SendMsg():

SendMsg(ebPortItem, msg, &configuration, sizeof(configuration));

The SendMsg() call accepts four arguments: the item number of the event broker port, the item number of the message the task has created, a pointer to the ConfigurationRequest data structure the task has initialized, and the size of that data structure.

When the event broker receives the configuration message, it adds the task as a listener. The event broker reads the reply port contained in the message and uses that port whenever it needs to communicate with the listening task. The event broker also reads the ConfigurationRequest data structure and sets up the listener's configuration accordingly.

Receiving the Configuration Reply Message

When the event broker finishes processing the configuration message, it changes the message to a configuration reply message. That message contains a pointer to a single data structure: an EventBrokerHeader with the value EB_ConfigureReply. The event broker returns the message to the task requesting configuration. The receiving task checks the configuration message's result field (msg_Result, which is cast to an Err type) to see if the operation was successful or not. If the value is a negative number, it is an error code, and the configuration was not successful (the task was not connected). If the value is 0 or a positive number, the configuration was successful and the task is connected.