[擴充功能] IPTV 大數據非同步過濾器 (com.luckyh9h.iptvapi)
本組件是專為 MIT App Inventor 2、Kodular 與 Niotron 設計的高效能後端資料處理擴充功能。它跳脫了傳統 AI2 前端逐行讀取大量資料會造成畫面卡頓的缺點，直接與全球最大的開源電視直播資料庫 (iptv-org) 的 JSON 接口對接，並全面使用背景子執行緒 (FilterStreamsTask) 進行非同步網路下載與核心數據清洗。
主程式內建 「安全防禦閘門（Null Safety Guard）」：當使用者在積木中將國家代碼留空或未填寫時，Java 核心會自動攔截空指標，強制以台灣 "tw" 作為安全預設值，徹底免除 App Runtime 閃退的系統原罪。過濾完成後，會自動在記憶體同步產出「頻道名稱清單」與「影音網址清單」供前端元件調用。
- 組件包名（Package Name）：
com.luckyh9h.iptvapi - 內部類別名（Class Name）：
IptvApi - 元件版本：
1.0 - 組件分類： Extension（擴充功能）
- 非可視組件： 是（100% 邏輯運算組件，拉入任何 Screen 均不佔用畫面佈局）
- 最低支援系統： Android API 19+ (KitKat) 以上
無。（完全改由後端非同步線程與網路協議自動運算）。
在背景啟動獨立的非同步工人和執行緒（AsyncTask），向全球資料庫抓取最新串流總表，並根據選定的國碼與分類篩選出有價值的電視台。
- 參數：
selectedCountryCode(String) - 國家與地區代碼（如台灣填tw、日本填jp、美國填us）。【內建安全防禦】 如果文字積木留空、未接或傳入 null，組件會自動強制將預設值設定為台灣"tw"進行抓取，絕不閃退。selectedCategory(String) - 節目內容分類過濾（如news新聞、movies電影、sports體育）。若想獲取該地區所有不分類的完整電視台，直接給予一個空字串""積木即可。
當背景執行緒正式向網路伺服器發動連線握手、並開始串流下載 JSON 位元組的瞬間觸發。非常適合用來開啟畫面上的「讀取進度條（Progress Spinner）」提示使用者正在載入中。
當背景執行緒在毫秒內將數萬筆的龐大資料庫下載、拆解、清洗過濾完畢時觸發。會直接以「雙軌陣列」形式將乾淨合規的清單打包丟回 AI2 積木中。
- 參數：
channelNames(List) - 篩選成功的所有電視台展示名稱清單（用於灌進 ListView 供使用者觀看）。channelUrls(List) - 與名稱順序完全一一對應的真實影音串流網址清單（.m3u8或.ts，用於點選後直接丟給播放器）。
當遇到手機斷網、GitHub 伺服器逾時、或是不可預知的 JSON 解析結構異常時觸發。
- 參數：
errorMessage(String) - 回報底層最真實的網路中斷原因日誌。
// 1. 當點擊搜尋按鈕時，發動非同步背景清洗
當 btn_search.Click 執行時：
呼交 IptvApi1.FilterStreams(
selectedCountryCode: txt_country_input.Text, // 讀取輸入框代碼
selectedCategory: "" // 不限分類，抓取全部
)
// 2. 搜尋啟動時，轉動進度輪並淨空舊選單
當 IptvApi1.OnFilterStarted 執行時：
設定 progress_spinner.Visible 為 true
設定 list_channels.Elements 為 (建立空清單)
// 3. 背景大數據清洗完畢，完美灌入清單
當 IptvApi1.OnFilterCompleted (channelNames, channelUrls) 執行時：
設定 progress_spinner.Visible 為 false
// 關鍵：將網址清單保存在全域變數裡待命
設定 global 網址快取暫存區 為 (取得 channelUrls)
// 將乾淨的電視名稱展示在選台器畫面上
設定 list_channels.Elements 為 (取得 channelNames)
// 4. 使用者選好電視台，瞬間連動您的萬能 Iptv.aix 智慧雙引擎播放器開播！
當 list_channels.AfterPicking 執行時：
設定 選中行數 為 (取得 list_channels.SelectionIndex)
設定 最終影音連結 為 (選擇清單項目 清單: global 網址快取暫存區, 索引值: 選中行數)
// 呼叫播放積木，瞬間開播！
呼叫 Iptv1.PlayStream(streamUrl: 最終影音連結)
// 5. 斷網防禦處理
當 IptvApi1.OnFilterFailed (errorMessage) 執行時：
設定 progress_spinner.Visible 為 false
呼叫 通知元件1.顯示警告通知(訊息: (合併文字 "網路連線失敗: " (取得 errorMessage)))
A robust, high-performance back-end data processor extension designed for MIT App Inventor 2, Kodular, and Niotron. It interacts directly with the global open-source live-television database (iptv-org), downloading and parsing massive streams.json datasets asynchronously via background threads (FilterStreamsTask).
It features an intelligent zero-field null safety guard that automatically intercepts empty or null parameters from AI2 text blocks to prevent application crashes, instantly returning separate parallel lists of clean channel names and play URLs.
- Package Name:
com.luckyh9h.iptvapi - Class Name:
IptvApi - Version:
1.0 - Category: Extension
- Non-visible Component: Yes (100% safe from UI layout compiler overheads)
- Minimum Android API: 19+ (KitKat)
None. (Operates purely on asynchronous network and memory logic via blocks).
Triggers a background worker thread (AsyncTask) to download the global stream database and filter live television feeds based on country codes and optional content categories.
- Parameters:
selectedCountryCode(String) - The ISO 3166-1 alpha-2 country code (e.g.,tw,us,jp). [Null Safety Guard Included] If left empty or null, it automatically defaults to"tw".selectedCategory(String) - Optional content filter category (e.g.,news,movies,sports). Leave completely empty""to fetch all available genres for that region without restrictions.
Triggered the exact millisecond the background task establishes a handshake with the remote database server and begins streaming raw JSON bytes. Ideal for displaying loading spinners or progress bar UI elements to the user.
Triggered when the background thread successfully finishes downloading, parsing, and filtering the large dataset. Returns clean parallel lists ready to be populated inside user interfaces like ListView.
- Parameters:
channelNames(List) - A list containing the clean display titles of the filtered television channels.channelUrls(List) - A list containing the verified playback stream links (.m3u8or.ts) corresponding to each filtered channel index.
Triggered if a network anomaly, server timeout (e.g., GitHub Pages downtime), or local parsing error occurs during data extraction.
- Parameters:
errorMessage(String) - The technical reason or exception error logs explaining the connection breakdown.
// 1. Trigger the background search when user inputs a country code
When btn_search.Click do:
Call IptvApi1.FilterStreams(
selectedCountryCode: txt_country_input.Text,
selectedCategory: "" // Empty string to fetch all categories
)
// 2. Display a loading wheel when parsing starts
When IptvApi1.OnFilterStarted do:
Set progress_spinner.Visible to true
Set list_channels.Elements to (create empty list) // Clear previous entries
// 3. Populate ListView when filtering finishes safely
When IptvApi1.OnFilterCompleted(channelNames, channelUrls) do:
Set progress_spinner.Visible to false
// Cache the URLs into an App variable for indexing
Set global cached_urls to (get channelUrls)
// Populate titles onto the UI list selection
Set list_channels.Elements to (get channelNames)
// 4. Feed selected link into your custom Iptv.aix Player Component
When list_channels.AfterPicking do:
Set target_index to (get list_channels.SelectionIndex)
Set play_link to (select list item from list: global cached_urls, index: target_index)
Call Iptv1.PlayStream(streamUrl: play_link)
// 5. Handle Network Outages Gracefully
When IptvApi1.OnFilterFailed(errorMessage) do:
Set progress_spinner.Visible to false
Call Notifier1.ShowAlert(notice: (join "Network Error: " (get errorMessage)))