Menu
▾
▴
[Ndn-public] FMTAPI
|
From: <che...@us...> - 2002-06-18 20:41:46
|
Hello ndn-public,
API для работы с внешними описателями архиваторов ( в дальнейшем FmtAPI).
Версия 0.6.1.
Версия описания fmtAPI - 0.01
Условия распространения.
1. FmtAPI является частью проекта NDN (Necromancer's Dos Navigator).
2. FmtAPI может быть использован в любом программном продукте, независимо
от его открытости(зарыточти), операционной системы и т.п.
3. При использовании FmtAPI обязательно указание принадлежности его
проекту NDN и автора FmtAPI.
4. Допускается модификация FmtAPI, но только с ведома Автора или
координатора проекта NDN.
Такое ограничение на возможность модификации определяется необходимостью
соблюдения совместимости внешних описателей архиваторов с любым
программным продуктом, использующим FmtAPI.
5. Автором текущей версии 0.6.1 FmtAPI является Воронов Петр aka Chem O`Dun.
Область применения.
FmtAPI используется для написания и использования внешних описателей
архиваторов в проекте NDN.
Внешний описатель архиватора - динамическая библиотека (DLL) использующаяся
для детектирования заданного файла на совпадение его формата с форматом
архива, созданного каким-либо архиватором.
Так же в настоящей момент используется для чтения и выдачи в основную
программу списка файлов, обнаруженных в текущем архиве.
В последующих версия планируется введение возможности чтения и записи
содержимого архива, т.е. не только списка файлов в нем, но и самих этих
файлов.
В настоящий момент допускается возможность чтения списка файлов как напрямую
из потока ассоциированного с архивом, так и с помощью внешней программы
(архиватора), путем анализа выдаваемой им информации.
Описание FmtAPI.
Основой FmtAPI является файл plugdef.pas описывающий данный API. %-)
Описание plugdef.pas
Так как в FmtAPI для вызова процедур(функций) из внешних dll(fmt),
используется метод вызова по символьному имени, то в plugdef.pas
определяются символьные имена, для единообразия именования этих
функций.
const
pGetSign = 'tAPIGetSign'; //Выдача информации о данном
//fmt (Автор и т.п.)
pGetFMTVersion = 'tAPIGetFMTVersion'; //Выдача версии FmtAPI,
//поддерживаемой данным fmt
pSetStartupInfo = 'tAPISetStartupInfo'; //Задание необходимых для работы
// fmt параметров и функций из
// внешний программы
pSetMemoryManager = 'tAPISetMemoryManager'; //установка менеджера памяти,
//необходимого для работы.
Далее идет версия текущего FmtAPI,для жесткй записи ее в fmt.
const
cFMTAPIVersion : pchar = '0.6.1';
Далее идет описание типов переменных используемых в FmtAPI.
Тип записи с информации о файле, найденном в архиве:
type
pFmtAPIArchFileInfo = ^tFmtAPIArchFileInfo;
tFmtAPIArchFileInfo = Record
FName : PChar; //имя файла
Desc : PChar; //Описание (если есть)
USize : LongInt; //Исходный размер
PSize : LongInt; //Упакованный размер
Date : LongInt; //Дата файла (в ДОС-формате)
Attr : Byte; //его аттрибуты(в ДОС-формате)
end;
Запись с информацией о архиваторе:
type
pFmtAPIArchSetupInfo = ^tFmtAPIArchSetupInfo;
tFmtAPIArchSetupInfo = packed record
Ident, // идентификатор fmt, в которм описан текущий архиватор
// В дальнейшем будет использован для выбора пользователем
// наиболее нужного ему описателя из возможных
Sign, // трехсимвольный идентификатор архиватора
Desc, // Описание архиватора, его автора и т.д.
Packer, // Имя внешней программы для упаковки
UnPacker, // тоже для распаковки
// параметры командной строки для внешнего архиватора
Extract, // распаковки файла(списка)
ExtractWP, // для распаковки с путями
Add, // для добавления файла в архив
Move, // для переноса в архив
Delete, // для удаления из архива
Test, // для проверки целостности в архиве
Password, // для задания пароля доступа к архиву
IncludePaths, // для задания опции использования путей при архивации
ExcludePaths, // то же для исключения
ForceMode, // для задания опции "ускоренного" режима
RecoveryRec, // для добавления "восстановительной" записи
SelfExtract, // для задания опции саморазархивируемого архива
Solid, // тоже, для непрерывного
List, // параметр для вывода списка файлов
Default, // возможные параметры по умолчанию
// опции режима сжатия
StoreCompression, // без
FastestCompression, // слабое сжатие
FastCompression, //
NormalCompression, // обычное
GoodCompression, // хорошее
UltraCompression, // сверх
//
ListChar, // задание префикса имени файла , со списком обрабатываемых файлов
UseLFN : PChar; // допустимо ли использование "длинных" имен
PutTempBefore : byte; // предварительно положить во временный каталог (не использ)
Options : longint; // опции архиватора (см. ниже)
end;
Список опций:
Const
// опции режима работы описателя
cFmtAPIarchInternal : longint = $00000001; // Вкомпилирован в программу
// внешний
cFmtAPIarchReplaceAble : longint = $00000002; // допускается замена другим найденным
cFmtAPIarchNoReplaceAble : longint = $00000004; // не допускается замена
// опции архиватора
cFmtAPIarchExtList : longint = $00000010; // для чтения списка файлов используется
// внешний архиватор
cFmtAPIarchIntPack : longint = $00000100; // для упаковки не используется внешний архиватор
cFmtAPIarchIntUnp : longint = $00000101; // для распаковки не используется внешний архиватор
cFmtAPIarchNoPack : longint = $00000102; // не возможна распаковка архива
cFmtAPIarchNoUnp : longint = $00000104; // не возможно добавления файлов в архив
Прототипы функций для получения информации из fmt
type
tFmtAPIGetString = function : pchar; //получение ферсии и т.п.
tFmtAPISetMemoryManager = procedure (const MemMgr: TMemoryManager); //установка менеджера памяти
tFmtAPISetStartupInfo= function(var info) : Integer; // задание основных параметров
Прототипы функция для работы с потенциальным архивом
// проверка на совпадение формата
tFmtAPIDetectArchive = function( ArchStream: Pointer; ArchPos: Longint; ArchName: PChar; var Additional : Pointer):longint;
// выдача описания следующего файла в списке
tFmtAPIGetNextFile = function( ArchStream: Pointer; ArchFileInfo : pFmtAPIArchFileInfo; Additional : Pointer): longint;
// закрытие архива после прочтения всего списка
tFmtAPICloseArchive = function( var Additional : Pointer): longint;
Прототип функции инициализации описателя внешнего архиватора
(допустимо инициализация любого количества описателей в одном fmt)
tFmtAPIInitArchive = function (
AArchInfo: pFmtAPIArchSetupInfo; //запись с информацией об архиваторе
ADetect: tFmtAPIDetectArchive; //ссылка на функцию проверки формата
AGetNextFile : tFmtAPIGetNextFile; // тоже - описания следующего файла
AClose : tFmtAPICloseArchive; // закрытие списка файлов
AMode: longint):longint; // режим работы описателя()
прототипы функций работы с внешним потоком
tFmtAPIStreamOpen = function (FileName: PChar; Mode: Longint) : Pointer;
tFmtAPIStreamReadWrite = function (Stream : Pointer; var B; Size : longint) : longint;
tFmtAPIStreamReadWriteLn = function (Stream : Pointer; var S :shortstring): longint;
tFmtAPIStreamReadWriteChLn = function (Stream : Pointer; var P :Pchar): longint;
tFmtAPIStreamClose = function (Stream : Pointer) : Pointer;
tFmtAPIStreamGetInfo = function (Stream : Pointer) : Longint;
tFmtAPIStreamTruncate = procedure(Stream : Pointer);
tFmtAPIStreamSeek = function (Stream : Pointer; Pos: Longint) : Boolean;
tFmtAPIStreamEof = function (Stream : Pointer) : longint;
tFmtAPIStreamSearch = function (Stream : Pointer; SStr: PChar; Pos: Longint) : LongInt;
прототип функции текущего разделителя
tFmtAPISysPathSep = function : char;
прототип функции преобразования "Большие - маленькие" символов
tFmtAPIChangeCase = function (Str: Pchar; Mode : byte):PChar;
константы описания атрибутов файла в архиве
Const
cFmtAPIReadOnly : longint = $01;
cFmtAPIHidden : longint = $02;
cFmtAPISysFile : longint = $04;
cFmtAPIVolumeID : longint = $08; // N/A under OS/2
cFmtAPIDirectory : longint = $10;
cFmtAPIArchive : longint = $20;
константы задания режимов открытия внешнего потока
cFmtAPIStreamCreate : longint = $00003C00; { Create new file }
cFmtAPIStreamOpenRead : longint = $00003D40; { Read access only }
cFmtAPIStreamOpenWrite : longint = $00003D41; { Write access only }
cFmtAPIStreamOpen : longint = $00003D42; { Read and write access }
константы состояния внешнего потока
cFmtAPIStreamOk : longint = 0; { No error }
cFmtAPIStreamError : longint = -1; { Access error }
cFmtAPIStreamInitError : longint = -2; { Cannot initialize stream }
cFmtAPIStreamReadError : longint = -3; { Read beyond end of stream }
cFmtAPIStreamWriteError: longint = -4; { Cannot expand stream }
cFmtAPIStreamGetError : longint = -5; { Get of unregistered object type }
cFmtAPIStreamPutError : longint = -6; { Put of unregistered object type }
константы режима работы функции преобразования символов
cFmtAPIUpCase : byte = 0;
cFmtAPILowCase : byte = 1;
запись с информацией из внешней программы, задаваемой при инициализации
fmt.
type
pPluginStartupInfo = ^tPluginStartupInfo;
tPluginStartupInfo = packed record
StructSize : Integer; // не используется
// Смотри выше.
SysPathSep : tFmtAPISysPathSep;
StreamOpen : tFmtAPIStreamOpen;
StreamRead : tFmtAPIStreamReadWrite;
StreamWrite : tFmtAPIStreamReadWrite;
StreamReadLn : tFmtAPIStreamReadWriteLn;
StreamWriteLn : tFmtAPIStreamReadWriteLn;
StreamReadChLn : tFmtAPIStreamReadWriteChLn;
StreamWriteChLn : tFmtAPIStreamReadWriteChLn;
StreamClose : tFmtAPIStreamClose;
StreamGetStat : tFmtAPIStreamGetInfo;
StreamGetSize : tFmtAPIStreamGetInfo;
StreamGetPos : tFmtAPIStreamGetInfo;
StreamTruncate : tFmtAPIStreamTruncate;
StreamSeek : tFmtAPIStreamSeek;
StreamEof : tFmtAPIStreamEof;
StreamSearch : tFmtAPIStreamSearch;
ArchiveInit : tFmtAPIInitArchive;
ChangeCase : tFmtAPIChangeCase;
end;
Технология использования внешнего fmt из программы.
1. Инициализация fmt Как внешней dll.
2. Вызов функции выдачи версии FmtAPI по символьной ссылке
и проверка соответствия версии.
3. Вызов функции установки менеджера памяти.
4. Вызов функции выдачи информации о fmt.
5. Вызов функции задания стартовых параметров.
При этом вся необходимая информация о внешнем архиваторе
попадет в основную программу, а необходимые функции будут
экспортированы в fmt.
Рассмотрим эту технологию на примере arc_dir.pas
1. пропускаем.
2. в основную программу будет выдана версия 0.6.1 с использованием
функции GetFMTVersion
3. в fmt будет установлен текуший менеджер памяти с помощью функции
SetMemoryManager (стандартная для VirtualPascal)
4. будет получена информации о fmt, путем вызова функции GetSign
('Dir fmt by Chem`O Dun')
5. будет вызвана функция SetStartupInfo , при этом из основной программы
ей будет передана запись типа tPluginStartupInfo , с заполненными
полями.
В ходе выполнения функции она будет скопирована во внутреннюю переменную
FmtAPI.
Далее происходит вызов процедуры из основной программы для записи в нее
текущего описания архиватора, с передачей функций для работы с этим
архиватором.
6. Далее в процессе работы основной программы при необходимости произвести
"детектирование" архива будет вызвана функция
DirDetect( ArchStream: Pointer; ArchPos: Longint; ArchName: PChar; var Additional : Pointer):longint;
Где ArchStream - ссылка на внешний поток уже ассоциированный с текущим архивом
ArchName - имя текущего архива
Additional - переменная - указатель на возможно необходимый массив
информации, необходимой для работы с текущим архивом
Изначально = nil.
При успешном детектировании архива функция вернет 1 и Additional станет
указателем на непустой массив информации.
В даленйшем путем последовательного вызова функции
DirGetFile( ArchStream: Pointer; ArchFileInfo : pFmtAPIArchFileInfo; Additional : Pointer): longint;
где ArchStream - см. выше
ArchFileInfo - указатель на уже выделенную область памяти под информацию о
файле в архиве
Additional - см. выше.
При удачном прочтении информации о файле функция вернет 0
Если список файлов прочитан полностью - то 1
Если в процессе чтения списка фозникла ошибка - то 2.
После окончания четния списка файлов в основной программе необходимо вызвать
DirClose(var Additional : Pointer): longint;
для очистки Additional.
Примечание: если в опциях описания архиватора присутствует cFmtAPIarchExtList,
то при вызове функции типа tFmtAPIGetNextFile ей передается
указатель не на поток ассоциированный с архивом,
а на поток ассоциированный с файлом , результатом вывода
внешнего архиватора , после передачи ему
параметра, требующего выдачи списка файлов в текущем архиве.
Планы на дальнейше развитие.
1. Переход к новому формату описания файла в архиве
pFmtAPIArchFileInfo = ^tFmtAPIArchFileInfo;
tFmtAPIArchFileInfo = Record
FName : PChar;
Desc : PChar;
USize : record Lo,Hi :LongInt; end;
PSize : record Lo,Hi :LongInt; end;
Date : record Lo,Hi :LongInt; end;
DateType : byte;
Attr : Byte;
end;
возможные типы даты:
0 - ДОС формат
1 - юникс
2 - Микрософт 64 бит.
для преобразования типов внутри основной программы.
2. Возможность обработки архивов без вызова внешнего архиватора.
3. Счастье для всех и побольше.
18-06-2002. Воронов П.С.
Best regards,
Peter S. Voronov aka Chemodun (Чемодан) mailto:che...@us...
Necromancer's Dos Navigator Team |
