EVPlugBase Program Guide

Version 1.1 beta 1
12/18/1999
Copyright by EVSoft Co., Ltd.
All rights reserved.

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:
3. • 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.
4. 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.
5. 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.

When we developing EVEdit (A HackMaster extention), we feel these inconvenient deeply, so we develop EVPlugBase, to manage Plugins for Palm OS. The enhancement list below:

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.

As far as the patchs, it is the applications that include a piece of replacement code of SysTrap.
EVPlugBase notify plugin with 'Launch Command' to load or unload etc. Plugin act by those commands.

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.

EVPlugBase Launch Command
As metioned before, EVPlugBase communicates with plugins with Launch Command. Here list the Commands.

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);
      }
   

EVPlugBase API
EVPlugBase provide a suit of API to replace SysTrap or to install SoftPenStroke.

• 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

FAQ

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.