Subversion Repositories Kolibri OS

Rev

Rev 589 | Blame | Compare with Previous | Last modification | View Log | Download | RSS feed

  1. Плагин представляет собой стандартную для Колибри динамическую библиотеку (формата COFF),
  2. экспортирующую следующие функции и переменные (некоторые функции могут отсутствовать).
  3. Функции могут разрушать любые регистры. kfar гарантирует сброшенный флаг направления DF
  4. при вызове экспортируемых функций и ожидает того же для callback-функций.
  5.  
  6. int version;
  7. Версия интерфейса kfar, на которую рассчитан плагин. Сейчас должна быть 2.
  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* open2;    // HANDLE __stdcall open2(int plugin_id, HANDLE plugin_instance,
  24.                         //                      const char* name, int mode);
  25.                         // аналогично open, но открывает файл с панели плагина
  26.                         // open2(0,<anything>,name,mode) = open(name,mode)
  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);
  30.         void* tell;     // __int64 __stdcall tell(HANDLE hFile);
  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. 0 = успешная инициализация
  62. 1 = ошибка инициализации (kfar выдаст сообщение пользователю)
  63. 2 = ошибка инициализации (kfar продолжит без сообщений)
  64.  
  65. void __stdcall plugin_unload(void);
  66. Вызывается при выгрузке плагина (в процессе завершения работы kfar).
  67.  
  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);
  71. Открывает плагин, эмулирующий файловую систему на базе файла (например, архива).
  72.  
  73. basefile - хэндл файла (к которому применимы функции read и seek из kfar_info)
  74. attr - указатель на структуру с атрибутами файла в формате системной функции 70.1
  75. data - буфер, содержащий данные из начала файла (может использоваться для определения типа файла)
  76. datasize - размер данных в data. В текущей реализации min(1024,размер файла)
  77. baseplugin_id - идентификатор плагина, на панели которого располагается открываемый файл;
  78.                 0 в случае обычных панелей
  79. baseplugin_instance - хэндл, возвращённый из функции GetOpenPluginInfo плагина,
  80.                 определяемого по baseplugin_id
  81. name - имя файла (во временном буфере) (полное имя относительно baseplugin)
  82.  
  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);
  150.