trunk/bwapi/BWAPI_MPQDraftInjector/source/MPQDraftPlugin.h

Go to the documentation of this file.

/*
  QDPlugin.h
  The central hive of the MPQDraft plugin system.

  In addition to the standard MPQ "adding" functionality of MPQDraft,
  MPQDraft also supports a powerful plugin system to acommodate addition
  methods of patching. These plugins are specially constructed DLLs which
  1) Export the GetMPQDraftPlugin function, and 2) Impliment the
  IMPQDraftPlugin interface. Up to 8 plugins may be loaded in one patching
  session (although 8 is a rather arbitrary number, and may be changed in
  later versions, if there is reason to do so).

  - PLUGIN MODULES -
  MPQDraft supports the creation of completely self-contained SEMPQs. But,
  this ability creates a palette of problems all its own. All of a plugin's
  data files have to be packed into the SEMPQ. This means that a special
  mechanism is needed, to marshall the data files from the plugin to the
  SEMPQ, and back to the plugin; this is the plugin module system. Each data
  file of the plugin is referred to as a "module", and identified by
  a pair of DWORDs: a plugin ID, and a module ID. The plugin ID is the
  globally unique ID of the plugin; the module ID is the plugin-specific ID
  of the module.

  [FURTHER TEXT TO BE ADDED HERE]

  - SETUP SIDE -
  There are two halves to each plugin: a setup side and a patching side. The
  setup side is when the plugin gets loaded in MPQDraft, and displayed in
  the plugin list, in either the patching wizard or SEMPQ wizard.
  Specifically, MPQDraft loads all plugins when the plugins page in the
  wizard first gets activated. The plugins will remain loaded until the
  wizard is closed. If a patch is performed, the plugins will remain loaded
  until the patch is completed. This allows plugins to get the opportunity
  to delete any temporary files that were created for the patch.

  Order and timing of calls to setup-side plugin functions:

  When the plugins wizard page is first activated, and MPQDraft is building
  its plugin database:
  1. The plugin gets loaded with LoadLibrary.
  2. The plugin's GetMPQDraftPlugin function gets called to obtain the
  plugin's IMPQDraftPlugin interface.
  3. IMPQDraftPlugin::Identify gets called.
  4. IMPQDraftPlugin::GetPluginName gets called.

  Each time the plugins page is switched to, MPQDraft determines which
  plugins to display in the plugin list:
  - IMPQDraftPlugin::CanPatchExecutable gets called for the currently
  selected executable. If the plugin can patch the executable, it will
  appear in the plugin list if it can't, then it won't appear. NOTE: this
  step does not occur when selecting plugins for use in an SEMPQ. In this
  case, ALL plugins will be available to select.

  If the "Configure" button is clicked while a plugin is selected:
  - IMPQDraftPlugin::Configure is called, with the HWND to the wizard in
  use. This allows the plugin to create a modal dialog with various plugin
  settings.

  If the "Finish" button is clicked to initiate a patch:
  1. IMPQDraftPlugin::ReadyForPatch is called to discern whether the plugin
  is properly configured, and ready to perform the patch.
  2. IMPQDraftPlugin::GetModules is called to obtain the number of plugin
  modules the plugin will require.
  3. IMPQDraftPlugin::GetModule is called again to get the plugin's modules.

  Either after the patch is completed or the wizard is cancelled:
  - FreeLibrary is called to unload the plugin. The plugin is responsible
  for cleaning up any data files it created temporarily.

  NOTE: Plugins will not be loaded in setup-side when an SEMPQ is executed.

  - PATCHING SIDE -
  The patching side is when a plugin gets loaded by the MPQDraft patching
  kernel. The plugin will be loaded inside the patchee (the process being
  patched) BEFORE any patchee code gets executed, but after any DLLs the
  patchee uses are loaded and initialized (DllMain is called). This means
  that plugins will be able to modify initialized data in the patchee, but
  not uninitialized data. If the latter is necessary, a thread can be
  spawned by the plugin to wait until the data has been initialized.

  Order and timing of calls to patching-side plugin functions:

  After MPQDraft performs its own initializations, it will load each
  selected plugin (this is done before any MPQs are loaded):
  1. LoadLibrary gets called to load the plugin inside the patch target.
  2. GetMPQDraftPlugin gets called to obtain an IMPQDraftPlugin interface.
  3. IMPQDraftPlugin::InitializePlugin gets called with a pointer to the
  MPQDraft server interface, to allow the plugin to locate its data files.

  When the patchee is closing down, and MPQDraft is terminating:
  1. IMPQDraftPlugin::TerminatePlugin gets called to remove any patches the
  plugin performed.
  2. The plugin is unloaded with FreeLibrary.
*/

#ifndef QDPLUGIN_H
#define QDPLUGIN_H

#include <windows.h>

// The maximum length of a plugin module's filename. INCLUDES final NULL.
#define MPQDRAFT_MAX_PATH 264

// The maximum length of a plugin's name. INCLUDES final NULL.
#define MPQDRAFT_MAX_PLUGIN_NAME 64

/*
  MPQDRAFTPLUGINMODULE

  Structure used by IMPQDraftPlugin::GetModules to notify MPQDraft of any
  files (called plugin modules) that are to be loaded. Read description of
  that function for more information.
*/
#include <pshpack1.h>
struct MPQDRAFTPLUGINMODULE
{
  /* dwComponentID: The ID of the plugin. Should be the same value as is
  returned by IMPQDraftPlugin::Identify. Must be globally unique. */
  DWORD dwComponentID;
  /* dwModuleID: The unique ID of the plugin module. This will be used
  instead of the actual filename for identifying plugin modules. */
  DWORD dwModuleID;
  // bExecute: Used internally by MPQDraft. Must be set to FALSE.
  BOOL bExecute;
  // szModuleFileName: The absolute path of the plugin module file.
  char szModuleFileName[MPQDRAFT_MAX_PATH];
};
#include <poppack.h>

/*
  IMPQDraftServer

  Serves as a portal back to MPQDraft, allowing the plugin to
  not only be executed by MPQDraft, but also it communicate with MPQDraft.
  A plugin will be given an IMPQDraftServer pointer when MPQDraft calls
  IMPQDraftPlugin::InitializePlugin.
*/
struct IMPQDraftServer
{
  /*
    IMPQDraftServer::GetPluginModule

    Allows a plugin to locate its modules when it is loaded in patch-side.

    Return TRUE on success, and FALSE on failure.

    Parameters:
      dwPluginID [in] - The ID of the plugin who is attempting to locate
      its modules.
      dwModuleID [in] - The ID of the module to be located.
      lpszFileName [out] - Pointer to a buffer where MPQDraft will copy
      the file name of the module to. This buffer should be
      MPQDRAFT_MAX_PATH characters long.

    Behavior:
      - If lpszFileName is NULL, GetPluginModules will fail.

      - If the buffer pointer to by lpszFileName is shorter than the
      length of the module's filename (which will never be more than
      MPQDRAFT_MAX_PATH), a crash will result.
      - If no module identified by dwPluginID and dwModuleID can be
      found, GetPluginModule will fail.
      - If more than one module with identical dwPluginID and
      dwModuleID exist, MPQDraft will arbitrarily choose one to return.

      - If the desired module exists, GetPluginModule will copy the
      filename of the module to lpszFileName.
  */
  virtual BOOL WINAPI GetPluginModule(DWORD dwPluginID, DWORD dwModuleID, LPSTR lpszFileName) = 0;
};

/*
  IMPQDraftPlugin

  The primary gateway between the MPQDraft patching kernel and the plugin.
  This interface must be fully implimented by every MPQDraft plugin (or at
  least until it is superseded by IMPQDraftPlugin2, in a much later version
  of MPQDraft). MPQDraft will obtain this interface when it calls
  GetMPQDraftPlugin. It will then store the interface in its plugin
  database, and use it in all subsequent calls to the plugin.

  NOTE: The specifications for this interface are based on the recommended
  responses. In some places it may be legal to slightly depart from the
  recommended specs (i.e. functions may fail instead of asserting).
*/
struct IMPQDraftPlugin
{
  /*
    IMPQDraftPlugin::Identify

    Identifies the plugin to MPQDraft with a globally unique ID code.

    Returns TRUE on success, and FALSE on failure (which should never
    happen).

    Parameters:
      lpdwPluginID [out] - A pointer to a DWORD that will receive the
      plugin's ID. MPQDraft will supply this DWORD.

    Behavior:
      - If lpdwPluginID is NULL, Identify will assert.

      - On success, Identify will copy its ID to lpdwPluginID.
  */
  virtual BOOL WINAPI Identify(LPDWORD lpdwPluginID) = 0;

  /*
    GetPluginName

    Retrieves the name of the plugin which will be displayed in the
    plugin list in either of the MPQDraft wizards. This name should also
    include the version of the plugin, i.e. "StarGraft v1.08 QD".

    Returns TRUE on success, and FALSE on failure.

    Parameters:
      lpszPluginName [out] - A pointer to a buffer which will receive
      the name of the plugin. This buffer will by provided by MPQDraft,
      and will usually be MPQDRAFT_MAX_PLUGIN_NAME chars long.
      nNameBufferLength [in] - The length of the buffer pointed to by
      lpszPluginName, including space for the final NULL.

    Behavior:
      - If lpszPluginName is null, GetPluginName will assert.

      - If nNameBufferLength is shorter than the name of the plugin,
      GetPluginName will fail.

      - On success, GetPluginName will copy the plugin name to the
      buffer pointed to by lpszPluginName.
  */
  virtual BOOL WINAPI GetPluginName(LPSTR lpszPluginName, DWORD nNameBufferLength) = 0;
  /*
    IMPQDraftPlugin::CanPatchExecutable

    Called by MPQDraft in the plugins page of the patch wizard (but not on
    the SEMPQ wizard). Its return value determines whether or not the
    plugin will appear in the list of available plugins, as MPQDraft will
    only list plugins which are compatible with the currently selected
    patch target.

    Returns TRUE if the plugin can patch the selected executable, and
    FALSE if it cannot.

    Parameters:
      lpszEXEFileName [in] - The absolute path of the currently selected
      executable.

    Behavior:
      - If lpszEXEFileName is NULL, CanPatchExecutable will assert.

      - If an error occurs (i.e. the executable cannot be opened or read
      from, CanPatchExecutable will fail.
  */
  virtual BOOL WINAPI CanPatchExecutable(LPCSTR lpszEXEFileName) = 0;
  /*
    IMPQDraftPlugin::Configure

    Called by MPQDraft from the plugin page in either of the wizards.
    Configure should present the user with settings which can be
    adjusted to change the way the plugin will function (i.e. selecting
    the PAT to use in StarGraft). If necessary, the plugin can create a
    settings dialog. It is recommended that the plugin stores the settings
    from the last time it was configured in the registry, but this is not
    mandatory. Some plugins may even not require any configuration at all,
    in which case this function would be a simple "return TRUE".

    Returns TRUE on success and FALSE on failure.

    Parameters:
      hParentWnd [in] - A handle to the wizard from which Configure was
      called. This handle is to be used exclusively to pass to
      DialogBox, to create a modal dialog. It is NOT to be used to
      attempt to modify the wizard. Such an attempt will probably crash.

    Behavior:
      - If hParentWnd is NULL, Configure will assert.

      - If an error occurs while configuring the plugin, Configure will
      fail.

      - If the configuration completed sucessfully (even if the user
      pressed the "Cancel" button on a dialog), Configure will succeed.
  */
  virtual BOOL WINAPI Configure(HWND hParentWnd) = 0;

  /*
    IMPQDraftPlugin::ReadyForPatch

    Called by MPQDraft right before a patch, to determine whether all
    plugins are properly configured, and ready to patch.

    Returns TRUE if the plugin is configured properly, FALSE if it isn't.
  */
  virtual BOOL WINAPI ReadyForPatch() = 0;

  /*
    IMPQDraftPlugin::GetModules

    Called twice by MPQDraft right before it is about to perform a patch.
    The first time, MPQDraft collects the number of modules from all
    plugins, so that it can allocate the proper amount of memory to hold
    the list of modules. The second it will be to actually retrieve the
    list of modules. These modules will be packed into an SEMPQ. Or, if
    if a straight patch is being performed, MPQDraft will just pass on the
    module list to the patching kernel.

    Returns TRUE on success, and FALSE on failure.

    Parameters:
      lpPluginModules [out] - A pointer to the memory MPQDraft has
      allocated to hold the list of modules. The plugin must  list each
      module it will require in the patching process. When MPQDraft
      first calls GetModules, lpPluginModules will be NULL.
      lpnNumModules [out] - A pointer to the number of plugin modules
      the plugin will need. This number ought not to exceed 4.

    Behavior:
      - If lpnNumModules is NULL, GetModules will assert.

      - If an error occurs, and GetModules is unable to supply the
      required information, GetModules will fail. In this case, MPQDraft
      will abort the patch.

      - If lpPluginModules is non-NULL, GetModules will copy the
      list of modules to lpPluginModules, and give the number of modules
      in lpnNumModules.
      - If lpPluginModules is NULL, GetModules will give the exact
      number of modules it will require in lpnNumModules, and succeed.
  */
  virtual BOOL WINAPI GetModules(MPQDRAFTPLUGINMODULE* lpPluginModules, LPDWORD lpnNumModules) = 0;

  /*
    IMPQDraftPlugin::InitializePlugin

    Called by MPQDraft from inside the patch target, to allow the plugin
    to perform its patch. Any patches the plugin makes should be stored,
    and undone upon TerminatePlugin.

    A return value of TRUE indicates that MPQDraft should continue with
    the patch. FALSE indicates that MPQDraft should abort the patch. The
    plugin should report any errors BEFORE it returns FALSE, as MPQDraft
    will terminate the patch silently.

    Parameters:
      lpMPQDraftServer [in] - A pointer to an IMPQDraftServer interface,
      provided by MPQDraft. This interface can be used to locate the
      plugin's modules. This pointer should be saved in case it is
      needed in future use.

    Behavior:
      - If lpMPQDraftServer is NULL, InitializePlugin will assert.

      - If the plugin was unable to perform the patch, and the the patch
      target should be terminated, InitializePlugin will display an
      error message box and return FALSE. MPQDraft will abort the patch.
      - If the plugin was unable to perform the patch, and MPQDraft
      should ignore the error and continue, InitializePlugin will
      return TRUE. MPQDraft will continue the patch.

      - If the patch was performed successfully, InitializePlugin will
      return TRUE.
  */
  virtual BOOL WINAPI InitializePlugin(IMPQDraftServer* lpMPQDraftServer) = 0;

  /*
    IMPQDraftPlugin::TerminatePlugin

    Called by MPQDraft inside the patch target during the shutdown
    process, to allow the plugin to unload any patches it made.

    Returns TRUE on success, and FALSE on failure.

    Behavior:
      - If InitializePlugin was not called previously, TerminatePlugin
      asserts.

      - If the patches performed in InitializePlugin were not
      successfully removed, TerminatePlugin fails.
      - If the patches performed in InitializePlugin were successfully
      removed, TerminatePlugin succeeds.

      - It is possible that on rare occasions InitializePlugin will be
      called, then the plugin will be unloaded before TerminatePlugin
      gets called. The plugin should check for this on
      DLL_PROCESS_DETACH, and call TerminatePlugin itself.
  */
  virtual BOOL WINAPI TerminatePlugin() = 0;
};

/*
  GetMPQDraftPlugin

  Exported by name from the plugin DLL. Called by MPQDraft to obtain the
  IMPQDraftPlugin interface of the plugin.

  Returns TRUE on success, and FALSE on failure.

  Parameters:
    lppMPQDraftPlugin [out] - A pointer to a pointer that will hold the
    IMPQDraftPlugin. The plugin must set this to point to the plugin's
    IMPQDraftPlugin interface.

  Behavior:
    - GetMPQDraftPlugin will only be called once, so it isn't necessary
    to instantiate an IMPQDraftPlugin for each call. A single global
    IMPQDraftPlugin is sufficient.
*/
BOOL WINAPI GetMPQDraftPlugin(IMPQDraftPlugin** lppMPQDraftPlugin);

#endif // #ifndef QDPLUGIN_H