Instant Messaging Plugin Template

Opening the web admin, and going to Advanced > Configuration > Device Templates, We pick my manufacturer, LOCALE|Concept, and pick the Pluto General Plugins category, and click Add Device Template.

Adding our Command Group - Instant Messaging Commands

After this is done, I specify that this is a device that will be implemented by C++ code.

That fills in the blanks, and brings up the following display, of which, the following screen snippet is most relevant:

Note that I have checked the "Is a Plugin" and once I did this, it automatically added a Controlled by Category:DCERouter entry. This happens the moment that you check this box, and goes away when you uncheck it. There is no need to manually add it.

Also note that the Implements DCE box is checked, and there is nothing in the command line box. If this is checked, and there is nothing in the command line box, the system assumes that the DCE Device command name is the same as the name of the plugin, with any spaces substituted by underscores. (_)

I hit save at this point, to get the device template into the system, but I now need to define the commands that this plugin will need.

Scrolling down, notice there is a link for Create Command Group, this needs to be clicked, as the above three command groups do not contain relevant commands that we want to implement in our template.

Notice here the Category drop down. All this signifies is where this command group will be automatically presented as a possible group of commands to add to a particular device. I have selected the Pluto General Plugins device so that any device that is in this category AND its descendents will see this command group added. This is used by various system parts too to do intelligent database queries to see which plugins to iterate over, etc. I could have just as easily made a new category here.. and I may in the future, but I didn't this time around.. so.. I select, enter a meaningful name for this group of commands, and go back.

A command group, to reiterate, is nothing more than a group of commands together. It allows you to quickly define groups of common commands that a device may implement.

Once this is done. Take a look at the resulting difference in the command group checkboxes. Our command group is now here, but for now, it's empty.

Adding Commands to the Command Group

Clicking Edit Commands, brings up a window where the command groups can be edited.

Each command group has a set of commands. These commands are designed to be consistent throughout the entire system, so the point is to try to create commands that can be re-used as much as possible. Normally, new commands would probably not need to be created, you can try to look through the existing commands and add them in via the pull-down menu. However, in my case, I need to add two new commands:

• Set Presence - To set the presence of a given user or all users in the house
• Send Message - To send an instant message to another person.

You may have noticed that both of these commands were specified in the Instant Messaging in LinuxMCE page for both the Plugin and players. They are indeed defined in both, however the scope of both are different. Whereas with the plugin, it affects all accounts of a specific user, with each device, it only affects a given transport for a given user. So even though that a given command will be used in two different groups, they differ in scope, and thus the code for them is different. Typically, the orbiter will interact with the Plugin, and the Plugin will send the necessary commands to the individual devices.

Send Instant Message

So we now add our first command to the group.

And as we add this command, currently there are no parameters. So we need to add them, I am trying to use existing command parameters as much as I can, but if something didn't exist, I could also define it here.

I use the PK_Users command parameter to specify a given user. This corresponds to a row in the Users table, which is the list of people in the house. This is the From parameter.

I use the Address parameter to determine where to send this to. I will figure out what to put here later, but for now, I know I just need a way to specify a string for a to address.

I use the Options parameter as a sort of catch-all for any special parameters I wish to send along with the message. I will figure out what to do with this later.

Saving this parameter, This command is now complete.

Set Presence

In addition, I add a Set Presence command, so that Online/Offline/DND/Away status can be set. The parameters are very similar:

• PK_Users - so I can determine which user to set presence.
• Options - The presence to set. Will be a single word. online, offline, away, dnd, etc

Once this is done, This command group is now complete.

And with this, the first pass of the Instant Messaging Plugin is now complete.

A Note About events

You may have noticed, that I didn't specify any events in the Events section of the plugin. That is because this plugin does not emit any events. Adding events to the events section of a device template sets things up so that you can fire an event with EVENT_EventName(); .... If I need to do this later from within the plugin, I will add it. But based on my observations with the other plugins, most do not emit events themselves, but rather consume them with an event interceptor.

Back to Instant Messaging in LinuxMCE or forward to the Instant Messaging Device Template

-Thom