CONTENTS:

1. Overview
2. How to write a Plugin?
3. FAQ

Overview

EVPlugBase is an open platform for third-party developers to develop a Plugin for Palm OS. Plam OS is very succinct os system, but it's a little inconvenient. Many programers develop patchs for the system, some of them are based with Hack Master, a great platform for patchs, others are not. That was the internal reason that might crash the pilot.

After we finished EVEdit, a Hack extension, we find it is necessary to develop a new mechanism to the programers who want add some of the system patch trap in their applications. We name these applications "Plugin", different with "hack".

What is lack of the Hack Master?

1. Not solve the hack conflict with the no-hack application problem.
2. Strictly resources requirement:
• Strictly resources ID requirement, for example, patch code ID must start from 'code' resource 1000, config panel resource ID must be 2000 etc.
• Strictly require 'TRAP' resource, it is very difficult for Code warrior programer.
3. Waste of code, for example, when a patch want to replace several system trap, normally a piece of init code needed in sereral place, that will waste a lot code.
4. Inflexible programing, for example, in different versioin of OS, SysKeyboardDialog trap is different, if you want to replace it in Palm OS 1.0, you must replace the SysKeyboardDialogV10 trap, but when you try in Palm OS 2.0, you must replace SysKeyboardDialog trap, so you must provide two version for these two OS.

1. EVPlugBase can manage all Plugin written according EVPlugBase rule. No conflict each other.
2. EVPlugBase can manage all other no-hack applications that replace system traps.
3. Provide delete-protection. This prevent some users to delete Plugin or HackExtention which is actived, that will mostly cased a system crash.
4. Provide SoftPenStroke function for Plugin. It will save many time of patch programer.
5. Solve all problem that list in the lack of Hack Master.

How to write a Plugin?

1. Mechanism introduction
2. Resources requirement
3. EVPlugBase Launch Command
4. EVPlugBase API

Mechanism introduction
EVPlugBase supports four kind of patchs,

1. Hack extentions written according to Hack Master rules.
2. Passive plugins written according to EVPlugBase rules.
3. Active plugins written according to EVPlugBase rules.
4. Others applications written not according to Hack Master rules nor EVPlugBase rules.

Resources requirement
The resources requirement of a plugin in EVPlugBase is almost same as one general application.

Resource of big icon is    'tAIB', ID 1000
Resource of small icon is  'tAIB', ID 1001
Resource of plugin name is 'tAIN', ID 1000
These are same as general applications.

As far as the passive plugins, their type must be 'PLUG'.
As far as the active plugins, there is no limitation. Active plugins are actual general applications which call EVPlugBase internal functions.

PBLaunchCmd_GetInformation
PBLaunchCmd_PluginAttach
PBLaunchCmd_PluginDetach
PBLaunchCmd_ActivePluginInfoPanel
PBLaunchCmd_ActivePluginControlPanel
PBLaunchCmd_SoftPenStroke

//------------------------------------------------------------------------
// Parameter blocks for action code
//------------------------------------------------------------------------

typedef struct {
   ULong    id;                       // Launch command identifier for EVPlugBase,
                                            // seted to PlugBaseCreator['evPM']
                                            // by EVPlugBase before launch
   ULong    pluginType;         // Type of plugin PRC
   ULong    pluginCreator;     // Creator of plugin PRC
   PlugBaseAPIPtr apiP;        // EVPlugBaseAPI pointer
   Err         err;

   union param {
       struct allParam {
           Word data[8];
       } allParam;

       // For PBLaunchCmd_GetInformation
       struct {
           Boolean  supportInfoPanel;
           Boolean  supportConfigPanel;
       } getInformation;

       // For PBLaunchCmd_SoftPenStroke
       struct {
           UInt  id;
       } SoftPenStroke;

   } data;
} PBLaunchParameterType, *PBLaunchParameterPtr;
 

• PBLaunchCmd_GetInformation

EVPlugBase call it to check whether or not the plugin supports Config panel and info panel function.
For example:
DWord
PilotMain (Word cmd, Ptr cmdPBP, Word launchFlags)
{
    PBLaunchParameterPtr pmP = (PBLaunchParameterPtr) cmdPBP;

    if (cmd == PBLaunchCmd_GetInformation)
    {
        pmP->data.getInformation.supportInfoPanel     = true;   //Support Info Panel
        pmP->data.getInformation.supportConfigPanel = true;   //Support Config Panel
        pmP->err = 0;
    }
    return 0;
}
 

• PBLaunchCmd_PluginAttach

EVPlugBase call it to active a plugin. Then, plugin replace the necessary SysTrap, setup its SoftPenStroke, initialize the application.
 
• PBLaunchCmd_PluginDetach

EVPlugBase call it to end a plugin. The plugin release the SysTrap replaced, unload the SoftPenStroke, finish some ending job.

Note: When a plugin want to replace SysTrap, its new SysTrap code must be locked or be unlocked by itself.

    else if (cmd == PBLaunchCmd_PluginAttach || cmd == PBLaunchCmd_PluginDetach)
    {
        DmOpenRef      pluginDB;
        VoidHand         codeResH;
        HookTrapType trapItem;
        DWord             romVersion;

        FtrGet (sysFtrCreator, sysFtrNumROMVersion, &romVersion);

        // Lock or unlock code
        pluginDB = DmOpenDatabaseByTypeCreator (PlugBasePluginType, appCreator, dmModeReadOnly);
        codeResH  = DmGet1Resource (CodeResType, 1);
        if (cmd == PBLaunchCmd_PluginAttach)
            MemHandleLock (codeResH);
        else
            MemHandleUnlock (codeResH);
        DmReleaseResource (codeResH);
        DmCloseDatabase (pluginDB);

        // Replace or release SysKeyboardDialog according to different OS version.
        trapItem.type     = PlugBasePluginType;
        trapItem.creator = appCreator;
        if (romVersion < version20)
        {
            trapItem.trapNum         = sysTrapSysKeyboardDialogV10;
            trapItem.newTrapAddr = mySysKeyboardDialogV10;
        }
        else {
            trapItem.trapNum         = sysTrapSysKeyboardDialog;
            trapItem.newTrapAddr = mySysKeyboardDialog;
        }
        if (cmd == PBLaunchCmd_PluginAttach)
            (*(pmP->apiP->hookSysTrap)) (&trapItem);
        else
            (*(pmP->apiP->unhookSysTrap)) (&trapItem);

        // Load or unload SoftPenStroke
        if (cmd == PBLaunchCmd_PluginAttach)
            installSoftPenStrokeOfExample (pmP->apiP, PenStroke1From, PenStroke1To, PenStroke2From, PenStroke2To);
        else
            uninstallSoftPenStrokeOfExample (pmP->apiP);

        pmP->err = 0;
    }
 

• PBLaunchCmd_ActivePluginInfoPanel

Active Info Panel of Plugin
    else if (cmd == PBLaunchCmd_ActivePluginInfoPanel)
    {
        doDialog (AboutForm);
        pmP->err = 0;
    }

• PBLaunchCmd_ActivePluginControlPanel

Active Control Panel of Plugin (As if tap a icon to config a plugin.)
    else if (cmd == PBLaunchCmd_ActivePluginControlPanel)
    {
        doConfig ();
        pmP->err = 0;
    }

• PBLaunchCmd_SoftPenStroke

EVPlugBase call it to notify plugin that user has operated a SoftPenStroke of this plugin. The plugin can respond according this command and its SoftPenStroke ID.
    else if (cmd == PBLaunchCmd_SoftPenStroke)
    {
        CharPtr msg = 0;

        if (pmP->data.SoftPenStroke.id == SoftPenStroke1ID)
            msg = "SoftPenStroke1";
        else if (pmP->data.SoftPenStroke.id == SoftPenStroke2ID)
            msg = "SoftPenStroke2";

        if (msg) msgBox (msg, 100);
    }
 

• How to get API pointer?
• By macro PBGetAPIPtr.
• When the system send Launch Command, the apiP in Parameter blocks is.
• The structure of API

typedef struct {
PBGetVersionPtr         getVersion;
PBGetAPIVersionPtr   getAPIVersion;

PBPluginEnablePtr       pluginEnable;
PBPluginEnabledPtr     pluginEnabled;

PBHookSysTrapPtr     hookSysTrap;
PBUnhookSysTrapPtr unhookSysTrap;
PBSysTrapHookedPtr sysTrapHooked;

PBInstallSoftPenStrokePtr              installSoftPenStroke;
PBUninstallSoftPenStrokePtr          uninstallSoftPenStroke;
PBGetSoftPenStrokePtr                 getSoftPenStroke;
PBCheckSoftPenStrokePtr             checkSoftPenStroke;
PBGetSoftPenStrokeChoicesPtr      getSoftPenStrokeChoices;
PBSetSoftPenStrokeListChoicesPtr setSoftPenStrokeListChoices;
} PlugBaseAPIType, *PlugBaseAPIPtr;
 

• Introduction of each function
• getVersion

To get the version of EVPlugBase

DWord getVersion (void);

Parameters:
    None.

Return:
    The version of EVPlugBase.
 

• getAPIVersion

To get the version of EVPlugBase API

DWord getAPIVersion (void);

Parameters:
    None

Return:
    Version of EVPlugBase API

• pluginEnable

Active or disable a plugin. Only can be called by active plugin. It gives a way to active plugin to be managed by EVPlugBase as a passive plugin.

Err pluginEnable (ULong type, ULong creator, Boolean enableIt);

Parameters:
    type        The type of plugin application
    creator    The creator of Plugin application
    enableIt   true mean active the Plugin, false mean disable the plugin.

Return:
    0 mean no error.

• pluginEnabled

To get the current state of Plugin.

Boolean pluginEnabled (ULong type, ULong creator);

Parameters:
    type        Type of Plugin application.
    creator   Creator of Plugin application.

Return:
    true mean plugin is active, false mean Plugin is disable.

• hookSysTrap

Replace the SysTrap of system.

Err hookSysTrap (HookTrapPtr trapP);

Parameters:
    trapP    Pointer point to HookTrapType structure.

    typedef struct tagHookTrapType {
    ULong   type;                 //Type of plugin, if the plugin is passive, it must be 'PLUG'.
    ULong   creator;             //Creator of plugin.
    UInt       trapNum;          //Number of SysTrap to be replaced.
    VoidPtr  newTrapAddr; //New Trap address.
    VoidPtr  oldTrapAddr;   //Return SysTrap address before hooked
    } HookTrapType, *HokTrapPtr;

Return:
    0 mean no error. Return an old SysTrap address in oldTrapAddr, member of trapP.
And set Feature Number, Feature of trapP->trapNum to the old SysTrap address.
FtrSet (trapP->creator, trapP->trapNum, (DWord) trapP->oldTrapAddr);

• unhookSysTrap

Release old SysTrap (replaced SysTrap).

Err unhookSysTrap (HookTrapPtr trapP);

Parameters:
    trapP    Pointer point to structure of HookTrapType , only type, creator, trapNum member needed.

Return:
    0 mean no error.

• sysTrapHooked

Return whether or not the SysTrap is replaced.

Boolean  sysTrapHooked (HookTrapPtr trapP);

Parameters:
    trapP    Pointer point to structure of HookTrapType , only type, creator, trapNum member needed.

Return:
    true mean this SysTrap is replaced by the Plugin, false mean the SysTrap is not.
 

• installSoftPenStroke

Install SoftPenStroke.

Err   installSoftPenStroke (SoftPenStrokePtr psP);

Parameters:
    psP    Pointer point to structure of SoftPenStrokeType

    typedef struct tagSoftPenStrokeType {
    ULong   type;                       // Type of application which install the SoftPenStroke
    ULong   creator;                   // Creator of application which install the SoftPenStroke
    UInt       id;                           // An application can install several SoftPenStroke,
                                                // each SoftPenStroke identified by this ID,
                                                // maybe 0..MAX UInt
    ScreenAreaType  penFrom;  // From Area
    ScreenAreaType  penTo;      // To Area
    } SoftPenStrokeType, *SoftPenStrokePtr;

Return:
    0 mean no error.
 

• uninstallSoftPenStroke

Uninstall SoftPenStroke¡£

Err   uninstallSoftPenStroke (SoftPenStrokePtr psP);

Parameters:
    psP    Pointer point to structure of SoftPenStrokeType,only type, creator, id needed.

Return:
    0 mean no error.
 

• getSoftPenStroke

Get installed SoftPenStroke

Err   getSoftPenStroke (SoftPenStrokePtr psP);

Parameters:
    psP    Pointer point to structure of SoftPenStrokeType,only type, creator, id needed.

Return:
    0 mean no error, and return details in psP.
 

• checkSoftPenStroke

Return whether or not the SoftPenStroke is occupied by other application.

Boolean  checkSoftPenStroke (SoftPenStrokePtr psP, SoftPenStrokePtr psOccupiedByP);

Parameters:
    psP    Pointer point to structure of SoftPenStrokeType

Return:
    true mean occupied, and return in psOccupiedByP the details of the application which occupy the SoftPenStroke.
    false mean not occupied, can be replaced safely.
 

• getSoftPenStrokeChoices

Get the pointer of SoftPenStroke PopupList text, this pointer is managed by the system, programer cannot release it.

CharPtr*  getSoftPenStrokeChoices (UIntPtr numItemsP, AreaMode areaMode, Boolean longDesc);

Parameters:
    numItemsP    Return number of items.
    areaMode     The type of return list text.
        areaFrom  Return FROM SoftPenStroke list text.
        areaTo      Return TO SoftPenStroke list text.
    longDesc       Define the length feature of a return text.
        true           Return a complete description.
        false          Return a compact description.

Complete description		Compact description
FROM	TO	FROM	TO
Applications Button	Applications Button	ApplBtn	ApplBtn
Menu Button	Menu Button	MenuBtn	MenuBtn
Calculator Button	Calculator Button	CalcBtn	CalcBtn
Find Button	Find Button	FindBtn	FindBtn
	Screen Area		Screen
	Graffiti Area		G(Graffiti)
	Graf Letter Up Area		G LettUp
	Graf Letter Down Area		G LettDn
	Graf Number Up Area		G NumUp
	Graf Number Down Area		G NumDn
	Disable		Disable
Note: Details position refer to SoftPenStroke map

Return:
   true mean occupied, and return details of the SoftPenStroke in psOccupiedByP.
   false mean not occupied, it can be used safely.
 

• setSoftPenStrokeListChoices

Set SoftPenStroke PopupList text.

void  setSoftPenStrokeListChoices (ListPtr list, AreaMode areaMode, Boolean longDesc);

Parameters:
    list                 the popup list for set the SoftPenStroke.
    areaMode     The mode of the list.
        areaFrom  The FROM SoftPenStroke popup list.
        areaTo      The TO  SoftPenStroke popup list.
    longDesc       Set the length feature of list text in popup list.
        true           Complete description
        false          Compact description
Return:
   None

Question: Could I operate with the pointer returned from SysGetTrapAddress, for example, lock, unlock etc?
Answer: No all. The pointer from SysGetTrapAddress could only be used to save or be released by SysSetTrapAddress, can't be operated by other ways. LaunchIII might operate the pointer and cause a crash when uncheck the box Always use LaunchIII.

Question: Can I write a application to replace a SysTrap not according the EVPlugBase?
Answer:Yes, you can. Because EVPlugBase rewrite the SysGetTrapAddress and SysSetTrapAddress two function. We suggest you write as the general ways:

static void hookASysTrap ()
{
       UInt        trapNum = sysTrapXXXX;
       VoidPtr   oldTrapAddr;

       oldTrapAddr = SysGetTrapAddress (trapNum);
       //A way to save old address
       //appCreator the creator of application
       FtrSet (appCreator, trapNum, (DWord) oldTrapAddr);
       SysSetTrapAddress (trapNum, sysTrapXXXXnewProc);
}

static void unhookASysTrap ()
{
       UInt        trapNum = sysTrapXXXX;
       VoidPtr   oldTrapAddr;

       if (FtrGet (appCreator, trapNum, (DWordPtr)(&oldTrapAddr)) == 0)
       {
               SysSetTrapAddress (trapNum, oldTrapAddr);
               FtrUnregister (appCreator, trapNum);
       }
}

Question: When more than one application replace one SysTrap, what must be noticed?
Answer: Because EVPlugBase rewrite SysGetTrapAddress and SysSetTrapAddress two function, the SysTrap can be replaced more than one times, and can be released without the First in, First out order. You just need to replace or release the SysTrap, and save the old address as the last question&answer metioned.

Question: Can one SysTrap be replaced more than once in a application?
Answer: In Plugin, a Systrap can only be replaced one times, can not be replaced more than one times. If the application not apply the EVPlugbase rule, direct call SysGetTrapAddress and SysSetTrapAddress to replace SysTrap, and can save every old Systrap address safely, it can replace the address sereral times. But these replacement is meanless.

Question: Can I run hacks in EVPlugBase?
Answer:   Yes.

Question: Can I run Plugins in Hack Master?
Answer:   No if the plugin written according rule of EVPlugBase.

Question: My pilot crash and reset when I uncheck the box of Always use LauncherIII after I installed EVPlugBase, how to solve the problem?
Answer:   Please disable EVPlugbase first, then uncheck the box of Always use LauncherIII, then enable EVPlugbase.

Question: Can EVPlugBase manage no-hack applications or non-EVPlugBase applications?
Answer:   Yes.