Tutorial - HelloFunc


Overview
Taking the previous tutorial a few small steps further we will create a messiah function (Function Module) that will also display a message box that says "Hello World!".
Step 1 Create Project
Following the procedures from Concepts - Compiling, create a new project for whatever compiler you're using. Name this project "HelloFunc".
Step 2 Create Files
Since this is going to be such a simple plugin we're going to just put everything in one source file. Go ahead and create a source file called PluginMain.c.
Step 3 Includes
We will need to include messiah_main.h, as we will in all plugins, but before we do this we need to define two symbols. The first is _MESSIAH_FULL_API, this indicates that we want to include the headers for the entire API. Although including the whole thing isn't really nescessary, it's easy and that's what this example's all about. Next we'll define _MAINPLUGIN_FILE, a symbol that should always be defined in the PluginMain.c file for all plugins. The symbol, of course, should be defined before messiah_main.h is included. So far here's what we've got:

#define _MESSIAH_FULL_API
#define _MAINPLUGIN_FILE

#include <messiah_main.h>
Step 4 Callback Prototype
We'll need to create a callback that messiah can call whenever the user executes our Function Module. Use the FX_EXPFUNC() macro to declare the function as follows:

FX_EXPFUNC( Exec, void, data );
This macro expands to the following:

FXint Exec( FX_Arg *return_arg, void *data);
We'll talk more about this function in a moment.
Step 5 Plugin Entry
Now we need to create our plugin's entry point and register our Function Module with messiah. The entry point function takes the form:

_pluginEntry
{
        //...
        return FX_PLUGIN_OK;
}
Note that _pluginEntry is a macro that expands to the signature of messiahEntry().
Before we can do any of the registration we need to retrieve all of the components of the messiahAPI that we will use as well as do some housekeeping. Fortunatly this is all handled with one macro:

_MESSIAH_PLUGIN_ALL("Hello_Func");
The first part of the registration process is describing the Function Module in English so that when the user selects it from a list of Function Modules he will get information about what the Function Module does.

fxFunctionDescription("My first messiah plugin!", FX_NOFLAG);
Next we'll actually register the Function Module:

fxFunctionRegister("HelloFunc", FX_FUNCCLASS_GENERAL, &Exec, NULL, FX_ARG_INT, FX_NOFLAG);
"HelloFunc" will be the name of the Function Module as it appears to the user in messiah. The second argument indicates the classification of the function, this allows functions to be grouped based on their functionality. The third argument is the address of our callback that we just declared. We're telling messiah that this Function Module will return an int by passing FX_ARG_INT as the return_type.
So our completed entry function looks like:

_pluginEntry
{

        // Get all API components and do initial plugin setup
        _MESSIAH_PLUGIN_ALL("Hello_Func");

        // Describe the mfunc in English
        fxFunctionDescription("My first messiah plugin!", FX_NOFLAG);

        // Register the mfunc
        fxFunctionRegister("HelloFunc", &Exec, NULL, FX_ARG_INT, FX_NOFLAG);

        return FX_PLUGIN_OK;
}
Step 6 Plugin Exit
Type this:
Step 7 Exec Function
This is where we'll actually do the stuff our Function Module is supposed to do, in this case display a message box. Using the same declaration macro we'll define our Exec callback function now:

FX_EXPFUNC( Exec, void, data )
// FXint f(FX_Arg *return_arg, dt *ed)
{
        fxMessageSend(FX_NULLID, "HelloFunc", FX_MESSAGE_POST, "Hello World!", NULL);

        fxArgSetInt( return_arg, 0, 1);

        return FX_FUNC_OK;
The first line of this function uses the fxMessageSend() function to display the message box. The second line sets the return value for our Function Module. The return value is stored in an FX_Arg variable because Function Modules can return a variety of data types. The return_arg argument will always contain the return value at index 0, see ARG for more information about FX_Arg's. In this case we are setting the return value to 1 and returning from our callback FX_FUNC_OK indicating to the system that our Function Module executed successfully.
Summary
That's all there is to it, congratulations you've just created your first messiah plugin!


© 2003 pmG WorldWide, LLC.


www.projectmessiah.com

groups.yahoo.com/pmGmessiah

Last Updated on Thu Jul 10 04:49:37 2003