TCB_IMGPSScanX OCX 通訊介面與溝通機制分析

本表條列了 Delphi 宿主環境(ActiveX[ocx]) 與 TCB_IMGPSScanX 元件之間主要的溝通管道、對應方法及其在系統架構中的作用。

壹、 指令與資料交換介面表

貳、 溝通機制細部說明

1. 參數化配置 (Config-by-String)

本專案大量使用 SetSQLData 這種「一條字串走天下」的設計，這在早期 ActiveX 開發中非常流行，優點是規避了 COM 介面頻繁修改 _TLB.pas 的麻煩。您在轉換 TypeScript UI 時，可以將其封裝為一個 JSON 物件，最後再組合成字串傳給這個方法。

2. 狀態回饋 (The Inf1~7 Pattern)

由於 ActiveX 事件 (Events) 的回傳有時在網頁端不夠穩定，開發者選擇了 GetSetInf 系列。宿主程式通常會在執行完某個長耗時動作（如 upFile）後，連續呼叫 GetSetInf3 (成功標記) 與 GetSetInf6 (錯誤訊息) 來決定下一步 UI 流程。

3. 雙向同步 (Bidirectional Sync)

• 同步設定：宿主透過 GetDefScanIni 觸發，OCX 內部完成硬體設定。
• 同步資料：宿主透過 dnFile_Get 觸發，OCX 完成本機與伺服器的檔案 IO 同步。

參、描服務抽象層實作

採用 「抽象介面層 (Abstraction Layer)」 配合 「適配器模式 (Adapter Pattern)」，處理遺留系統（Legacy System）過渡到現代化架構

/**
 * 掃描服務資料模型定義
 * 將原本 OCX 雜亂的字串溝通 (SetSQLData) 結構化
 */
export interface ScanConfig {
  serverIp: string;
  caseId: string;
  dpi: number;
  isColor: boolean;
  isDuplex: boolean;
  // ... 其他來自 GetDefScanIni 的參數
}

export interface ScanStatus {
  caseId: string;
  totalPageCount: number;
  isUploadSuccess: boolean;
  lastBarcode: string;
  errorMessage: string;
}

/**
 * 掃描服務抽象介面 (IScanService)
 * UI 層僅與此介面溝通，不直接操作底層實作
 */
export interface IScanService {
  initialize(config: ScanConfig): Promise<void>;
  startScan(): Promise<boolean>;
  uploadFiles(): Promise<boolean>;
  getStatus(): Promise<ScanStatus>;
  getVersion(): Promise<string>;
  downloadResource(action: string, fileName: string): Promise<void>;
}

/**
 * 實作 A: ActiveX 適配器 (Legacy Adapter)
 * 用於目前環境：UI (TS) -> Delphi Browser -> ActiveX (OCX)
 */
export class ActiveXScanAdapter implements IScanService {
  private ocx: any;

  constructor() {
    // 透過 window.external 或 Delphi Bridge 取得 OCX 實例
    this.ocx = (window as any).OCX_INSTANCE;
  }

  async initialize(config: ScanConfig): Promise<void> {
    // 將 JSON 轉回 OCX 慣用的管道分隔字串 (SetSQLData 邏輯)
    const sqlDataStr = `${config.serverIp}|${config.caseId}|${config.dpi}|${config.isColor ? 'C' : 'G'}`;
    this.ocx.SetSQLData(sqlDataStr);
  }

  async startScan(): Promise<boolean> {
    this.ocx.StatrTwainScan();
    return true; // 實際狀態需透過 GetSetInf 輪詢
  }

  async getStatus(): Promise<ScanStatus> {
    return {
      caseId: this.ocx.GetSetInf1(),
      totalPageCount: parseInt(this.ocx.GetSetInf2()),
      isUploadSuccess: this.ocx.GetSetInf3() === 'Y',
      lastBarcode: this.ocx.GetSetInf5(),
      errorMessage: this.ocx.GetSetInf6()
    };
  }

  async uploadFiles(): Promise<boolean> {
    this.ocx.upFile();
    return true;
  }

  async getVersion(): Promise<string> {
    return this.ocx.GetCurrentVersionNo();
  }

  async downloadResource(action: string, fileName: string): Promise<void> {
    this.ocx.dnFile_Get(action, fileName);
  }
}

/**
 * 實作 B: Backend Server 適配器 (Future Adapter)
 * 用於未來環境：UI (TS) -> REST API / WebSocket -> Rust/Go Backend
 */
export class BackendServerAdapter implements IScanService {
  private apiUrl = "http://localhost:8080/api/scanner";

  async initialize(config: ScanConfig): Promise<void> {
    await fetch(`${this.apiUrl}/config`, {
      method: 'POST',
      body: JSON.stringify(config)
    });
  }

  async startScan(): Promise<boolean> {
    const res = await fetch(`${this.apiUrl}/scan`, { method: 'POST' });
    return res.ok;
  }

  async getStatus(): Promise<ScanStatus> {
    const res = await fetch(`${this.apiUrl}/status`);
    return await res.json();
  }

  async uploadFiles(): Promise<boolean> {
    const res = await fetch(`${this.apiUrl}/upload`, { method: 'POST' });
    return res.ok;
  }

  async getVersion(): Promise<string> {
    const res = await fetch(`${this.apiUrl}/version`);
    const data = await res.json();
    return data.version;
  }

  async downloadResource(action: string, fileName: string): Promise<void> {
    // 未來可能直接由後端處理，前端僅發送同步指令
    await fetch(`${this.apiUrl}/sync?action=${action}&file=${fileName}`);
  }
}

/**
 * 服務工廠 (Scanner Factory)
 * 根據環境自動切換實作
 */
export class ScannerFactory {
  static getService(): IScanService {
    if ((window as any).OCX_INSTANCE) {
      console.log("偵測到 ActiveX 環境，啟用 ActiveX 適配器");
      return new ActiveXScanAdapter();
    } else {
      console.log("現代瀏覽器環境，啟用後端 API 適配器");
      return new BackendServerAdapter();
    }
  }
}

1. 介面標準化（JSON 化）

原先 OCX 使用 SetSQLData 的「長字串」溝通是非常脆弱的（一項參數順序錯了就全毀）。在 TypeScript 抽象層中，請務必將其轉換為 強型別的 JSON 物件（如 ScanConfig 介面）。這樣你的 UI 邏輯在處理設定時會非常直覺。

2. 非同步處理（Promise/Async）

ActiveX 的方法通常是同步阻塞的，而後端 API 是非同步的。

• 建議：在抽象介面（IScanService）中，所有方法都回傳 Promise。
• 原因：這樣當你未來切換到後端伺服器（fetch API）時，UI 的調用邏輯（await service.startScan()）不需要做任何修改。

3. 實作「心跳」或「狀態輪詢」

原本 GetSetInf1~7 主要是靠宿主程式主動去「問」OCX。

• 抽象層建議：在 IScanService 中實作一個 subscribeStatus(callback) 的觀察者模式。
• ActiveX 模式下：在適配器內部啟動一個 setInterval 去輪詢 GetSetInf。
• 未來後端模式下：適配器改用 WebSocket 接收後端主動推播的掃描事件。
• UI 層感受：UI 只需要處理 onStatusUpdate 事件，根本不用管底層是用輪詢還是 WebSocket。

4. 資源路徑的轉義（The Bridge Proxy）

這是我之前提到的關鍵：由於 iframe 裡的 TypeScript 無法存取 C:\Temp，但 ActiveX 依舊會把檔案掃到那裡。

• 策略：你的 Delphi Browser 需要實作一個簡單的本地 Proxy。
• 實作：當 TypeScript 需要顯示圖檔時，它請求 http://local.bridge/view/001.tif，Delphi Browser 攔截此請求並從實體路徑讀取檔案回傳。
• 好處：未來改為 Backend Server 時，Server 也可以提供同樣的 URL 格式，UI 完全無縫接軌。

肆、 Delphi 與 JavaScript 通訊橋樑 (Bridge) 實作說明

當您在 Delphi 宿主程式中使用內嵌瀏覽器時，JavaScript 取得 OCX_INSTANCE 的方式取決於底層的瀏覽器引擎：

1. 舊版 IE 核心 (TWebBrowser / window.external)

這是最傳統的方式，Delphi 會透過實作 IDocHostUIHandler 介面，將一個自訂的 IDispatch 物件掛載到 window.external 上。

• Delphi 端：將 TCB_IMGPSScanX 實例或其包裝類別指派給瀏覽器的 External 屬性。
• JS 端：直接使用 window.external.StatrTwainScan() 呼叫。

2. 新版 Edge 核心 (TEdgeBrowser / WebView2 Host Objects)

這是現代化的做法。Delphi 透過 WebView2 的 API 將物件直接「注入」到 JS 的命名空間中。

• Delphi 端執行：

  // 將 OCX 物件以 'OCX_INSTANCE' 名稱注入
  EdgeBrowser.AddHostObjectToScript('OCX_INSTANCE', MyOcxWrapperObject);
  

• JS 端取得： WebView2 會將物件放置在 window.chrome.webview.hostObjects 底下。

  const ocx = window.chrome.webview.hostObjects.OCX_INSTANCE;
  

3. 為什麼需要 Wrapper (包裝類別)？

通常我們**不建議**直接將 TCB_IMGPSScanX 注入，原因如下：

1. 安全性：直接暴露 COM 元件可能會有安全漏洞。
2. 相容性：OCX 的某些方法回傳型別（如 Delphi 的自訂 Enum）JavaScript 無法識別。
3. 執行緒優化：Delphi 可以在 Wrapper 中使用 TThread.Queue 確保掃描指令在正確的執行緒執行，避免瀏覽器 UI 凍結。

4. 溝通路徑總結

1. Delphi 宿主程式 啟動並實體化 OCX 控制項。
2. Delphi 宿主程式 建立 Browser 物件 並載入 TypeScript UI (HTML)。
3. Delphi 宿主程式 呼叫瀏覽器 API（如 AddHostObjectToScript），將 OCX 的操作介面「注入」到該網頁的 window 物件中。
4. TypeScript 透過抽象層 (Adapter) 取得該物件，實現「網頁點按鈕，掃描機開動」的效果。