設備SDK封裝應統一呼叫約定,同時保留設備之間真實存在的差異。介面名稱一致,不能取代參數語意、緩衝所有權和錯誤狀態的定義。以下為適配層設計方法,不代表任意設備已完成統一存取。

參數模型先定義語意

欄位 應表達的訊息 需要避免的問題
參數標識 業務名稱、設備對應及適用模式 同名參數在不同裝置上意義不同
類型和單位 整數、浮點、枚舉、布林以及明確單位 直接複製數值造成單位錯誤
訪問能力 唯讀、可寫入、動態範圍與依賴狀態 採集中寫入不允許修改的參數
枚舉與預設值 實際支援項和讀取結果 把未支持項預設為成功
生效條件 是否停採、重啟或重連後生效 設定回傳後立即假定影像已採用新值

不要只做字段重命名。對於不支援的功能,應返回可辨識狀態;對於可轉換的單位,應規定換算和捨去。設定參數後的回讀、設備狀態和影像變化,並依目標SDK能力驗證。

幀資料的生命週期

介面文件應寫明緩衝由裝置SDK、適配層或呼叫方分配,呼叫方能讀取到何時,何時必須釋放或歸還,是否允許跨執行緒及是否發生記憶體複製。影像寬高、格式、行跨度和有效長度共同描述數據,不能假定每行緊密排列。

非同步回調中傳回的指針,不能在未確認生命週期時交給長期運作的下游任務。停止採集、斷連和銷毀設備時,還需定義未處理訊框、排隊回呼與資源回收的順序。

狀態與錯誤來源

建議區分未連接、已連接、已配置、採集中、停止中和故障等狀態,並記錄允許的呼叫與轉換條件。超時、設備斷連、參數不支援、緩衝不足和解析失敗應分別表達。統一錯誤碼的同時保留原廠錯誤碼和上下文,以便於定位問題。

驗證介面而不只驗證範例

依特定裝置與版本檢查參數邊界、重複啟動停止、無幀逾時、緩衝歸還、並發呼叫和斷連恢復。對無法注入或設備不支援的故障,記錄未驗證原因。交付介面說明、錯誤碼表、建置與範例及約定的測試記錄。

相關服務:視覺硬體SDK、嵌入式影像擷取。