Plugin Developers Resources

So you are interested in writing a plugin for TjMSN, this page is aimed at being a basic tutorial for writing plugins for TjMSN.

Introtuction

There are three main parts to a TjMSN plugin each of which I shall explain in more detail in there relavent section, but first here is a breaf outline of the role of each section

The Loading Interface
The Loading interface takes care of installing the plugin for the first time and loading the plugin every time TjMSN is started.

The Plugin Loading Descriptor
The XML file is used by the plugin loader to determin the title and description of the plugin during the loading process and also names the class that the loader should use as the loading interface.

The Event Handler
This class is responsable for handling all of the messages from the server and for certain messages recived from the main TjMSN gui.

API Documentation

The Loading Interface

The following simple example show's the plugin loading interface for a simple plugin that has no menu or configuration, whos title is "Demo Plugin".

import com.tomjudge.TjMSN.MSNInterface;
import com.tomjudge.TjMSN.plugins.PluginLoadingInterface;
import com.tomjudge.TjMSN.plugins.PluginEventHandler;
import javax.swing.JDialog;
import javax.swing.JMenu;

public class DemoLoadingInterface implements 
            PluginLoadingInterface {

    DemoEventHandler handler;

    public DemoLoadingInterface(MSNInterface iface) {
        handler = new DemoEventHandler(iface);
    }

    public JDialog getConfigDialog() {
        return null;
    }

    public PluginEventHandler getEventHandler() {
        return handler;

    }

    public JMenu getMenu() {
        return null;
    }

    public String getTitle() {

        return "Demo Plugin";
    }
}

The Plugin Loading Descriptor

The following XML document should be placed in the META-INF directory of the jar file that the plugin is finally packaged into as the file tjmsn.xml. The first section is the DTD declaration that must always be present.
The contents of the interface tag give the full class name including package of the class that is to be used as the module loading interface.

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE tjmsnplugin [ 
<!ELEMENT tjmsnplugin (title, description?, interface)> 
<!ELEMENT title (#PCDATA)> 
<!ELEMENT description (#PCDATA)> 

<!ELEMENT interface (#PCDATA)> 
]> 
 
<tjmsnplugin> 
        <title>Demo TjMSN Plugin</title> 
        <description> 
                Demo TjMSN Plugin 

        </description> 
        <interface>DemoLoadingInterface</interface> 
</tjmsnplugin> 

The Event Handler

This simple example event handler prints "Status Changed" to the console every time the local user changes their status. I.e. Changing from away to online. More complex functionality can be achived by implimenting the rest of the functions in the interface.

 
import com.tomjudge.TjMSN.MSNInterface; 
import com.tomjudge.TjMSN.plugins.PluginEventHandler; 
 
public class DemoEventHandler extends  
            PluginEventHandler { 


    /** Creates a new instance of DemoEventHandler */ 
    public DemoEventHandler(MSNInterface iface) { 
        super(iface); 

    } 
     
    public void addGroup(String name, int id) { 
    } 
     
    public void addUser(String name, String screenName,  

            int groupId, int status) { 
    } 
     
    public void displayBlockUser(String user, String screenName) { 

    } 
     
    public void displayUnblockUser(String user, String screenName,  
            int status) { 
    } 
     

    public void imRecived(int displayId, String passport,  
            String screenName, String message, String format) { 
    } 

     
    public void removeGroup(int id) { 
    } 
     
    public void removeUser(String passport, int groupId) { 

    } 
     
    public void renameGroup(int id, String newName) { 
    } 
     
    public void setClientDisplayName(String screenName) { 

    } 
     
    public void setClientStatus(int status) { 
        System.out.println("Status changed"); 
    } 
     
    public void setDisplayMenus(int status) { 

    } 
     
    public void setDisplaySigendOut() { 
    } 
     
    public void setUserStatus(String user, String screenName,  

            int status) { 
    } 
     
    public void showError(String title, String message) { 
    } 

     
    public void userJoinedIm(int displayId, String passport,  
            String screenName) { 
    } 
     
    public void userTyping(int displayId, String passport) { 

    } 
     
    public void setClientPassport(String passport) { 
    } 
     
} 

Packaging It All Up

Assuming that in the current directory you have all your class files and a directory called META-INF containing the tjmsn.xml you need to issue the following command to create the jar file to be installed with TjMSN.

jar cvf plugin.jar Class1.class META-INF dir1

Using ant as the build tool

It is highly recomended that ANT is used to build plugins for TjMSN the following is an exmample build script for a plugin who's source code is stored in a directory call src, in the same directory as the following build.xml.

<?xml version="1.0" encoding="UTF-8"?> 
<project basedir="." default="dist" name="demo"> 
    <property name="src" location="src"/> 
    <property name="build" location="build"/>     
    <property name="dist" location="dist"/> 
     
    <target name="init"> 
        <tstamp/> 
    </target> 
     
    <target name="compile" depends="init"> 
        <javac debug="true" deprecation="true" destdir="${build}" srcdir="${src}" /> 
    </target>     
 
    <target name="dist" depends="compile"> 
        <mkdir dir="${dist}/plugin"/> 
        <mkdir dir="${dist}/plugin/META-INF"/> 
        <copy file="${src}/META-INF/tjmsn.xml" todir="${dist}/plugin/META-INF" /> 
        <copy todir="${dist}/plugin"> 
            <fileset dir="${build}"/> 
        </copy> 
        <jar destfile="${dist}/plugin.jar" basedir="${dist}/plugin"/> 
        <delete dir="${dist}/plugin"/> 
    </target> 
</project>