انتقل إلى المحتوى الرئيسي

C API Reference

Each component's contract is its include/ directory; everything else is private. This page indexes the public functions; semantics live in the linked chapters.

event_bus (event_bus.h)​

event_bus_init, event_bus_deinit, event_bus_subscribe(type, cb, user_data), event_bus_unsubscribe(type, cb), event_bus_publish(type, data, len) (synchronous), event_bus_publish_async(type, data, len) (copied payload), event_bus_get_event_name(type), event_bus_get_dropped_count(). Chapter.

audio_player (audio_player.h, audio_output.h)​

Playback: audio_player_init/deinit, audio_player_play_file(path), audio_player_play_file_at(path, start_ms), audio_player_play_stream(url), audio_player_pause/resume/stop, audio_player_seek(ms). Volume: audio_player_set_volume(0..100), audio_player_get_volume. State: audio_player_get_state, audio_player_is_playing, audio_player_get_track(buf, size, *is_stream), audio_player_get_info, audio_player_get_underrun_count, audio_player_register_callback. Resume: audio_player_has_resume_state, audio_player_get_resume_info, audio_player_resume_saved, audio_player_clear_resume. I2S layer: i2s_output_init(bclk, lrc, din, sd_pin), i2s_write_samples(src, size, *written, timeout_ms), i2s_set_sample_rate(rate), i2s_output_deinit. Chapters.

playback_queue (playback_queue.h)​

playback_queue_init, playback_queue_set_mode(mode), playback_queue_set_hifz(cfg), playback_queue_get_state(*out), playback_queue_next(), playback_queue_prev(), playback_queue_play_juz(juz, reciter, path, pos), playback_queue_play_hizb(hizb, reciter, path, pos).

ayah_timings (ayah_timings.h)​

ayah_timings_init, ayah_timings_get() (returns ayah_progress_t), ayah_timings_find_start(reciter, surah, ayah, *pos), ayah_timings_find_start_ex(reciter, surah, ayah, is_repeat, *pos). Parses binary .atb archives and files with JSON fallback and 3-surah LRU caching.

stream_client (http_stream.h)​

stream_client_init/deinit, stream_client_validate_url(url), stream_client_start(url), stream_client_stop, stream_client_read(buf, max, timeout_ms, *out_len), stream_client_is_connected, stream_client_is_active, stream_client_get_content_type. Chapter.

display_driver (display_ui.h, lcd_st7735s.h)​

Lifecycle: display_init(config), display_backlight_init, ui_manager_init, ui_display_task_start. Screens: ui_show_splash, ui_splash_report_failure, ui_show_idle, ui_update_playback(info), ui_set_stream_title(title), ui_show_browse_mode, ui_show_volume_mode, ui_show_wifi_status, ui_show_nfc_detected, ui_show_ota_progress(percent), ui_show_error(msg), ui_update_status_bar. Support: display_set_contrast(0..255), display_backlight(on), ui_display_notify_activity, ui_browse_mode_active, ui_set_time_format_24h(use_24h), ui_tick_idle_clock, ui_screenshot_bmp(write_cb, ctx), lcd_st7735s_test_pattern. Chapters.

sd_manager (sd_manager.h)​

sd_manager_init/deinit, sd_manager_is_mounted, sd_manager_get_capacity, sd_manager_scan_files, sd_manager_get_stats, sd_manager_get_reciter_count, sd_manager_get_reciter(index, *out) (copy-out), sd_manager_get_reciter_by_name, sd_manager_get_surah_path(reciter, surah, buf, size), sd_manager_surah_exists. Chapter.

state_manager​

nvs_manager.h: init/deinit, nvs_save/load_volume, nvs_save/load/clear_playback_state, nvs_save/load/delete_radio_preset, nvs_get_radio_preset_count, nvs_save/load_display_settings, nvs_save/load/has/clear_wifi_credentials, nvs_save/load_card_removal_policy, nvs_save/load_auto_resume, nvs_save/load_time_format_24h, nvs_save/load_sleep_settings, nvs_reset_all_settings, nvs_manager_get_stats. Chapter. favorites.h: favorites_init/add/remove/toggle/is_favorite/get/get_all/count/increment_play_count/save/load. scheduler.h: scheduler_init/start/stop/add/remove/update/get/get_all/count/set_enabled/save/load. time_sync.h: time_sync_init, time_sync_set_timezone(tz), time_sync_get_timezone, time_sync_is_synced, and the source trio time_sync_get_source, time_sync_source_name, time_sync_mark_source(source) over time_source_t (none / rtc / sntp / manual). boot_report.h: boot_report_add(component, err), boot_report_count, boot_report_get(index). Chapter.

power_manager (battery_monitor.h)​

battery_monitor_init/deinit, battery_get_state(*out) (voltage, percent, charging, sense_valid), and the pure logic pair battery_voltage_to_percentage(volts), battery_update_low_streak(volts, charging, sense_valid, streak), battery_should_shutdown(streak). Chapter.

rfid_manager (rfid_manager.h, card_database.h)​

rfid_manager_init, rfid_manager_start_scanning/stop_scanning, rfid_set_mode, rfid_register_card, rfid_get_card. Database: card_database_init/deinit/register/update/get/delete/exists/count/list/iterate/clear. Chapter.

input_handler (rotary_encoder.h, touch_sensor.h, input_events.h)​

rotary_encoder_init, touch_sensor_init; both report through the event bus rather than exposing polling APIs. Chapter.

web_server (https_server.h, rest_api.h, websocket.h, api_auth.h, rate_limit.h)​

start_webserver wires everything; api_auth_require(req) and rate_limit_allow(req, class, n, window_ms) are the two calls every handler makes; individual REST registration functions exist per domain file. Chapters.