Libs-dev/libini/ru

From KolibriOS wiki
Jump to: navigation, search

INI файлы — структурированные текстовые файлы, легко воспринимаемые человеком. Каждый файл состоит из нескольких секций, в каждой из которых находится несколько ключей со значениями. Вот пример такого файла:

[цвета фруктов]
банан = жёлтый
апельсин = оранжевый
клубника = красный
 
[цвета овощей]
огурец = зелёный

Имена секций заключены в квадратные скобки, пишутся в одну строку и могут состоять из любых символов. Секции разделяют файл на части, в которых находятся ключи и соответствующие им значения. В начале файла (перед первой секцией) также могут находится ключи и значения, не принадлежащие ни одной из секций. Ключи и значения также пишутся в одну строку и разделяются друг от друга символом равенства "=". Имя ключа, конечно же, не может содержать символ "=". Значение ключа — строка от первого найденного символа "=" до конца строки.

Имена секций, имена и значения ключей обрезаются, то есть пробельные символы удаляются из начала и конца строк перед их сравнением.

Если каждая секция определяет набор ключей, то каждый ключ, в свою очередь, определяет одно значение. Имена секций и ключей не обязаны быть уникальными, однако если найдётся два ключа (в пределах одной секции) с одинаковым именем, значения будут читаться и записываться в тот из них, что находится ближе к началу файла.

Для всех файловых операций, libini использует libio.

Функции (перебор сущностей)

ini_enum_sections

Перебрать секции, вызывая пользовательскую функцию для каждого из них.

Прототип:

proc ini.enum_sections _f_name, _callback

Аргументы:

_f_name → asciiz
путь к INI файлу
_callback
адрес пользовательской функции: func(f_name, sec_name), где
f_name → asciiz
путь к INI файлу (совпадает с переданным в функцию)
sec_name → asciiz
имя найденной секции

Результат:

eax → dword
-1 (ошибка) / 0

ini_enum_keys

Перебоать ключи в секции, вызывая пользовательскую функцию для каждого из них.

Прототип:

proc ini.enum_keys _f_name, _sec_name, _callback

Аргументы:

_f_name → asciiz
путь к INI файлу
_sec_name → asciiz
имя секции
_callback
адрес пользовательской функции: func(f_name, sec_name, key_name, key_value), где
f_name → asciiz
путь к INI файлу (совпадает с переданным в функцию)
sec_name → asciiz
имя секции (совпадает с переданным в функцию)
key_name → asciiz
имя найденного ключа
key_value → asciiz
значение найденного ключа

Результат:

eax → dword
-1 (ошибка) / 0

Функции (получение и установка значений)

Все функции получения значений безопасны, возвращая переданное значение по умолчанию при любой ошибке.

ini_get_str

Прочитать строку.

Прототип:

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

Аргументы:

_f_name → asciiz
путь к INI файлу
_sec_name → asciiz
имя секции
_key_name → asciiz
имя ключа
_buffer → byte*
буфер для записи полученного значения
_buf_len → dword
размер буфера (максимальное количество байт для чтения)
_def_val → asciiz
возвращаемое значение по умолчанию, если ключ, секция или файл не будут найдены

Результат:

eax → dword
-1 (ошибка) / 0
[_buffer] → asciiz
[_def_val] (ошибка) / найденное значение ключа

ini_set_str

Записать строку.

Прототип:

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

Аргументы:

_f_name → asciiz
путь к INI файлу
_sec_name → asciiz
имя секции
_key_name → asciiz
имя ключа
_buffer → byte*
буфер, содержащий записываемое значение
_buf_len → dword
размер буфера (количество байт для записи)

Результат:

eax → dword
-1 (ошибка) / 0

ini_get_int

Прочитать целое число.

Прототип:

proc ini.get_int _f_name, _sec_name, _key_name, _def_val

Аргументы:

_f_name → asciiz
путь к INI файлу
_sec_name → asciiz
имя секции
_key_name → asciiz
имя ключа
_def_val → dword
возвращаемое значение по умолчанию, если ключ, секция или файл не будут найдены

Результат:

eax → dword
[_def_val] (ошибка) / найденное значение ключа

ini_set_int

Записать целое число.

Прототип:

proc ini.set_int _f_name, _sec_name, _key_name, _val

Аргументы:

_f_name → asciiz
путь к INI файлу
_sec_name → asciiz
имя секции
_key_name → asciiz
имя ключа
_val → dword
значение

Результат:

eax → dword
-1 (ошибка) / 0

ini_get_color

Прочитать цвет.

Прототип:

proc ini.get_color _f_name, _sec_name, _key_name, _def_val

Аргументы:

_f_name → asciiz
путь к INI файлу
_sec_name → asciiz
имя секции
_key_name → asciiz
имя ключа
_def_val → dword
возвращаемое значение по умолчанию, если ключ, секция или файл не будут найдены

Результат:

eax → dword
[_def_val] (ошибка) / найденное значение ключа

ini_set_color

Записать цвет.

Прототип:

proc ini.set_color _f_name, _sec_name, _key_name, _val

Аргументы:

_f_name → asciiz
путь к INI файлу
_sec_name → asciiz
имя секции
_key_name → asciiz
имя ключа
_val → dword
значение

Результат:

eax → dword
-1 (ошибка) / 0

ini_get_shortcut

Прочитать клавишу быстрого доступа.

Строка для ini_get_shortcut - произвольное количество модификаторов Ctrl/Alt/Shift/LCtrl/LAlt/LShift/RCtrl/RAlt/RShift, после которых следует латинская буква/цифра/имя клавиши (имена собственные имеют Home, End, PgUp, PgDn, Ins=Insert, Del=Delete, Tab, Plus, Esc, Enter, Backspace, Space, Left, Right, Up, Down). Строку можно писать с любым регистром символов. Части пишутся либо слитно, либо разделяются плюсом. Например: Ctrl+Alt+Backspace, RCtrl+RShift, ShiftA, f10, shiftalt5

Прототип:

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

Аргументы:

_f_name → asciiz
путь к INI файлу
_sec_name → asciiz
имя секции
_key_name → asciiz
имя ключа
_def_val → dword
возвращаемое значение по умолчанию, если ключ, секция или файл не будут найдены
_modifiers → dword*
адрес переменной типа dword, получающей значение модификаторов для передачи функции 66.4

Результат:

eax → dword
[_def_val] (ошибка) / скан-код клавиши быстрого доступа
[[_modifiers]] → dword
неизменно (ошибка) / состояние модификаторов клавиши быстрого доступа

Примеры использования

Этот пример перебирает секции, а потом в пользовательской функции перебирает ключи каждой найденной секции. Заметьте, что мы используем "invoke", так как вызов функции — косвенный.

  1. ; ...
  2.  
  3.         invoke  ini_enum_sections, filename, ini_section_callback
  4.  
  5. ; ...
  6.  
  7. proc ini_section_callback _filename, _section_name
  8.         ; эта функция вызывается библиотекой для каждой найденной в файле секции
  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.         ; эта функция вызывается библиотекой для каждого найденного в файле ключа каждой секции
  19.  
  20.         ; ...
  21.  
  22.         ret
  23. endp
  24.  
  25. ; ...
  26.  
  27. filename db '/hd0/1/a.ini', 0