KFar-API: Difference between revisions

From KolibriOS wiki
Jump to navigation Jump to search
mNo edit summary
m (fix translation where logic was broken)
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The plugin is a standard kolibri library (COFF format)
The plugin is a standard kolibri library (COFF format).
The plugin must export the following functions and variables (some features may not be available).
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,
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.
And expects the same for the callback functions.
== plugin structure ==
<syntaxhighlight lang="c">
<syntaxhighlight lang="c">
int version;
int version;
</syntaxhighlight>
</syntaxhighlight>
KFAR interface version, current version is 2.
KFAR interface version, current version is 2.
<syntaxhighlight lang="c">
int __stdcall plugin_load(kfar_info* info);
</syntaxhighlight>
Called when the plugin is loaded.
<syntaxhighlight lang="c">
<syntaxhighlight lang="c">
typedef struct
typedef struct
Line 26: Line 22:
         void* open2;    // HANDLE __stdcall open2(int plugin_id, HANDLE plugin_instance,
         void* open2;    // HANDLE __stdcall open2(int plugin_id, HANDLE plugin_instance,
                         //                      const char* name, int mode);
                         //                      const char* name, int mode);
                         //  similar to open, but it opens the fle with the plugin panel
                         // similar to open, but it opens the file with the plugin panel
                         // open2(0,<anything>,name,mode) = open(name,mode)
                         // open2(0,<anything>,name,mode) = open(name,mode)
         void* read;    // unsigned __stdcall read(HANDLE hFile, void* buf, unsigned size);
         void* read;    // unsigned __stdcall read(HANDLE hFile, void* buf, unsigned size);
Line 37: Line 33:
  /* Functions to work with the memory (page) */
  /* Functions to work with the memory (page) */
         void* pgalloc;  // in: ecx=size, out: eax=pointer or NULL
         void* pgalloc;  // in: ecx=size, out: eax=pointer or NULL
                         // Out of memory informs the user and returns NULL
                         // Out of memory, informs the user and returns NULL
         void* pgrealloc; // in: edx=pointer, ecx=new size, out: eax=pointer or NULL
         void* pgrealloc; // in: edx=pointer, ecx=new size, out: eax=pointer or NULL
                         // Out of memory informs the user and returns NULL
                         // Out of memory, informs the user and returns NULL
         void* pgfree;  // in: ecx=pointer
         void* pgfree;  // in: ecx=pointer
         void* getfreemem;      // unsigned __stdcall getfreemem(void);
         void* getfreemem;      // unsigned __stdcall getfreemem(void);
Line 62: Line 58:
} kfar_info;
} kfar_info;
</syntaxhighlight>
</syntaxhighlight>
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);
== plugin_load() ==
Called to unload the plugin (when KFAR is being shut down).
<syntaxhighlight lang="c">
int __stdcall plugin_load(kfar_info* info);
</syntaxhighlight>
Called when the plugin is loaded.
{| class="wikitable"
|+ return
| 0
| align="left" | successful initialization
|-
| 1
| align="left" | Initialization error (KFAR will display a message to the user)
|-
| 2
| align="left" | 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).


HANDLE __stdcall OpenFilePlugin(HANDLE basefile,
== OpenFilePlugin() ==
<syntaxhighlight lang="c">
HANDLE __stdcall OpenFilePlugin(HANDLE basefile,
         const void* attr, const void* data, int datasize,
         const void* attr, const void* data, int datasize,
         int baseplugin_id, HANDLE baseplugin_instance, const char* name);
         int baseplugin_id, HANDLE baseplugin_instance, const char* name);
Opens plugin that emulates a filesystem on the basis of a file (for example, archive)
</syntaxhighlight>
Opens plugin that emulates a filesystem on the basis of a file (for example, archive)
{| class="wikitable"
|+ arguments
| 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)
|}


basefile - wich applies to read and seek in kfar_info
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).
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.
{| class="wikitable"
If the operation is interrupted by the user, return -1 .
|+ return
| 0
| plugin does not handle the transferred file
|-
| -1
| the operation is interrupted by the user
|}


void __stdcall ClosePlugin(HANDLE hPlugin);
== ClosePlugin() ==
Handle was returned from OpenFilePlugin
<syntaxhighlight lang="c">
void __stdcall ClosePlugin(HANDLE hPlugin);
</syntaxhighlight>
Close handle returned by '''OpenFilePlugin'''.


void __stdcall GetOpenPluginInfo(HANDLE hPlugin, OpenPluginInfo* Info);
== GetOpenPluginInfo() ==
Get information about the open plugin instance.
<syntaxhighlight lang="c">
typedef struct
void __stdcall GetOpenPluginInfo(HANDLE hPlugin, OpenPluginInfo* Info);
{
</syntaxhighlight>
        unsigned flags; // bit 0: add the item '..' if cleared
Get information about the open plugin instance.
                         // bit 1: copy is processed by the GetFiles
<syntaxhighlight lang="c">
} OpenPluginInfo;
typedef struct
{
        unsigned flags; // bit 0: add the item '..' if it is missing
                         // bit 1: copying is processed by the GetFiles
} OpenPluginInfo;
</syntaxhighlight>


void __stdcall GetPanelTitle(HANDLE hPlugin, char title[1024],
== GetPanelTitle() ==
<syntaxhighlight lang="c">
void __stdcall GetPanelTitle(HANDLE hPlugin, char title[1024],
         const char* host_file, const char* curdir);
         const char* host_file, const char* curdir);
Get the title of the plugin panel. Host_file parameter coincides with the filename passed
</syntaxhighlight>
in OpenFilePlugin. Curdir parameter is equal to the current folder which is set by SetFolder.
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'''.


int __stdcall ReadFolder(HANDLE hPlugin, unsigned dirinfo_start,
== ReadFolder() ==
<syntaxhighlight lang="c">
int __stdcall ReadFolder(HANDLE hPlugin, unsigned dirinfo_start,
         unsigned dirinfo_size, void* dirdata);
         unsigned dirinfo_size, void* dirdata);
Reads the current folder. hPlugin - returned from OpenFilePlugin handle.
</syntaxhighlight>
dirinfo_start - from where to read the file, dirinfo_size, how many files are read.
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.


bool __stdcall SetFolder(HANDLE hPlugin, const char* relative_path, const char* absolute_path);
== SetFolder() ==
Set the current folder. relative_path = realative path (".." or the name of the subfolder)
<syntaxhighlight lang="c">
absolute_path -  absolute path (folder emulated file system plugin)
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)


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


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