View source for Message Interceptors

[[Category: Programmer's Guide]]
==Basics==
This allows your device to tell [[DCERouter]] that it wants to get copies of all messages that meet a certain criteria.  For example, a device may want to work with the lights and get copies of all messages going to a light, or another may want a copy of all events from the disk drive.  When you register a message interceptor with [[DCERouter]] you specify 6 numeric parameters which limit the messages you will receive.

For each you can specify 0, which means match all, or a non-zero integer which means only match messages which match that criteria.  If you register a message interceptor with all 0's, you will get all messages.  Be sure to provide restrictions so you only get the messages you really need.  

[[DCERouter]] processes lots of messages, so if you register a message interceptor that is too vague, you could get flooded.  For example, the media players typically broadcast a message every second with an updated time code.  If you register a message interceptor to grab all messages from a media device, you would get time-code messages every second.  

Note that parameters act as 'AND' not 'OR'.  If you register for DeviceCategory="Media Player" and MessageID="Play Media" you will get messages that are both going to Media Players AND have an ID of Play Media.  If you wanted to get messages that go either to Media Players OR have an ID of Play Media, then register 2 separate interceptors.
==Parameters==
===From (PK_Device):===
If specified you will only get messages from this particular device ID.
===To (PK_Device):=== 
If specified you will only get messages to this particular device ID.
===Template (PK_DeviceTemplate):=== 
If specified you will only get messages to devices of this particular DeviceTemplate.  Note that if the message type is an Event, that is coming from a device rather than going to it, the Router will look at the template of the From device.
===Category (PK_DeviceCategory):=== 
If specified you will only get messages to devices of this particular DeviceCategory.  Note that if the message type is an Event, that is coming from a device rather than going to it, the Router will look at the category of the From device.
===MessageType:===
The type of message, as defined in the source file DCE/Message.h. The 2 most common message types are 1 and 2 (MESSAGETYPE_COMMAND=1, MESSAGETYPE_EVENT=2). But you can also receive message of type 7 (MESSAGETYPE_SYSCOMMAND=7) if DCERouter is reloaded. In this case MessageID is 1 and it means 'Reload'
===MessageID:===
The ID of the message, as defined in the source file DCE/Message.h.  The ID depends on the message type.  Event ID's are defined in the table 'Event' in pluto_main.  Command ID's are defined in the table 'Command'.  In [[LinuxMCE Admin Website]] you can choose 'Advanced', 'DCE' to see the command and event ID's.  If you specify an ID, you should also specify a type.  A command ID of 19 is "Set House Mode" whereas an event ID of 19 is "Watching Media".  So if you only specify the ID of 19, and leave MessageType as 0, your interceptor will get both "Set House Mode" commands and "Watching Media" events.
==Register a Message Interceptor==
To register a message interceptor, call the RegisterMsgInterceptor member function, with the Command_Impl class that all plugins and devices are derived from:
<pre>RegisterMsgInterceptor( ( MessageInterceptorFn )( &Media_Plugin::MediaInserted ), 0, 0, 0, 0, MESSAGETYPE_EVENT, EVENT_Media_Inserted_CONST );</pre>
This means the member function Media_Plugin::MediaInserted, which must match the definition of MessageInterceptorFn, will be called whenever a device fires a "Media Inserted" Event.
==Sending Message Manually==
If you are not using the DCE C++ library, you can send a message to [[DCERouter]] manually to register the message interceptor, and then you will get intercepted messages encapsulated within another message.  To register a message interceptor this way, send a message to [[DCERouter]], which is always device ID -1000 (#define DEVICEID_DCEROUTER -1000) with a MessageType of 8 (MESSAGETYPE_REGISTER_INTERCEPTOR=8).  The parameters for the message are the 6 interceptor parameters:
<pre> enum { PARM_FROM=1, PARM_TO, PARM_TEMPLATE, PARM_CATEGORY, PARM_MESSAGE_TYPE, PARM_MESSAGE_ID };</pre>

Here is the same interceptor sent by hand, not using the framework:
    <pre>   Message *pMessage = new Message(m_dwPK_Device,DEVICEID_DCEROUTER,PRIORITY_NORMAL,
	     MESSAGETYPE_REGISTER_INTERCEPTOR,2,
	     PARM_MESSAGE_TYPE,MESSAGETYPE_EVENT,
	     PARM_MESSAGE_ID,EVENT_Media_Inserted_CONST);
       QueueMessageToRouter(pMessage);</pre>
In this case you will receive all intercepted messages embedded within a message of type: MESSAGETYPE_MESSAGE_INTERCEPTED.  The actual intercepted message will be the single embedded message in m_vectExtraMessages.