Messages

MESSAGE CLASS

The program has many individual pieces (DEVICES) that have to communicate with each other. The Message class defines the form of these messages. A message is generated through a 'factory' call to Message::future_Message(...).

The message has a source and destination address (TASK_NAME), identifies the action to be taken (EVENT_*), and two signed integers for passing settings or values as needed.

The Message class is used to create a standardized message that can pass directives and/or information between drivers (See DEVICE DRIVER). The SwitchBoard class defines a callback which is used to deliver these messages as needed. See the SwitchBoard page for more information

Each message represents an instruction or 'event' that the driver should implement (in some cases, the message might only contain status information from the driver that generated it).

The Message class is used to generate a message, which can then be sent. (Through the switchboard. The Switchboard is responsible for delivering the message to its proper destination (i.e.:'device' class). It has the following fields:

CONTENT:

• TASK_NAME destination- This is an enum class defined in Message.h. It defines the name of the device that we should deliver this message to.
• TASK_NAME response - This is an enum class defined in Message.h. If a response is indicated (e.g.: Rotate - what position are you at?), then this is where the response will be sent.
• int event - This defines what we want the device to do. See the EVENTS section below.
• int val - The value we want to set or report. The meaning of this value is defined by the Driver.
• int rate - A second value we want to set or report. The meaning of this value is defined by the Driver.

EVENTS:

Events define what action should be taken when a given message is received. There are some pre-defined events in the 'Message' class which are identified by a number from 1 thru 10. In addition, each device driver can define its own events, using values greater than 10 - these will be documented in the *.h file for each driver. The pre-defined events in the Message class are:

• EVENT_ACTION_NONE (Deprecated - not implemented) This is sent to a driver to means the driver was registered, and is now active.
• EVENT_ACTION_REGISTERED (Deprecated - not implemented) When sent means task is now registered. hutdown.
• EVENT_ACTION_SHUTDOWN (Deprecated - not implemented) the device is being shut down.
• EVENT_ACTION_SETVALUE This indicates the device should set itself to a particular value.

LIFETIME OF A MESSAGE:

• When snd(msg) is called to send an event, the msg is no longer available to the calling program - the Switchboard owns it (and its memory). (The switchboard will take care of freeing its memory-see below).
• The destination is looked up, and if it has been registered the message is delivered to the registered driver through its 'callback' (see DEVICE DRIVER. If not, the message is simply deleted.
• Once the callback completes, the message is then deleted (note that the driver callback routine is expected to save any information from the msg that it may need longer-term.