Packer plugins developer guide overview

Overview

This help file is about writing packer plugins for the file manager Total Commander, available on [1]. It describes the functions you need to implement to add a specific packer to Total Commander. You should also look at the available sample packers (with source), which give you some insight on plugin programming. There are samples for Microsoft Visual C++ and Delphi.

A WCX is nothing more than a 32-bit Windows DLL renamed to *.WCX, which supports a list of specific functions. Total Commander loads this library dynamically at runtime with LoadLibrary(), and loads all available functions with GetProcAddress(). This means that not all functions described here must be implemented (see below). All functions use the STDCALL calling convention with no C++ name mangling (see below), exactly like in most standard system libraries in Windows.

Mandatory functions

The minimum functions needed for a read-only plugin are:

• OpenArchive - tells the plugin which archive it should open for listing or reading.
• ReadHeader - this function is called as long as the plugin returns no error - the plugin must return one filename inside the * archive per call.
• ProcessFile - called immediately after ReadHeader. Tells the plugin to extract, test, or skip this file.
• CloseArchive - called after ReadHeader returns an error.
• SetChangeVolProc - Set a callback function to request a disk change from the user.
• SetProcessDataProc - Set a callback function to give feedback and allow aborting of the pack or unpack operation.

Optional functions

All the following functions are optional: if you want to support them, you need to implement GetPackerCaps too, to tell Total Commander which functions are supported. If GetPackerCaps isn't available, Total Commander assumes that the plugin only supports unpacking. Even with a read-only plugin, you may want to implement GetPackerCaps and return PK_CAPS_SEARCHTEXT to allow Total Commander to search for text in archives of this type.

The first group allows to create or modify existing archives:

• PackFiles - tells the plugin to pack a list of files into a given archive. If the archive exists, the plugin should add the files to that archive. Total Commander will ask the user for overwrite confirmation, so files which already exist in the archive should be overwritten.
• DeleteFiles - tells the plugin to remove files from the given archive.
• ConfigurePacker - lets the plugin open a configuration dialog for packing (not unpacking!). It is called when the 'configure' button is pressed in Total Commander's Files - Pack dialog.

The following optional functions are for packing in memory: This is used by Total Commander to create TAR.Plugin files in one step. For example, the .BZ2 plugin supports these functions. Most plugins can pack multiple files into one archive, and therefore will not need to implement these functions.

• StartMemPack tells the plugin to prepare internal structures for packing into memory.
• PackToMem sends new data (to be packed) to the plugin, and receives packed data from it.
• DoneMemPack terminates the packing to memory, either after a successful PackToMem loop, or when the user aborts packing.

The following function tells the plugin to check whether it can handle the specified unknown file or not:

• CanYouHandleThisFile allows the plugin to support files which may have a different extension, e.g. self-extracting archives.

Call sequences

Here is a simple pseudocode declaration how Total Commander calls the extraction functions:

1. Loop to scan for files in the archive:

 OpenArchive()          with OpenMode==PK_OM_LIST
 repeat
    ReadHeader()
    ProcessFile(...,PK_SKIP,...)
 until error returned
 CloseArchive()

2. Loop to extract files from the archive:

 OpenArchive()          with OpenMode==PK_OM_EXTRACT
 repeat
    ReadHeader()
    if WantToExtractThisFile()
       ProcessFile(...,PK_EXTRACT,...)
    else
       ProcessFile(...,PK_SKIP,...)
 until error returned
 CloseArchive()

Notes for VC++ users

If using __stdcall the linker produces file names like "_ReadHeader@8". To get a compatible plugin a "Def" file e.g. wcx.def has to be added to your project.

 --Begin of wxc.def file to change export names for linker
 
 EXPORTS
 
 CloseArchive=_CloseArchive@4
 DeleteFiles=_DeleteFiles@8
 GetPackerCaps=_GetPackerCaps@0
 OpenArchive=_OpenArchive@4
 PackFiles=_PackFiles@20
 ProcessFile=_ProcessFile@16
 ReadHeader=_ReadHeader@8
 SetChangeVolProc=_SetChangeVolProc@8
 SetProcessDataProc=_SetProcessDataProc@8
 ConfigurePacker=_ConfigurePacker@8
 
 --End of wxc.def file

---

Back to Packer plugins developer guide