Other Event Broker Activities

Although the event broker's primary activity is monitoring pod table events for listeners, it performs other activities such as checking on connected listeners and pods, finding out where the focus lies, and controlling individual pods, such as stereoscopic glasses and audio controllers.

Getting Lists of Listeners and Connected Pods

There are many times when a task needs a list of pods connected to the control port or listeners connected to the event broker. There are two flavors of messages that retrieve this kind of information: EB_DescribePods asks for a list of connected pods; EB_GetListeners asks for a list of connected listeners.

Asking for a List of Connected Pods

When a task uses an EB_DescribePods message to ask the event broker for a list of connected pods, the message data block contains only the EventBrokerHeader data structure specifying the flavor EB_DescribePods. The message sent to the event broker should be a buffered message, created with CreateBufferedMsg(), which contains sufficient room to hold the complete list of connected pods.

Reading a Returned List of Connected Pods

When the event broker replies to an EB_DescribePods message, it turns the message into an EB_DescribePodsReply message. The message's data buffer contains a list of pods currently attached to the control port. Those pods are described in the data structure PodDescriptionList, which is defined as follows:

typedef struct               PodDescriptionList
{
  EventBrokerHeader           pdl_Header;
  int32                       pdl_PodCount;
  PodDescription              pdl_Pod[1];
} PodDescriptionList;

pdl_Header is an EventBrokerHeader data structure set to the message flavor EB_DescribePodsReply.
pdl_PodCount contains the number of pods described in the next field.
pdl_Pod[] is an array of pod descriptions, with one element for each pod currently attached to the control port. Each pod description is contained in the data structure PodDescription, defined as follows:

typedef struct PodDescription
{
  uint8            pod_Number;
  uint8            pod_Position;
  uint8            rfu[2];
  uint32           pod_Type;
  uint32           pod_BitsIn;
  uint32           pod_BitsOut;
  uint32           pod_Flags;
  uint8            pod_GenericNumber[16];
  Item             pod_LockHolder;
} PodDescription;

pod_Number gives the unique and unchanging pod number of the pod.
pod_Position gives the position of the pod in the control port daisy chain. It is an integer from 1 to the total number of pods on the control port.
pod_Type lists the native pod type of the pod, that is, the specific type of device attached to the daisy chain (not the generic type).
pod_BitsIn and pod_BitsOut give the number of bits shifted into the pod during the control port data stream for each video field, and the number of bits shifted out of the pod during each data stream.

pod_Flags, contains flags that show the generic device type (or types) that the pod contains. These flags, shown in Table 4, occupy the left-most bits of the pod_Flags word.

Table 1:  Flag constants used for the pod_Flags field. 
-----------------------------------------------
Flag Constant      |Hex Value     |Count From  
                   |              |Left-Most   
                   |              |Bit         
-----------------------------------------------
POD_IsControlPad   |0x80000000    |0           
-----------------------------------------------
POD_IsMouse        |0x40000000    |1           
-----------------------------------------------
POD_IsGun          |0x20000000    |2           
-----------------------------------------------
POD_IsGlassesCtlr  |0x10000000    |3           
-----------------------------------------------
POD_IsAudioCtlr    |0x08000000    |4           
-----------------------------------------------
POD_IsKeyboard     |0x04000000    |5           
-----------------------------------------------
POD_IsLightGun     |0x02000000    |6           
-----------------------------------------------
POD_IsStick        |0x01000000    |7           
-----------------------------------------------
POD_IsIRController |0x00800000    |8           
-----------------------------------------------

pod_GenericNumber is an array of 16 unsigned 8-bit values. These values correspond to the bits of the pod_Flags field: pod_GenericNumber[0] corresponds to flag bit 0, POD_IsControlPad; pod_GenericNumber[1] corresponds to the first flag bit, POD_IsMouse; and so on. The value in each element of the array stores the rank of this pod in the order of all other identical generic devices connected to the serial port. For example, if pod_GenericNumber[2] contains a 4, then the pod contains a generic gun that is the fourth generic gun connected to the serial port.
pod_LockHolder gives the item number of the task that has this pod locked for its exclusive use. If this field is set to 0, then the pod is unlocked. Pod locking is not currently implemented, so this field should not be used.

Asking for a List of Connected Listeners

When a task asks for a list of connected listeners, it uses an EB_GetListeners message, whose data block contains only the EventBrokerHeader data structure specifying the flavor EB_GetListeners. Messages used for this purpose must be created with CreateBufferedMsg() in the same way as messages used with the EB_DescribePods command. CreateBufferedMsg() is described in Creating a Configuration Message.

Reading a Returned List of Connected Listeners

When the event broker replies to an EB_GetListeners message, it turns the message into an EB_GetListenersReply message. The message buffer contains a list of listeners currently connected to the event broker. The list is contained in the data structure ListenerList, defined as follows:

typedef struct ListenerList
{
  EventBrokerHeader                        ll_Header; /* { EB_GetListenersReply } */
  int32                        ll_Count;
  struct {
    Item                        li_PortItem;
    enum ListenerCategory                        li_Category;
  } ll_Listener[1];
} ListenerList;

ll_Header is an EventBrokerHeader structure set to the message flavor EB_GetListenersReply.
ll_Count contains the number of listeners described in the next field.
ll_Listener is an array of listener descriptions with one element for each listener currently connected to the event broker. Each listener element contains these fields:

li_PortItem contains the item number of the listener's reply port
li_Category gives the listener's focus-interest category

Working With Input Focus

It is often important for a listener to know which task currently has the input focus or to be able to change the input focus from one task to another without user intervention. The event broker can handle both of these requests.

Finding the Current Focus Holder

To find the current focus holder, a listener can inquire with an EB_GetFocus message. Its data block is an EventBrokerHeader data structure set to the message flavor EB_GetFocus.

When the event broker receives an EB_GetFocus message, it gets the item number of the task currently holding the focus, writes that value in the error field of the message, and returns the message to the task. The task receiving the message reads the current focus holder's item number from the error field. The error field will contain a negative number (an error code) if the operation failed.

Setting the Current Focus Holder

Warning: Although the event broker currently allows any user task to set the current focus holder, in the future this request may restricted to only privileged tasks.

To move the focus from one task to another without input from the user, a listener can use an EB_SetFocus message. The data block for this message uses the SetFocus data structure, defined as follows:

typedef struct SetFocus
{
  EventBrokerHeader sf_Header; /* { EB_SetFocus } */
  Item            sf_DesiredFocusListener;
} SetFocus;

sf_Header is an EventBrokerHeader data structure set to the message flavor EB_SetFocus.
sf_DesiredFocusListener is the item number of the task to which the event broker should give the focus.

When the event broker receives the message, it changes the input focus to the requested task and writes that task's item number into the error field of the message. It returns the message to the sending task. That task can now read the error field to get the item number of the focus-holding task (if successful) or an error code (if unsuccessful).

Commanding a Pod

Sometimes a task may want to control a pod through the event broker. For example, a task may wish to alternate lens opaqueness in a pair of stereoscopic glasses, or mute the sound coming through an audio controller. To issue commands to a pod, the task uses a message of the flavor EB_IssuePodCmd. It accompanies the message with a data block that uses the PodData data structure, defined as follows:

typedef struct PodData
{
  EventBrokerHeader                        pd_Header;
  int32             pd_PodNumber;
  int32             pd_WaitFlag;
  int32             pd_DataByteCount;
  uint8             pd_Data[4];
} PodData;

pd_Header is an EventBrokerHeader data structure set to the message flavor EB_IssuePodCmd.
pd_PodNumber gives the pod number of the pod to which the command is sent.
pd_WaitFlag can be set to either 1 or 0. If set to 1, it asks the event broker to send the command to the pod and reply immediately. If set to 0, it asks the event broker to send the command to the pod, wait for the command to finish execution, and then reply to command message.
pd_DataByteCount gives the size in bytes of the pd_Data field that follows.
pd_Data is an array of bytes that contains the command sent to the pod. The first element of the array (element 0) contains the generic device class of the pod to which the command is sent; the second element (element 1) contains the command subcode, which is specific to the generic class in the first element. If the command defined by these two bytes requires extra data, that data goes into the elements of the array listed below.

Generic Device Class

The include file event.h currently defines the following constants to specify generic device classes:

GENERIC_ControlPad - a controller pad.
GENERIC_Mouse - a mouse.
GENERIC_Gun - a photo-optic gun.
GENERIC_GlassesCtlr - a stereoscopic glasses controller.
GENERIC_AudioCtlr - an audio controller.
GENERIC_Keyboard - a keyboard.
GENERIC_LightGun - a light gun.
GENERIC_Stick - a joystick.
GENERIC_IRController - a infrared controller pad (wireless).

The array element pd_Data[0] should hold the constant appropriate to the commanded pod.

Audio Controller Subcodes

The audio controller accepts commands defined by audio controller subcodes. At present, Portfolio offers one audio subcode, specified by the following constant:

GENERIC_AUDIO_SetChannels controls the output of the two stereo audio channels.

This subcode goes in the array element pd_Data[1]. It requires one byte of data following it in pd_Data[2]. This data specifies how the stereo channels are controlled. The four options, defined by the following constants, are:

AUDIO_Channels_Mute - turns off the audio output in both channels.
AUDIO_Channels_RightToBoth - feeds the right audio signal to both left and right channels.
AUDIO_Channels_LeftToBoth - feeds the left audio signal to both the left and right channels.
AUDIO_Channels_Stereo - feeds the left audio signal to the left channel and right audio signal to the right channel.

Glasses Controller Subcodes

The stereoscopic glasses controller accepts commands defined by glasses controller subcodes. At present, Portfolio offers one glasses subcode, specified by the following constant:

GENERIC_GLASSES_SetView - controls the opacity of each lens in a pair of stereoscopic glasses.

This subcode goes into the array element pd_Data[1]. It requires two bytes of data following it in pd_Data[2] and pd_Data[3]. The first of the two data bytes controls the left lens of the glasses, the second byte controls the right lens. The four possible values for each lens, defined by the following constants, are:

GLASSES_AlwaysOn - keeps the lens clear during both odd and even video fields.
GLASSES_OnOddField - turns the lens clear every odd video field, and turns it opaque every even field.
GLASSES_OnEvenField - turns the lens clear every even video field, and turns it opaque every odd field.
GLASSES_Opaque - turns the lens opaque during both odd and even video fields.

Lightgun Controller Subcode

Currently, Portfolio offers one light gun controller subcode, which is specified by the following constant:

GENERIC_LIGHTGUN_SetLEDs controls the setting of LEDs on the light gun. The setting of up to eight LEDs is supported, although the stock light gun has only two.

The possible options, defined by the following constants, are:

LIGHTGUN_LED1 - controls the setting of the first LED on the light gun.
LIGHTGUN_LED2 - controls the setting of the second LED on the light gun.

The Event Broker's Reply to a Command

After the event broker processes a pod command message, it returns the message to the sending task to report on the command execution. The returned message is of the flavor EB_IssuePodCmdReply, and contains a reply portion that is a negative number if there was an error executing the command, or is 0 or a positive number if the command execution was successful.