設備SDK封裝應統一呼叫約定,同時保留設備之間真實存在的差異。介面名稱一致,不能取代參數語意、緩衝所有權和錯誤狀態的定義。以下為適配層設計方法,不代表任意設備已完成統一存取。
參數模型先定義語意
| 欄位 | 應表達的訊息 | 需要避免的問題 |
|---|---|---|
| 參數標識 | 業務名稱、設備對應及適用模式 | 同名參數在不同裝置上意義不同 |
| 類型和單位 | 整數、浮點、枚舉、布林以及明確單位 | 直接複製數值造成單位錯誤 |
| 訪問能力 | 唯讀、可寫入、動態範圍與依賴狀態 | 採集中寫入不允許修改的參數 |
| 枚舉與預設值 | 實際支援項和讀取結果 | 把未支持項預設為成功 |
| 生效條件 | 是否停採、重啟或重連後生效 | 設定回傳後立即假定影像已採用新值 |
不要只做字段重命名。對於不支援的功能,應返回可辨識狀態;對於可轉換的單位,應規定換算和捨去。設定參數後的回讀、設備狀態和影像變化,並依目標SDK能力驗證。
幀資料的生命週期
介面文件應寫明緩衝由裝置SDK、適配層或呼叫方分配,呼叫方能讀取到何時,何時必須釋放或歸還,是否允許跨執行緒及是否發生記憶體複製。影像寬高、格式、行跨度和有效長度共同描述數據,不能假定每行緊密排列。
非同步回調中傳回的指針,不能在未確認生命週期時交給長期運作的下游任務。停止採集、斷連和銷毀設備時,還需定義未處理訊框、排隊回呼與資源回收的順序。
狀態與錯誤來源
建議區分未連接、已連接、已配置、採集中、停止中和故障等狀態,並記錄允許的呼叫與轉換條件。超時、設備斷連、參數不支援、緩衝不足和解析失敗應分別表達。統一錯誤碼的同時保留原廠錯誤碼和上下文,以便於定位問題。
驗證介面而不只驗證範例
依特定裝置與版本檢查參數邊界、重複啟動停止、無幀逾時、緩衝歸還、並發呼叫和斷連恢復。對無法注入或設備不支援的故障,記錄未驗證原因。交付介面說明、錯誤碼表、建置與範例及約定的測試記錄。