KFar-API
The plugin is a standard kolibri library (COFF format). The plugin must export the following functions and variables (some features may not be available). Functions may destroy any registers. KFAR also guarantees DF flag is cleared when a function is called, and expects the same for the callback functions.
plugin structure
<syntaxhighlight lang="c"> int version; </syntaxhighlight> KFAR interface version, current version is 2. <syntaxhighlight lang="c"> typedef struct {
int StructSize; // = sizeof(kfar_info)
int kfar_ver; // 10000h*major + minor
/* The callback function preserves all registers except eax. */
/* File functions: */
void* open; // HANDLE __stdcall open(const char* name, int mode);
// mode - a combination of bit flags
// O_READ = 1 - read access
// O_WRITE = 2 - write access
// O_CREATE = 4 - if the file does not exist, create it
// O_TRUNCATE = 8 - truncate the file to zero len
void* open2; // HANDLE __stdcall open2(int plugin_id, HANDLE plugin_instance,
// const char* name, int mode);
// similar to open, but it opens the file with the plugin panel
// open2(0,<anything>,name,mode) = open(name,mode)
void* read; // unsigned __stdcall read(HANDLE hFile, void* buf, unsigned size);
void* write; // not yet implemented
void* seek; // void __stdcall seek(HANDLE hFile, int method, __int64 newpos);
void* tell; // __int64 __stdcall tell(HANDLE hFile);
void* flush; // not yet implemented
void* filesize; // __int64 __stdcall filesize(HANDLE hFile);
void* close; // void __stdcall close(HANDLE hFile);
/* Functions to work with the memory (page) */
void* pgalloc; // in: ecx=size, out: eax=pointer or NULL
// Out of memory, informs the user and returns NULL
void* pgrealloc; // in: edx=pointer, ecx=new size, out: eax=pointer or NULL
// Out of memory, informs the user and returns NULL
void* pgfree; // in: ecx=pointer
void* getfreemem; // unsigned __stdcall getfreemem(void);
// returns the size of free memory in KB
void* pgalloc2; // void* __stdcall pgalloc2(unsigned size);
void* pgrealloc2; // void* __stdcall pgrealloc2(void* pointer, unsigned size);
void* pgfree2; // void __stdcall pgfree2(void* pointer);
/* Functions for the dialogue: */
void* menu; // int __stdcall menu(void* variants, const char* title, unsigned flags);
// variants points to the current element in the linked list
void* menu_centered_in; // int __stdcall menu_centered_in(unsigned left, unsigned top,
// unsigned width, unsigned height,
// void* variants, const char* title, unsigned flags);
void* DialogBox; // int __stdcall DialogBox(DLGDATA* dlg);
void* SayErr; // int __stdcall SayErr(int num_strings, const char** strings,
// int num_buttons, const char** buttons);
void* Message; // int __stdcall Message(const char* title,
// int num_strings, const char** strings,
// int num_buttons, const char** buttons);
// may be x=-1 and/or y=-1
struct {unsigned width;unsigned height;}* cur_console_size;
} kfar_info; </syntaxhighlight>
plugin_load()
<syntaxhighlight lang="c"> int __stdcall plugin_load(kfar_info* info); </syntaxhighlight> Called when the plugin is loaded.
| 0 | successful initialization |
| 1 | Initialization error (KFAR will display a message to the user) |
| 2 | Initialization error (KFAR will continue without informing the user) |
plugin_unload()
<syntaxhighlight lang="c"> void __stdcall plugin_unload(void); </syntaxhighlight> Called to unload the plugin (when KFAR is being shut down).
OpenFilePlugin()
<syntaxhighlight lang="c"> HANDLE __stdcall OpenFilePlugin(HANDLE basefile,
const void* attr, const void* data, int datasize,
int baseplugin_id, HANDLE baseplugin_instance, const char* name);
</syntaxhighlight> Opens plugin that emulates a filesystem on the basis of a file (for example, archive)
| basefile | file handle (which functions read and seek in kfar_info are applied to) |
| attr | a pointer to a structure with the file attributes in form as they are passed to sysfn 70.1 |
| data | the buffer containing the data from the beginning of the file (can be used to determine the file type) |
| datasize | data size in the data. In the current implmentation equals min(1024, file size) |
| baseplugin_id | plugin ID on which panel opened file is located; 0 for default panels |
| baseplugin_instance | The handle returned from the function GetOpenPluginInfo of plugin, determined in baseplug_id |
| name | file name (in a temporary buffer) (full name relative to baseplugin) |
If the plugin handles the uploaded file, it must return the new handle which will later be used by kfar to refer to the plugin. In this case, plugin must close basefile using close function of kfar_info (eg closing plugin handle from ClosePlugin or directly in OpenFilePlugin, if basefile is not needed any more).
| 0 | plugin does not handle the transferred file |
| -1 | the operation is interrupted by the user |
ClosePlugin()
<syntaxhighlight lang="c"> void __stdcall ClosePlugin(HANDLE hPlugin); </syntaxhighlight> Close handle returned by OpenFilePlugin.
GetOpenPluginInfo()
<syntaxhighlight lang="c"> void __stdcall GetOpenPluginInfo(HANDLE hPlugin, OpenPluginInfo* Info); </syntaxhighlight> Get information about the open plugin instance. <syntaxhighlight lang="c"> typedef struct {
unsigned flags; // bit 0: add the item '..' if it is missing
// bit 1: copying is processed by the GetFiles
} OpenPluginInfo; </syntaxhighlight>
GetPanelTitle()
<syntaxhighlight lang="c"> void __stdcall GetPanelTitle(HANDLE hPlugin, char title[1024],
const char* host_file, const char* curdir);
</syntaxhighlight> Get the title of the plugin panel. host_file parameter coincides with the filename passed to OpenFilePlugin. Curdir parameter is equal to the current folder which is set by SetFolder.
ReadFolder()
<syntaxhighlight lang="c"> int __stdcall ReadFolder(HANDLE hPlugin, unsigned dirinfo_start,
unsigned dirinfo_size, void* dirdata);
</syntaxhighlight> Reads the current folder. The handle hPlugin was returned from OpenFilePlugin. dirinfo_start is the first file to read, dirinfo_size is how many files to read.
SetFolder()
<syntaxhighlight lang="c"> bool __stdcall SetFolder(HANDLE hPlugin, const char* relative_path, const char* absolute_path); </syntaxhighlight> Set the current folder. relative_path is the relative path (".." or the name of the subfolder) absolute_path is the absolute path (folder emulated by the plugin filesystem)
GetFiles()
<syntaxhighlight lang="c"> void __stdcall GetFiles(HANDLE hPlugin, int NumItems, void* items[], void* addfile, void* adddir);
bool __stdcall addfile(const char* name, void* bdfe_info, HANDLE hFile);
bool __stdcall adddir(const char* name, void* bdfe_info);
</syntaxhighlight>
Called to copy, if in the flags returned by GetOpenPluginInfo is set bit 1.
This function should be implemented when the standard recursive bypass of folders is inconvenient.
hPlugin is the descriptor created by OpenFilePlugin.
NumItems is the number of elements to copy.
items points to an array of elements to copy, each of which is given by pointer to a BDFE structure.
Special case: NumItems = -1, items = NULL means "all files" (in the current folder and subfolders).
addfile, adddir - callback-functions of kfar. Return false means "break up."
name must specify the name relative to the current folder.
bdfe_info is a pointer to a shortened (40 bytes) record in the format of sysfn 70.5
Opening and closing the handle hFile must be performed by the plugin. The addfile calls only read function.
getattr()
<syntaxhighlight lang="c"> int __stdcall getattr(HANDLE hPlugin, const char* filename, void* info); </syntaxhighlight> Get information about the file pointed to by filename. The return value and the data must correspond to system function 70.5
open()
<syntaxhighlight lang="c"> HANDLE __stdcall open(HANDLE hPlugin, const char* filename, int mode); </syntaxhighlight> Open the file filename. The mode parameter is reserved and must currently be set to 1.
read()
<syntaxhighlight lang="c"> unsigned __stdcall read(HANDLE hFile, void* buf, unsigned size); </syntaxhighlight> Read size bytes into the buffer buf from the file hFile, previously opened via open. KFAR ensures that the size is a multiple of 512 bytes. Return value: the number of bytes read, -1 on error
setpos()
<syntaxhighlight lang="c"> void __stdcall setpos(HANDLE hFile, __int64 pos); </syntaxhighlight> Set the current position to pos in the file hFile, previously opened by open. pos must be a multiple of 512 bytes
close()
<syntaxhighlight lang="c"> void __stdcall close(HANDLE hFile); </syntaxhighlight>