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
       mov     eax,[size]
       lea     ecx,[eax+4+4095]
       and     ecx,not 4095
       mcall   68,12
       add     ecx,-4
       mov     [eax],ecx
       add     eax,4
       pop     ecx ebx
       ret

endp

-----------------------------------------------------------------------------

proc mem.ReAlloc mptr,size;///////////////////////////////////////////////////

-----------------------------------------------------------------------------

       push    ebx ecx esi edi eax
       mov     eax,[mptr]
       mov     ebx,[size]
       or      eax,eax
       jz      @f
       lea     ecx,[ebx+4+4095]
       and     ecx,not 4095
       add     ecx,-4
       cmp     ecx,[eax-4]
       je      .exit
   @@: mov     eax,ebx
       call    mem.Alloc
       xchg    eax,[esp]
       or      eax,eax
       jz      .exit
       mov     esi,eax
       xchg    eax,[esp]
       mov     edi,eax
       mov     ecx,[esi-4]
       cmp     ecx,[edi-4]
       jbe     @f
       mov     ecx,[edi-4]
   @@: add     ecx,3
       shr     ecx,2
       cld
       rep     movsd
       xchg    eax,[esp]
       call    mem.Free
 .exit:
       pop     eax edi esi ecx ebx
       ret

endp

-----------------------------------------------------------------------------

proc mem.Free mptr ;//////////////////////////////////////////////////////////

-----------------------------------------------------------------------------

       mov     eax,[mptr]
       or      eax,eax
       jz      @f
       push    ebx ecx
       lea     ecx,[eax-4]
       mcall   68,13
       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!