Libs-dev/libini

From KolibriOS wiki
Jump to: navigation, search

INI files are structured human-readable text files. Each file consists of one or more sections, each having several keys with values. Here's the example of such file:

[fruit colors]
banana = yellow
orange = orange
strawberry = red
 
[vegetable colors]
cucumber = green

Section names are embraced with square braces and are one-line strings which may contain any characters. Sections divide file into parts, where keys and their corresponding values are specified. In the begining of file (before the first section) there may also be keys and values found which aren't in any section. Keys and values are also one-line strings which are separated from each other with equality sign "=". Key name of course can't contain "=" character. Key value is the string after first "=" character found in line till the end on line.

Section names, key names and key values are trimmed i.e. space characters are deleted from the beginning and end of the strings during comparison.

If each section identifies the set of keys, each key in turn identifies one value. Section and key names don't have to be unique, but if there're two keys (within a section) with the same name, value will be read and written from the one which appears earlier in the file.

For all file operations, libini uses libio.

Functions (enumerating entities)

ini_enum_sections

Enumerate sections, calling callback function for each of them.

Prototype:

proc ini.enum_sections _f_name, _callback

Arguments:

_f_name → asciiz
ini filename
_callback
callback function address: func(f_name, sec_name), where
f_name → asciiz
ini filename (as passed to the function)
sec_name → asciiz
section name found

Result:

eax → dword
-1 (error) / 0

ini_enum_keys

Enumerate keys within a section, calling callback function for each of them.

Prototype:

proc ini.enum_keys _f_name, _sec_name, _callback

Arguments:

_f_name → asciiz
ini filename
_sec_name → asciiz
section name
_callback
callback function address: func(f_name, sec_name, key_name, key_value), where
f_name → asciiz
ini filename (as passed to the function)
sec_name → asciiz
section name (as passed to the function)
key_name → asciiz
key name found
key_value → asciiz
value of key found

Result:

eax → dword
-1 (error) / 0

Functions (getting and setting values)

All the getter functions are fail-safe, returning supplied default value on any error.

ini_get_str

Read string.

Prototype:

proc ini.get_str _f_name, _sec_name, _key_name, _buffer, _buf_len, _def_val

Arguments:

_f_name → asciiz
ini filename
_sec_name → asciiz
section name
_key_name → asciiz
key name
_buffer → byte*
destination buffer address
_buf_len → dword
buffer size (maximum bytes to read)
_def_val → asciiz
default value to return if no key, section or file found

Result:

eax → dword
-1 (error) / 0
[_buffer] → asciiz
[_def_val] (error) / found key value

ini_set_str

Write string.

Prototype:

proc ini.set_str _f_name, _sec_name, _key_name, _buffer, _buf_len

Arguments:

_f_name → asciiz
ini filename
_sec_name → asciiz
section name
_key_name → asciiz
key name
_buffer → byte*
source buffer address
_buf_len → dword
buffer size (bytes to write)

Result:

eax → dword
-1 (error) / 0

ini_get_int

Read integer.

Prototype:

proc ini.get_int _f_name, _sec_name, _key_name, _def_val

Arguments:

_f_name → asciiz
ini filename
_sec_name → asciiz
section name
_key_name → asciiz
key name
_def_val → dword
default value to return if no key, section or file found

Result:

eax → dword
[_def_val] (error) / found key value

ini_set_int

Write integer.

Prototype:

proc ini.set_int _f_name, _sec_name, _key_name, _val

Arguments:

_f_name → asciiz
ini filename
_sec_name → asciiz
section name
_key_name → asciiz
key name
_val → dword
value

Result:

eax → dword
-1 (error) / 0

ini_get_color

Read color.

Prototype:

proc ini.get_color _f_name, _sec_name, _key_name, _def_val

Arguments:

_f_name → asciiz
ini filename
_sec_name → asciiz
section name
_key_name → asciiz
key name
_def_val → dword
default value to return if no key, section or file found

Result:

eax → dword
[_def_val] (error) / found key value

ini_set_color

Write color.

Prototype:

proc ini.set_color _f_name, _sec_name, _key_name, _val

Arguments:

_f_name → asciiz
ini filename
_sec_name → asciiz
section name
_key_name → asciiz
key name
_val → dword
value

Result:

eax → dword
-1 (error) / 0

ini_get_shortcut

Read shortcut key.

Prototype:

proc ini.get_shortcut _f_name, _sec_name, _key_name, _def_val, _modifiers

Arguments:

_f_name → asciiz
ini filename
_sec_name → asciiz
section name
_key_name → asciiz
key name
_def_val → dword
default value to return if no key, section or file found
_modifiers → dword*
pointer to dword variable which receives modifiers state as in 66.4

Result:

eax → dword
[_def_val] (error) / shortcut key value as scancode
[[_modifiers]] → dword
unchanged (error) / modifiers state for this shortcut

Usage examples

This one enumerates sections, and then enumerates keys for each section in its callback. Note that we use "invoke" here since the call is indirect.

  1. ; ...
  2.  
  3.         invoke  ini_enum_sections, filename, ini_section_callback
  4.  
  5. ; ...
  6.  
  7. proc ini_section_callback _filename, _section_name
  8.         ; this function is being called by library for each section found in the file
  9.  
  10.         invoke  ini_enum_keys, [_filename], [_section_name], ini_key_callback
  11.  
  12.         ; ...
  13.  
  14.         ret
  15. endp 
  16.  
  17. proc ini_key_callback _filename, _section_name, _key_name, _key_value
  18.         ; this function is being called by library for each key of each section found in the file
  19.  
  20.         ; ...
  21.  
  22.         ret
  23. endp
  24.  
  25. ; ...
  26.  
  27. filename db '/hd0/1/a.ini', 0