Subversion Repositories Kolibri OS

Rev

Go to most recent revision | 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, на которую рассчитан плагин. Сейчас должна быть 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. 0 = успешная инициализация
  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);
  138.