KFar-API: Difference between revisions

From KolibriOS wiki
Jump to navigation Jump to search
m (fix translation where logic was broken)
 
(19 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 ==
== plugin structure ==
<syntaxhighlight lang="c">
<syntaxhighlight lang="c">
Line 23: 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 34: 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 59: Line 58:
} kfar_info;
} kfar_info;
</syntaxhighlight>
</syntaxhighlight>
== plugin_load() ==
== plugin_load() ==
<syntaxhighlight lang="c">
<syntaxhighlight lang="c">
Line 64: Line 64:
</syntaxhighlight>
</syntaxhighlight>
Called when the plugin is loaded.
Called when the plugin is loaded.
Return value:
{| class="wikitable"
0 = successful initialization
|+ return
1 = Initialization error (KFAR will display to the user)
| 0
2 = Initialization error (KFAR will continue without informing the user)
| 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() ==
== plugin_unload() ==
Line 82: Line 89:
</syntaxhighlight>
</syntaxhighlight>
Opens plugin that emulates a filesystem on the basis of a file (for example, archive)
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
{| class="wikitable"
attr - a pointer to a structure with the attributes of a file, analogue to sysfn 70.1
|+ arguments
data - the buffer containing the data from the beginning of the file (can be used to determine the file type)
| basefile
datasize - data size in the data. In the current implmentation min 1024
| file handle (which functions read and seek in kfar_info are applied to)
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
| attr
name - the name of the file (in a temporary buffer) (full name relative baseplugin)
| 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 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 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).


If the plugin does not handle the transferred file, it should return 0. If the operation is interrupted by the user, return -1 .
 
{| class="wikitable"
|+ return
| 0
| plugin does not handle the transferred file
|-
| -1
| the operation is interrupted by the user
|}


== ClosePlugin() ==
== ClosePlugin() ==
Line 98: Line 129:
void __stdcall ClosePlugin(HANDLE hPlugin);
void __stdcall ClosePlugin(HANDLE hPlugin);
</syntaxhighlight>
</syntaxhighlight>
Handle was returned from OpenFilePlugin
Close handle returned by '''OpenFilePlugin'''.


== GetOpenPluginInfo() ==
== GetOpenPluginInfo() ==
Line 108: Line 139:
typedef struct
typedef struct
{
{
         unsigned flags; // bit 0: add the item '..' if cleared
         unsigned flags; // bit 0: add the item '..' if it is missing
                         // bit 1: copy is processed by the GetFiles
                         // bit 1: copying is processed by the GetFiles
} OpenPluginInfo;
} OpenPluginInfo;
</syntaxhighlight>
</syntaxhighlight>
Line 118: Line 149:
         const char* host_file, const char* curdir);
         const char* host_file, const char* curdir);
</syntaxhighlight>
</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.
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() ==
== ReadFolder() ==
Line 125: Line 156:
         unsigned dirinfo_size, void* dirdata);
         unsigned dirinfo_size, void* dirdata);
</syntaxhighlight>
</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.
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() ==
== SetFolder() ==
Line 131: Line 162:
bool __stdcall SetFolder(HANDLE hPlugin, const char* relative_path, const char* absolute_path);
bool __stdcall SetFolder(HANDLE hPlugin, const char* relative_path, const char* absolute_path);
</syntaxhighlight>
</syntaxhighlight>
Set the current folder. relative_path = realative path (".." or the name of the subfolder)
Set the current folder. '''relative_path''' is the relative path (".." or the name of the subfolder)
absolute_path -  absolute path (folder emulated file system plugin)
'''absolute_path''' is the absolute path (folder emulated by the plugin filesystem)


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


== getattr() ==
== getattr() ==
Line 155: Line 186:
int __stdcall getattr(HANDLE hPlugin, const char* filename, void* info);
int __stdcall getattr(HANDLE hPlugin, const char* filename, void* info);
</syntaxhighlight>
</syntaxhighlight>
Get information about the file. The ruturn value and the data must conform to the info of systemfunction 70.5
Get information about the file pointed to by '''filename'''. The return value and the data must correspond to system function 70.5


== open() ==
== open() ==
Line 161: Line 192:
HANDLE __stdcall open(HANDLE hPlugin, const char* filename, int mode);
HANDLE __stdcall open(HANDLE hPlugin, const char* filename, int mode);
</syntaxhighlight>
</syntaxhighlight>
Open the file filename. The mode parameters is resurved and must be set to 1.
Open the file '''filename'''. The '''mode''' parameter is reserved and must currently be set to 1.


== read() ==
== read() ==
unsigned __stdcall read(HANDLE hFile, void* buf, unsigned size);
<syntaxhighlight lang="c">
Read size bytes into the buffer buf from the file hFile, previously opened via open.
unsigned __stdcall read(HANDLE hFile, void* buf, unsigned size);
KFAR ensures that the size is a multiple of 512 bytes.
</syntaxhighlight>
Return value: The number of bytes read, -1 on error
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() ==
== setpos() ==
void __stdcall setpos(HANDLE hFile, __int64 pos);
<syntaxhighlight lang="c">
Set the current position in the file hFile, previously opened by open.
void __stdcall setpos(HANDLE hFile, __int64 pos);
Pos must be a multiple of 512 bytes
</syntaxhighlight>
Set the current position to '''pos''' in the file '''hFile''', previously opened by '''open'''.
'''pos''' must be a multiple of 512 bytes


== close() ==
== close() ==
<syntaxhighlight lang="c">
void __stdcall close(HANDLE hFile);
void __stdcall close(HANDLE hFile);
</syntaxhighlight>
[[Category:Manuals]]
[[Category:Coding]]

Latest revision as of 19:50, 31 August 2012

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);
        v