Libraries

KolibriOS libraries explained

This article assume's you know the basics of programming applications for KolibriOS in fasm, if not, start by reading this article Writing applications for KolibriOS.

First, when you want to start writing programs using libraries, you should get ahold of these four includes (they can be found with the libraries or on the SVN server):

• macros.inc
• proc32.inc
• dll.inc
• libcommon.inc

You will need to include them in your program, just place the includes in the same folder as your .asm file is, and put this inside your code (this should be right after your header, before the START label):

<asm> include 'proc32.inc' include 'macros.inc' include 'libcommon.inc' include 'dll.inc' </asm> After that, you'll need to think what library's you want to use, we can give each libary a name wich we'll need to use in the rest of our code:

<asm> align 16 @IMPORT:

library \

       library_name_i_can_choose ,'library_realname.obj',\
       libio ,'libio.obj',\
       libini ,'libini.obj' 

</asm>

Then, you'll need to read the specific library's documentation and think what function of what library you'll need.. We're going to import them into our program just beneath the above code, like this:

<asm> import library_name_i_can_choose, \

       function_name_i_can_choose_1,'real_function_name_1',\
       function_name_i_can_choose_2,'real_function_name_2',\
       function_name_i_can_choose_3,'real_function_name_3'

import libio, \

       file.aux.match_wildcard,'file.aux.match_wildcard',\
       file.find_first,'file.find_first',\
       file.find_next,'file.find_next',\
       file.find_close,'file.find_close',\
       file.open,'file.open',\
       file.seek,'file.seek',\
       file.write,'file.write',\
       file.truncate,'file.truncate',\
       file.close,'file.close'

</asm>

Apparently, you need to initialize the heap when your program is initialised. To do this, you may use system function 68 subfunction 11

like this:

<asm> START:

mcall 68,11 </asm>

The libraries will also need to be able to access the following procedures to work with ram. Place them somewhere in your code ;)

<asm> proc mem.Alloc size push ebx ecx mcall 68, 12, [size] pop ecx ebx ret endp

proc mem.ReAlloc mptr, size push ebx ecx edx

       mcall   68, 20, [size], [mptr]
       pop     edx ecx ebx

ret endp

proc mem.Free mptr

       push    ebx ecx
       mcall   68, 13, [mptr]
       pop     ecx ebx
       ret

endp </asm>

Now we would like our program to load the libraries We're going to use a function from dll.inc for this. Just put this at the beginning of your code: (Note how the @IMPORT refers to the above code)

<asm>

       stdcall dll.Load, @IMPORT
       or      eax, eax            ; This code will check if the program was able to
                                   ; load the libraries successfull
       jnz     EXIT                ; If not, it will jump to the label EXIT

</asm>

After that, and when you have putted your libraries in the /sys/lib/ folder (if they werent already there :), it's time to start the real work..

You can use the invoke function (from proc32.inc) to use any of the functions you included Like this:

<asm>

       invoke function_name_i_can_choose_1 ascii_string1, 0xAFB123, 1237

ascii_string1 db 'blablabla',0 </asm>

This will call the function 'real_function_name_1' from 'library_realname.obj' and pass ascii_string1, 0xAFB123 and 1237 to it. To know what you need to pass to each function, you need to read the library's documentation...

Good luck!