Subversion Repositories Kolibri OS

Rev

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