KFar-API

From KolibriOS wiki
Revision as of 13:24, 31 August 2012 by XVilka (talk | contribs)
Jump to navigation Jump to search

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.

int version;

KFAR interface version, current version is 2.

int __stdcall plugin_load(kfar_info* info);

Called when the plugin is loaded.

,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;
Return value:
0 = successful initialization
1 = Initialization error (KFAR will display to the user)
2 = Initialization error (KFAR will continue without informing the user)
void __stdcall plugin_unload(void);
Called to unload the plugin (when KFAR is being shut down).
HANDLE __stdcall OpenFilePlugin(HANDLE basefile,
        const void* attr, const void* data, int datasize,
        int baseplugin_id, HANDLE baseplugin_instance, const char* name);
Opens plugin that emulates a filesystem on the basis of a file (for example, archive)
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).
If the plugin does not handle the transferred file, it should return 0.
If the operation is interrupted by the user, return -1 .
void __stdcall ClosePlugin(HANDLE hPlugin);
Handle was returned from OpenFilePlugin
void __stdcall GetOpenPluginInfo(HANDLE hPlugin, OpenPluginInfo* Info);
Get information about the open plugin instance.
typedef struct
{
        unsigned flags; // bit 0: add the item '..' if cleared
                        // bit 1: copy is processed by the GetFiles
} OpenPluginInfo;
void __stdcall GetPanelTitle(HANDLE hPlugin, char title[1024],
        const char* host_file, const char* curdir);
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.
int __stdcall ReadFolder(HANDLE hPlugin, unsigned dirinfo_start,
        unsigned dirinfo_size, void* dirdata);
Reads the current folder. hPlugin - returned from OpenFilePlugin handle.
dirinfo_start - from where to read the file, dirinfo_size, how many files are read.
bool __stdcall SetFolder(HANDLE hPlugin, const char* relative_path, const char* absolute_path);
Set the current folder. relative_path = realative path (".." or the name of the subfolder)
absolute_path -  absolute path (folder emulated file system plugin)
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);
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.
int __stdcall getattr(HANDLE hPlugin, const char* filename, void* info);
Get information about the file. The ruturn value and the data must conform to the info of systemfunction 70.5
HANDLE __stdcall open(HANDLE hPlugin, const char* filename, int mode);
Open the file filename. The mode parameters is resurved and must be set to 1.
unsigned __stdcall read(HANDLE hFile, void* buf, unsigned size);
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
void __stdcall setpos(HANDLE hFile, __int64 pos);
Set the current position in the file hFile, previously opened by open.
Pos must be a multiple of 512 bytes
void __stdcall close(HANDLE hFile);