Libraries

From KolibriOS wiki

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 programming applications.

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):

include 'proc32.inc'
include 'macros.inc'
include 'libcommon.inc'
include 'dll.inc' 

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:

align 16
@IMPORT:

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

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:

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'

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:

START:

mcall   68,11  

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

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

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)

        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

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:

        invoke function_name_i_can_choose_1 ascii_string1, 0xAFB123, 1237

ascii_string1 db 'blablabla',0

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!