Рекомендации по написанию архиваторных плагинов для Total Commander

Обзор

Написание архиваторных плагинов для файлового менеджера Total Commander, доступного на www.ghisler.com. Описаны функции, которые вы должны реализовать для добавления нужного упаковщика в Total Commander. Вы можете посмотреть примеры плагинов (с исходными файлами), которые помогут понять программирование плагинов. Доступны примеры для Delphi и Microsoft Visual C++.

WCX – это обычная 32-битная библиотека Windows DLL, переименованная в *.WCX, которая поддерживает определённый список функций. Total Commander динамически загружает эту библиотеку через LoadLibrary(), и загружает все доступные функции через GetProcAddress(). Не все функции, описанные здесь, должны обязательно выполняться (см. ниже). Все функции используют соглашение о вызовах STDCALL with no C++ name mangling (см. ниже), точно так же, как большинство стандартных системных библиотек в Windows.

Функции, минимально необходимые в плагине «только для чтения»:

OpenArchive – сообщает плагину, какой архив должен быть открыт для просмотра или чтения.

ReadHeader – функция вызывается до тех пор, пока плагин не возвратит код ошибки – плагин должен возвратить одно имя файла из архива за вызов.

ProcessFile – вызывается сразу после ReadHeader. Сообщает плагину распаковать, тестировать или пропустить этот файл.

CloseArchive – вызывается после того, как ReadHeader возвратит код ошибки.

SetChangeVolProc – устанавливает функцию обратной связи, которая запрашивает смену диска пользователем.

SetProcessDataProc – устанавливает функцию обратной связи, позволяет прервать операции упаковки или распаковки.

Следующие функции описывать необязательно. Если нужна их поддержка, вы должны реализовать GetPackerCaps, чтобы сообщить Total Commander какие функции поддерживаются. Если GetPackerCaps не выполнена, Total Commander полагает, что плагин поддерживает только распаковку. В плагине «только для чтения» вы также можете описать GetPackerCaps и возвратить PK_CAPS_SEARCHTEXT, чтобы Total Commander мог искать по тексту в архивах этого типа.

Первая группа для создания или изменения существующих архивов:

PackFiles – сообщает плагину о необходимости упаковки списка файлов в нужный архив. Если архив существует, плагин должен добавить файлы в этот архив. Total Commander сам запрашивает пользователя о необходимости перезаписи, поэтому файл, существующий в архиве, должен быть перезаписан.

DeleteFiles – сообщает плагину о необходимости удаления файлов в нужном архиве.

ConfigurePacker – позволяет плагину открыть диалог настроек для упаковки (не для распаковки!). Вызывается при нажатии кнопки «Настройка» в диалоге Файл – Упаковать в Total Commander.

Следующие функции для упаковки в памяти описывать необязательно:

Используются в Total Commander для создания файлов типа TAR.Plugin за один шаг. Например, плагин .BZ2 поддерживает эти функции. Большинство плагинов могут упаковывать несколько файлов в один архив, и поэтому могут не использовать эти функции.

StartMemPack сообщает плагину о необходимости подготовить внутренние резервы для упаковки в памяти.

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.

Следующая функция сообщает плагину о проверке, может ли он обрабатывать указанный неизвестный файл:

CanYouHandleThisFile позволяет плагину поддерживать файлы с любыми расширениями, например самораспаковывающиеся архивы.

Как Total Commander вызывает внешние функции:

Приведёно описание простого псевдокода, как Total Commander вызывает внешние функции:

1. Цикл сканирования файлов в архиве:

OpenArchive()          with OpenMode==PK_OM_LIST
repeat
   ReadHeader()
   ProcessFile(..., PK_SKIP, ...)
until error returned (возвращена ошибка)
CloseArchive()

2. Цикл распаковки файлов из архива:

OpenArchive()          with OpenMode==PK_OM_EXTRACT
repeat
   ReadHeader()
   if WantToExtractThisFile() (если пользователь хочет распаковать этот файл)
      ProcessFile(..., PK_EXTRACT, ...) (распаковать)
   else
      ProcessFile(..., PK_SKIP, ...) (пропустить)
until error returned (возвращена ошибка)
CloseArchive()

Важное замечание для программистов на C и C++, использующих Visual C++:

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