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.

return

0	successful initialization
1	Initialization error (KFAR will display 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)

arguments

basefile	wich applies to read and seek in kfar_info
attr	a pointer to a structure with the attributes of a file, analogue 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 min 1024
baseplugin_id	ID plug on the panel which is opened by the file; 0 in case of conventional panels
baseplugin_instance	The handle returned from the function GetOpenPluginInfo plugin, determined in baseplug_id
name	the name of the file (in a temporary buffer) (full name relative baseplugin)

If the plugin handles the uploaded file, it must return the new descriptor which will later be used to refer to kfar plugin. In this case, plugin must independently close basefile using close function of kfar_info (eg closing handle plugin or directly ClosePlugin OpenFilePlugin, if basefile is not needed any more).

return

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> Handle was returned from 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 cleared
                        // bit 1: copy 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 in 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. hPlugin - returned from OpenFilePlugin handle. dirinfo_start - from where to read the file, dirinfo_size, how many files are 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 = realative path (".." or the name of the subfolder) absolute_path -  absolute path (folder emulated file system plugin)

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 the flags are returned GetOpenPluginInfo, set bit 1. This function should be implemented in the event that the standard recursive folders are inconvenient. hPlugin - descriptor created in OpenFilePlugin. NumItems - The number of elements to copy. items - an array of elements to copy, each of which is given a pointer to a structure BDFE Special case: NumItems = -1, items = NULL means "all files" (in the current folder and subfolders). addfile, adddir - callback-function kfar' . Return false means "break up." The name parameter must specify the name of the current folder. Parameter bdfe_info is a pointer to a shortened (40 bytes) recording format as in sysfn 70.5 Opening and closing the handle hFile must be performed by the plugin. The addfile function is only called by read.

getattr()

<syntaxhighlight lang="c"> int __stdcall getattr(HANDLE hPlugin, const char* filename, void* info); </syntaxhighlight> Get information about the file. The ruturn value and the data must conform to the info of systemfunction 70.5

open()

<syntaxhighlight lang="c"> HANDLE __stdcall open(HANDLE hPlugin, const char* filename, int mode); </syntaxhighlight> Open the file filename. The mode parameters is resurved and must 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 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>