Biblioteka korzysta z parsera pliku napisanego we fleksie i udostępnia proste API do pobierania wartości parametrów. Dane wewnętrzne biblioteki przechowywane są w statycznych, globalnych zmiennych. Nie zaleca się korzystania z biblioteki inaczej niż przez opisane API. Korzystanie z biblioteki wymaga włączenia do programu pliku nagłówkowego libpar.h.
Przed użyciem jakiejkolwiek funkcji z biblioteki konieczna jest jej inicjalizacja. Dokonuje się tego przez użycie jednej z dwóch funkcji:
libpar_init_with_filename(char *filename, int exit_on_error) - inicjalizuje bibliotekę i wczytuje plik konfiguracyjny o podanej nazwie. Jeżeli wystąpił błąd podczas odczytu pliku i wartość zmiennej exit_on_error jest różna od 0, wywoływana jest funkcja exit(1) - program kończy działanie. Jeżeli zamiast nazwy pliku podamy NULL, wczytany zostanie plik konfiguracyjny z domyślnej lokalizacji - pod Linuksem jest to /etc/szarp/szarp.cfg. Pod Windows nie ma domyślnej lokalizacji i funkcja nie załaduje żadnego pliku (wystąpi błąd).
libpar_init() - równoważne libpar_init_with_filename(NULL, 1).
Aby możliwe było korzystanie w pliku konfiguracyjnym ze zmiennych zadeklarowanych w linii komend uruchamianego programu (parametry -Dnazwa=wartość - zobacz Sekcja 4.1.6), należy jeszcze wywołać funkcję libpar_read_cmdline(int *argc, char *argv[]) . Argumentami funkcji są wskaźniki do standardowych argumentów funkcji main(). Wartość tych argumentów jest modyfikowana - argc jest zmniejszany, a argv modyfikowany tak, że w efekcie argumenty obsługiwane przez bibliotekę są w dalszej części programu niewidoczne. Pozwala to na nieprzejmowanie się programu obsługą opcji '-D'.
Funkcja libpar_reinit_with_filename(char *filename, int exit_on_error) ponownie inicjalizuje bibliotekę plikiem konfiguracyjnym o podanej nazwie. Jeżeli zamiast nazwy zostanie podany NULL, biblioteka użyje pliku /etc/szarp/szarp.cfg (jest to dozwolone tylko w Linuksie). Parametry z pliku, którym poprzednio zainicjalizowano bibliotekę, przestają być dostępne. Jeżeli parametr exit_on_error ma wartość różną od 0 i podczas odczytu pliku wystąpi błąd, biblioteka wywoła funkcję exit(1). Wywołania funkcji libpar_reinit() jest równoważne libpar_reinit_with_filename(NULL,1).
Ostatnim etapem korzystania z biblioteki powinno być wywołanie funkcji libpar_done(). Zwalnia ona zajmowaną przez bibliotekę pamięć i powoduje, że dostęp do wartości parametrów staje się niemożliwy.
| Poprzedni | Spis treści | Następny |
| Biblioteka libpar | Początek rozdziału | Odczytywanie wartości parametrów |