Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
589 diamond 1 
Плагин представляет собой стандартную для Колибри динамическую библиотеку (формата COFF),
2 
экспортирующую следующие функции и переменные (некоторые функции могут отсутствовать).
3 
Функции могут разрушать любые регистры. kfar гарантирует сброшенный флаг направления DF
4 
при вызове экспортируемых функций и ожидает того же для callback-функций.
5 
 
6 
int version;
7 
Версия интерфейса kfar, на которую рассчитан плагин. Сейчас должна быть 1.
8 
 
9 
int __stdcall plugin_load(kfar_info* info);
10 
Вызывается при загрузке плагина.
11 
typedef struct
12 
{
13 
        int StructSize; // = sizeof(kfar_info)
14 
        int kfar_ver;   // 10000h*major + minor
15 
/* Все callback-функции сохраняют все регистры, за исключением eax. */
16 
/* Функции работы с файлами: */
17 
        void* open;     // HANDLE __stdcall open(const char* name, int mode);
18 
                        // mode - комбинация битовых флагов
19 
                        // O_READ = 1 - доступ для чтения
20 
                        // O_WRITE = 2 - доступ для записи
21 
                        // O_CREATE = 4 - если файл не существует, создать его
22 
                        // O_TRUNCATE = 8 - усечь файл до нулевой длины
23 
        void* read;     // unsigned __stdcall read(HANDLE hFile, void* buf, unsigned size);
24 
        void* write;    // ещё не реализовано
25 
        void* seek;     // void __stdcall seek(HANDLE hFile, int method, __int64 newpos);
26 
        void* flush;    // ещё не реализовано
27 
        void* filesize; // __int64 __stdcall filesize(HANDLE hFile);
28 
        void* close;    // void __stdcall close(HANDLE hFile);
29 
/* Функции работы с памятью (постранично): */
30 
        void* pgalloc;  // in: ecx=size, out: eax=pointer or NULL
31 
                        // при нехватке памяти сообщает пользователю и возвращает NULL
32 
        void* pgrealloc; // in: edx=pointer, ecx=new size, out: eax=pointer or NULL
33 
                        // при нехватке памяти сообщает пользователю и возвращает NULL
34 
        void* pgfree;   // in: ecx=pointer
35 
        void* getfreemem;       // unsigned __stdcall getfreemem(void);
36 
                                // возвращает размер свободной оперативной памяти в Кб
37 
        void* pgalloc2;         // void* __stdcall pgalloc2(unsigned size);
38 
        void* pgrealloc2;       // void* __stdcall pgrealloc2(void* pointer, unsigned size);
39 
        void* pgfree2;          // void __stdcall pgfree2(void* pointer);
40 
/* Функции работы с диалогами: */
41 
        void* menu;     // int __stdcall menu(void* variants, const char* title, unsigned flags);
42 
                        // variants указывает на текущий элемент в двусвязном списке
43 
        void* menu_centered_in; // int __stdcall menu_centered_in(unsigned left, unsigned top,
44 
                                // unsigned width, unsigned height,
45 
                                // void* variants, const char* title, unsigned flags);
46 
        void* DialogBox;        // int __stdcall DialogBox(DLGDATA* dlg);
47 
        void* SayErr;           // int __stdcall SayErr(int num_strings, const char** strings,
48 
                                //                      int num_buttons, const char** buttons);
49 
        void* Message;          // int __stdcall Message(const char* title,
50 
                                //                      int num_strings, const char** strings,
51 
                                //                      int num_buttons, const char** buttons);
52 
                                // may be x=-1 and/or y=-1
53 
        struct {unsigned width;unsigned height;}* cur_console_size;
54 
} kfar_info;
55 
Возвращаемое значение:
56 
 
57 
1 = ошибка инициализации (kfar выдаст сообщение пользователю)
58 
2 = ошибка инициализации (kfar продолжит без сообщений)
59 
 
60 
void __stdcall plugin_unload(void);
61 
Вызывается при выгрузке плагина (в процессе завершения работы kfar).
62 
 
63 
HANDLE __stdcall OpenFilePlugin(HANDLE basefile, const char* name,
64 
        const void* attr, const void* data, int datasize);
65 
Открывает плагин, эмулирующий файловую систему на базе файла (например, архива).
66 
basefile - хэндл файла (к которому применимы функции read и seek из kfar_info)
67 
name - имя файла (во временном буфере)
68 
attr - указатель на структуру с атрибутами файла в формате системной функции 70.1
69 
data - буфер, содержащий данные из начала файла (может использоваться для определения типа файла)
70 
datasize - размер данных в data. В текущей реализации min(1024,размер файла)
71 
Если плагин обрабатывает переданный файл, то он должен вернуть новый описатель,
72 
который в дальнейшем будет использовать kfar для обращения к плагину. В этом случае
73 
плагин должен самостоятельно закрыть basefile функцией close из kfar_info (например,
74 
при закрытии описателя плагина в ClosePlugin или непосредственно в OpenFilePlugin,
75 
если basefile вообще впоследствии не нужен).
76 
Если плагин не обрабатывает переданный файл, должен возвращаться 0.
77 
Если операция прервана пользователем, должно возвращаться значение -1.
78 
 
79 
void __stdcall ClosePlugin(HANDLE hPlugin);
80 
Закрывает созданный в OpenFilePlugin описатель.
81 
 
82 
void __stdcall GetOpenPluginInfo(HANDLE hPlugin, OpenPluginInfo* Info);
83 
Получить информацию об открытом экземпляре плагина.
84 
typedef struct
85 
{
86 
        unsigned flags; // бит 0: добавлять элемент '..', если он отсутствует
87 
                        // бит 1: копирование обрабатывается функцией GetFiles
88 
} OpenPluginInfo;
89 
 
90 
void __stdcall GetPanelTitle(HANDLE hPlugin, char title[1024],
91 
        const char* host_file, const char* curdir);
92 
Получить заголовок панели плагина. Параметр host_file совпадает с именем файла, переданным
93 
в OpenFilePlugin. Параметр curdir совпадает с текущей папкой, устанавливаемой в SetFolder.
94 
 
95 
int __stdcall ReadFolder(HANDLE hPlugin, unsigned dirinfo_start,
96 
        unsigned dirinfo_size, void* dirdata);
97 
Читает текущую папку. hPlugin - возвращённый из OpenFilePlugin описатель.
98 
dirinfo_start - с какого файла читать, dirinfo_size - сколько файлов читать.
99 
Возвращаемое значение и возвращаемые в dirdata данные должны соответствовать функции 70.1.
100 
 
101 
bool __stdcall SetFolder(HANDLE hPlugin, const char* relative_path, const char* absolute_path);
102 
Установить текущую папку. relative_path - относительный путь (".." или имя подпапки),
103 
absolute_path - абсолютный путь (папка эмулируемой плагином файловой системы).
104 
 
105 
void __stdcall GetFiles(HANDLE hPlugin, int NumItems, void* items[], void* addfile, void* adddir);
106 
        bool __stdcall addfile(const char* name, void* bdfe_info, HANDLE hFile);
107 
        bool __stdcall adddir(const char* name, void* bdfe_info);
108 
Вызывается для копирования, если во флагах, возвращаемых GetOpenPluginInfo, установлен бит 1.
109 
Эту функцию рекомендуется реализовывать в случае, если стандартный рекурсивный обход папок
110 
неудобен.
111 
hPlugin - описатель, созданный в OpenFilePlugin.
112 
NumItems - число копируемых элементов.
113 
items - массив копируемых элементов, каждый из которых задаётся указателем на структуру BDFE.
114 
Специальный случай NumItems=-1, items=NULL означает "все файлы" (в текущей папке и подпапках).
115 
addfile, adddir - callback-функции kfar'а. Возврат false означает "прервать копирование".
116 
Параметр name должен задавать имя относительно текущей папки. Параметр bdfe_info -
117 
указатель на сокращённую (40 байт) запись в формате функции 70.5.
118 
Открытием и закрытием описателя hFile должен заниматься плагин. Функция addfile будет
119 
вызывать только функцию read.
120 
 
121 
int __stdcall getattr(HANDLE hPlugin, const char* filename, void* info);
122 
Получить информацию о файле. Возвращаемое значение и данные в info должны соответствовать
123 
функции 70.5.
124 
 
125 
HANDLE __stdcall open(HANDLE hPlugin, const char* filename, int mode);
126 
Открыть файл filename. Параметр mode зарезервирован и в текущей версии kfar всегда равен 1.
127 
 
128 
unsigned __stdcall read(HANDLE hFile, void* buf, unsigned size);
129 
Чтение size байт в буфер buf из файла hFile, ранее открытого через open.
130 
kfar гарантирует, что size кратен 512 байт.
131 
Возвращаемое значение: число прочитанных байт, -1 при ошибке.
132 
 
133 
void __stdcall setpos(HANDLE hFile, __int64 pos);
134 
Установить текущую позицию в файле hFile, ранее открытого через open, в pos.
135 
Гарантируется, что pos кратно 512 байт.
136 
 
137 
void __stdcall close(HANDLE hFile);