Libs-dev: Difference between revisions

From KolibriOS wiki
Jump to navigation Jump to search
(Initial documentation version, covering libio. Should probably be separated into separate subpages.)
 
mNo edit summary
 
(12 intermediate revisions by one other user not shown)
Line 1: Line 1:
=Introduction=
Libs-dev is a system libraries collection targeting different problematic programming areas.
Libs-dev is a system libraries collection targeting different problematic programming areas.


Line 6: Line 5:


==libio==
==libio==
Right now, libio provides API to only work with files, although other communication types (like pipes) are also planned.
<small>''Main article: [[Libs-dev/libio]]''</small>
By default, library is compiled to use OEM file names. Support for Unicode file names is also present but requires include file to be changed and library to be recompiled.


===functions (enumerating files)===
Library provides routines to perform basic file I/O like opening, closing, reading, writing, truncating files, getting and setting file pointer position. There're also routines to enumerate files inside specific directory with names matching shell pattern.


====file_find_first====
It should usually be used by programs which need to perform low-level file operations.
Find first file with matching attributes and mask in specified directory.


Prototype:
==libini==
:<tt>proc file.find_first _dir, _mask, _attr</tt>
<small>''Main article: [[Libs-dev/libini]]''</small>


Arguments:
Library provides routines to work with INI files which are key-value based text files with possibility to be edited by user by hand in any external editor.
:<tt>_dir</tt>
::directory path to search in <asciiz>
:<tt>_mask</tt>
::file mask, with use of wildcards <asciiz>
:<tt>_attr</tt>
::file attributes mask (combination of FA_* constants) <dword>


Result:
It should usually be used by programs which need to save and load their settings in platform-independent way.
:<tt>eax</tt>
::0 (error) / matched file data pointer (acts as find descriptor) <FileInfo*>


====file_find_next====
==libimg==
Find next file matching criteria.
<small>''Main article: [[Libs-dev/libimg]]''</small>


Prototype:
Library provides routines to work with graphics files and containers. It's made extensible and could transparently decode images in different formats identifying them by file signatures and other guessing techniques.
:<tt>proc file.find_next _findd</tt>


Arguments:
It should usually be used by programs which need to display pictures in their UI (for example, icons on tool buttons).
:<tt>_findd</tt>
::find descriptor (see [[#file_find_first|file_find_first]]) <FileInfo*>
 
Result:
:<tt>eax</tt>
::0 (error) / matched file data pointer (acts as find descriptor) <FileInfo*>
 
====file_find_close====
Close find descriptor and free memory.
 
Prototype:
:<tt>proc file.find_close _findd</tt>
 
Arguments:
:<tt>_findd</tt>
::find descriptor (see [[#file_find_first|file_find_first]]) <FileInfo*>
 
Result:
:<tt>eax</tt>
::result of memory freeing routine
 
===functions (working with specific file)===
 
====file_size====
Get file size.
 
Prototype:
:<tt>proc file.size _name</tt>
 
Arguments:
:<tt>_name</tt>
::path to file (full or relative) <asciiz>
 
Result:
:<tt>eax</tt>
::-1 (error) / file size (in bytes, up to 2G) <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_open====
Open file.
 
Prototype:
:<tt>proc file.open _name, _mode</tt>
 
Arguments:
:<tt>_name</tt>
::path to file (full or relative) <asciiz>
:<tt>_mode</tt>
::mode to open file in (combination of O_* constants) <dword>
::<tt>O_BINARY</tt>
:::don't change read/written data in any way (default)
::<tt>O_READ</tt>
:::open file for reading
::<tt>O_WRITE</tt>
:::open file for writing
::<tt>O_CREATE</tt>
:::create file if it doesn't exist, open otherwise
::<tt>O_SHARE</tt>
:::allow simultaneous access by using different file descriptors (not implemented)
::<tt>O_TEXT</tt>
:::replace newline chars with LF (overrides O_BINARY, not implemented)
 
Result:
:<tt>eax</tt>
::0 (error) / file descriptor <InternalFileInfo*>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_read====
Read data from file.
 
Prototype:
:<tt>proc file.read _filed, _buf, _buflen</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
:<tt>_buf</tt>
::buffer to put read data to <byte*>
:<tt>_buflen</tt>
::buffer size (number of bytes to be read from file) <dword>
 
Result:
:<tt>eax</tt>
::-1 (error) / number of bytes read <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_write====
Write data to file.
 
Prototype:
:<tt>proc file.write _filed, _buf, _buflen</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
:<tt>_buf</tt>
::buffer to get write data from <byte*>
:<tt>_buflen</tt>
::buffer size (number of bytes to be written to file) <dword>
 
Result:
:<tt>eax</tt>
::-1 (error) / number of bytes written <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_seek====
Set file pointer position.
 
Prototype:
:<tt>proc file.seek _filed, _where, _origin</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
:<tt>_where</tt>
::position in file (in bytes) counted from specified origin <dword>
:<tt>_origin</tt>
::origin from where to set the position (one of SEEK_* constants) <dword>
::<tt>SEEK_SET</tt>
:::from beginning of file
::<tt>SEEK_CUR</tt>
:::from current pointer position
::<tt>SEEK_END</tt>
:::from end of file
 
Result:
:<tt>eax</tt>
::-1 (error) / 0 <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_iseof====
Determine if file pointer is at the end of file.
 
Prototype:
:<tt>proc file.eof? _filed</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
 
Result:
:<tt>eax</tt>
::false / true <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_truncate (file_seteof)====
Truncate file size to current file pointer position:
 
Prototype:
:<tt>proc file.truncate _filed</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
 
Result:
:<tt>eax</tt>
::-1 (error) / 0 <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_tell====
Get current file pointer position.
 
Prototype:
:<tt>proc file.tell _filed</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
 
Result:
:<tt>eax</tt>
::-1 (error) / file pointer position <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
====file_close====
Close file.
 
Prototype:
:<tt>proc file.close _filed</tt>
 
Arguments:
:<tt>_filed</tt>
::file descriptor (see [[#file_open|file_open]]) <InternalFileInfo*>
 
Result:
:<tt>eax</tt>
::-1 (error) / file pointer position <dword>
 
Notes:
:call [[#file_err|file_err]] to obtain extended error information
 
===constants===
 
====file open mode====
O_BINARY = 00000000b
O_READ  = 00000001b
O_WRITE  = 00000010b
O_CREATE = 00000100b
O_SHARE  = 00001000b
O_TEXT  = 00010000b
 
====file seek origin====
SEEK_SET = 0
SEEK_CUR = 1
SEEK_END = 2
 
==== file attributes====
FA_READONLY = 00000001b
FA_HIDDEN  = 00000010b
FA_SYSTEM  = 00000100b
FA_LABEL    = 00001000b
FA_FOLDER  = 00010000b
FA_ARCHIVED = 00100000b
FA_ANY      = 00111111b
 
===structures===
 
====FileDateTime====
Date and time as returned by underlying system calls.
 
struct FileDateTime
  union
    time    dd ?
    struct
      sec  db ?
      min  db ?
      hour  db ?
    ends
  ends
  union
    date    dd ?
    struct
      day  db ?
      month db ?
      year  dw ?
    ends
  ends
ends
 
====FileInfoBlock====
File information block used by underlying system calls to identify function to be called and its basic arguments. Should generally not be used by programs.
 
struct FileInfoBlock
  Function  dd ?
  Position  dd ?
  Flags      dd ?
  Count      dd ?
  Buffer    dd ?
              db ?
  FileName  dd ?
ends
 
====FileInfoHeader====
File information header as returned by underlying call to [[SysFn70|70.1]] system function. Should generally not be used by programs.
 
struct FileInfoHeader
  Version    dd ?
  FilesRead  dd ?
  FilesCount dd ?
              rd 5
ends
 
====FileInfoA====
OEM version of FileInfo structure.
 
struct FileInfoA
  Attributes  dd ?
  Flags        dd ?
  DateCreate  FileDateTime
  DateAccess  FileDateTime
  DateModify  FileDateTime
  union
    FileSize  dq ?
    struct
      FileSizeLow  dd ?
      FileSizeHigh dd ?
    ends
  ends
  FileName    rb 252
ends
 
====FileInfoW====
Unicode version of FileInfo structure.
 
struct FileInfoW
  Attributes  dd ?
  Flags        dd ?
  DateCreate  FileDateTime
  DateAccess  FileDateTime
  DateModify  FileDateTime
  union
    FileSize  dq ?
    struct
      FileSizeLow  dd ?
      FileSizeHigh dd ?
    ends
  ends
  FileName    rw 260
ends
 
===usage examples===
Small piece of code illustrating file opening, reading 256 bytes, seeking to the beginning, writing same data back and closing file descriptor. Note that we could succeessfully read less than 256 bytes, so we remember the exact number.
 
<source>
include 'libio/libio.inc'
 
; ...
 
        stdcall file_open, filename, O_READ + O_WRITE
        or      eax, eax
        jz      .error
 
        mov    [fdesc], eax
        stdcall file_read, eax, buffer, 256
        mov    [bytes_read], eax
        inc    eax
        jz      .close
 
        stdcall file_seek, [fdesc], 0, SEEK_SET
        inc    eax
        jz      .close
 
        stdcall file_write, [fdesc], buffer, [bytes_read]
 
  .close:
        stdcall file_close, [fdesc]
  .error:
 
; ...
 
filename  db '/hd0/1/a.dat', 0
fdesc      dd ?
bytes_read dd ?
buffer    db 256 dup(?)
</source>
 
==libini==


==libgfx==
<small>''Main article: [[Libs-dev/libgfx]]''</small>


==libimg==
Library provides routines to draw different graphics primitives like dots, lines, rectangles, bars, circles etc. It uses canvas abstraction to be able to perform buffered off-screen drawing.
 
 
==libgfx==


It should usually be used by programs which need to draw any graphics on screen (which are almost all the programs to date since Kolibri is a pure GUI OS).


=Libraries tests=
=Libraries tests=
There's a <tt>.test</tt> directory containing different libraries tests. They are designed to be independent and should generate (or contain pre-generated) test data which leads to same results disregarding the order tests are executed in.
There's a <tt>.test</tt> directory containing different libraries tests. They are designed to be independent and should generate (or contain pre-generated) test data which leads to same results disregarding the order tests are executed in.
[[Kiv/ru|KIV]] program was initially based on one of such tests (002) using '''libio''' and '''libimg''' libraries to show their capabilities in a small GUI application able to display picture at path supplied by command-line parameter.


=Coding style=
=Coding style=
All the public functions are contained in <tt><library name>.asm</tt> file, supporting public declarations in <tt><library name>.inc</tt> file. All other library-specific (private and auxilary) core functions and declarations are separated into <tt><library name>_p.asm</tt> and <tt><library name>_p.inc</tt> files. There could also be separate files with self-describing names providing additional functionality.
All the public functions are contained in <tt><library name>.asm</tt> file, supporting public declarations in <tt><library name>.inc</tt> file. All other library-specific (private and auxiliary) core functions and declarations are separated into <tt><library name>_p.asm</tt> and <tt><library name>_p.inc</tt> files. There could also be separate files with self-describing names providing additional functionality.
 
Functions located in public source files use naming convention as in <tt><function namespace name>.<function name></tt>. Functions located in private source files use naming convention as in <tt><library name>._.<function name></tt>. This allows to separate libraries code when linking statically.


Specific type of function description comments is being used allowing documentation to be generated automatically in the future.
Specific type of function description comments is being used allowing documentation to be generated automatically in the future.
=See also=
* [[Libraries|KolibriOS libraries explained]]


[[Category:Coding]][[Category:Manuals]]
[[Category:Coding]][[Category:Manuals]]
[[Category:Libraries]]

Latest revision as of 21:56, 27 July 2010

Libs-dev is a system libraries collection targeting different problematic programming areas.

Libraries description

Libs-dev now consists of four common-use libraries: libio (input-output programming), libini (INI-like files support), libimg (graphics files manipulation) and libgfx (drawing convenience API).

libio

Main article: Libs-dev/libio

Library provides routines to perform basic file I/O like opening, closing, reading, writing, truncating files, getting and setting file pointer position. There're also routines to enumerate files inside specific directory with names matching shell pattern.

It should usually be used by programs which need to perform low-level file operations.

libini

Main article: Libs-dev/libini

Library provides routines to work with INI files which are key-value based text files with possibility to be edited by user by hand in any external editor.

It should usually be used by programs which need to save and load their settings in platform-independent way.

libimg

Main article: Libs-dev/libimg

Library provides routines to work with graphics files and containers. It's made extensible and could transparently decode images in different formats identifying them by file signatures and other guessing techniques.

It should usually be used by programs which need to display pictures in their UI (for example, icons on tool buttons).

libgfx

Main article: Libs-dev/libgfx

Library provides routines to draw different graphics primitives like dots, lines, rectangles, bars, circles etc. It uses canvas abstraction to be able to perform buffered off-screen drawing.

It should usually be used by programs which need to draw any graphics on screen (which are almost all the programs to date since Kolibri is a pure GUI OS).

Libraries tests

There's a .test directory containing different libraries tests. They are designed to be independent and should generate (or contain pre-generated) test data which leads to same results disregarding the order tests are executed in.

KIV program was initially based on one of such tests (002) using libio and libimg libraries to show their capabilities in a small GUI application able to display picture at path supplied by command-line parameter.

Coding style

All the public functions are contained in <library name>.asm file, supporting public declarations in <library name>.inc file. All other library-specific (private and auxiliary) core functions and declarations are separated into <library name>_p.asm and <library name>_p.inc files. There could also be separate files with self-describing names providing additional functionality.

Functions located in public source files use naming convention as in <function namespace name>.<function name>. Functions located in private source files use naming convention as in <library name>._.<function name>. This allows to separate libraries code when linking statically.

Specific type of function description comments is being used allowing documentation to be generated automatically in the future.

See also

Retrieved from "http://wiki.kolibrios.org/index.php?title=Libs-dev&oldid=2992"