Difference between revisions of "Libs-dev/libini"
(Initial libini documentation) |
(No difference)
|
Revision as of 10:13, 23 July 2010
INI files are structured human-readable text files. Each file consists of one or more sections (text within square braces), each having several keys (text before "=" sign) with corresponding values (text after "=" sign). Here's the example of such file:
[fruits]
banana = yellow
orange = orange
rosberry = red
[vegetables]
cucumber = green
Section names should be unique within file scope. Key names should be unique within section scope. This means, there could be keys with same names located in different sections, but no two sections with same name within a file.
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
- ini filename <asciiz>
- _callback
- callback function address: func(f_name, sec_name), where
- f_name
- ini filename (as passed to the function) <asciiz>
- sec_name
- section name found <asciiz>
Result:
- eax
- -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
- ini filename <asciiz>
- _sec_name
- section name <asciiz>
- _callback
- callback function address: func(f_name, sec_name, key_name, key_value), where
- f_name
- ini filename (as passed to the function) <asciiz>
- sec_name
- section name (as passed to the function) <asciiz>
- key_name
- key name found <asciiz>
- key_value
- value of key found <asciiz>
Result:
- eax
- -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
- ini filename <asciiz>
- _sec_name
- section name <asciiz>
- _key_name
- key name <asciiz>
- _buffer
- destination buffer address <byte*>
- _buf_len
- buffer size (maximum bytes to read) <dword>
- _def_val
- default value to return if no key, section or file found <asciiz>
Result:
- eax
- -1 (error) / 0
- [_buffer]
- [_def_val] (error) / found key value <asciiz>
ini_set_str
Write string.
Prototype:
- proc ini.set_str _f_name, _sec_name, _key_name, _buffer, _buf_len
Arguments:
- _f_name
- ini filename <asciiz>
- _sec_name
- section name <asciiz>
- _key_name
- key name <asciiz>
- _buffer
- source buffer address <byte*>
- _buf_len
- buffer size (bytes to write) <dword>
Result:
- eax
- -1 (error) / 0
ini_get_int
Read integer.
Prototype:
- proc ini.get_int _f_name, _sec_name, _key_name, _def_val
Arguments:
- _f_name
- ini filename <asciiz>
- _sec_name
- section name <asciiz>
- _key_name
- key name <asciiz>
- _def_val
- default value to return if no key, section or file found <dword>
Result:
- eax
- [_def_val] (error) / found key value <dword>
ini_set_int
Write integer.
Prototype:
- proc ini.set_int _f_name, _sec_name, _key_name, _val
Arguments:
- _f_name
- ini filename <asciiz>
- _sec_name
- section name <asciiz>
- _key_name
- key name <asciiz>
- _val
- value <dword>
Result:
- eax
- -1 (error) / 0
ini_get_color
Read color.
Prototype:
- proc ini.get_color _f_name, _sec_name, _key_name, _def_val
Arguments:
- _f_name
- ini filename <asciiz>
- _sec_name
- section name <asciiz>
- _key_name
- key name <asciiz>
- _def_val
- default value to return if no key, section or file found <dword>
Result:
- eax
- [_def_val] (error) / found key value <dword>
ini_set_color
Write color.
Prototype:
- proc ini.set_color _f_name, _sec_name, _key_name, _val
Arguments:
- _f_name
- ini filename <asciiz>
- _sec_name
- section name <asciiz>
- _key_name
- key name <asciiz>
- _val
- value <dword>
Result:
- eax
- -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
- ini filename <asciiz>
- _sec_name
- section name <asciiz>
- _key_name
- key name <asciiz>
- _def_val
- default value to return if no key, section or file found <dword>
- _modifiers
- pointer to dword variable which receives modifiers state as in 66.4 <dword*>
Result:
- eax
- [_def_val] (error) / shortcut key value as scancode <int>
- [[_modifiers]]
- unchanged (error) / modifiers state for this shortcut <int>