chrome.sockets.tcpServer

說明

使用 chrome.sockets.tcpServer API，透過 TCP 連線建立伺服器應用程式。這個 API 會取代先前在 chrome.socket API 中找到的 TCP 功能。

資訊清單

您必須在資訊清單中宣告下列金鑰，才能使用這個 API。

"sockets"

類型

AcceptErrorInfo

屬性

• resultCode

  數字

  基礎網路呼叫傳回的結果代碼。

• socketId

  數字

  伺服器通訊端 ID。

AcceptInfo

屬性

• clientSocketId

  數字

  用戶端通訊端 ID，例如新建立連線的通訊端 ID。這個通訊端 ID 只能與 chrome.sockets.tcp 命名空間中的函式搭配使用。請注意，用戶端通訊端一開始會暫停，且必須由應用程式明確取消暫停，才能開始接收資料。

• socketId

  數字

  伺服器通訊端 ID。

CreateInfo

屬性

• socketId

  數字

  新建立的伺服器通訊端 ID。請注意，透過這個 API 建立的通訊端 ID 與其他 API 建立的通訊端 ID (例如已淘汰的 [socket](../socket/) API) 相容。

SocketInfo

屬性

• localAddress

  string optional

  如果通訊端正在監聽，則會包含其本機 IPv4/6 位址。

• localPort

  編號 選填

  如果通訊端正在監聽，則會包含其本機通訊埠。

• 名稱

  string optional

  與通訊端相關聯的應用程式定義字串。

• 已暫停

  布林值

  此標記用於表示是否要透過 onAccept 事件來調度監聽通訊端的連線要求，還是在監聽佇列待處理工作中排入佇列。詳情請參閱 setPaused。預設值是「false」。

• 永久

  布林值

  此標記用於指出當應用程式的事件頁面卸載時，通訊端是否仍為開啟 (請參閱 SocketProperties.persistent)。預設值是「false」。

• socketId

  數字

  通訊端 ID。

SocketProperties

屬性

• 名稱

  string optional

  與通訊端相關聯的應用程式定義字串。

• 永久

  布林值 選填

  此標記用於指出當應用程式的事件頁面卸載時，通訊端是否仍為開啟 (請參閱管理應用程式生命週期)。預設值為「false」。載入應用程式時，可使用 getSockets 擷取先前透過 Persistent=true 開啟的任何通訊端。

方法

close()

Promise

chrome.sockets.tcpServer.close(
  socketId: number,
  callback?: function,
)

中斷連線並刪除通訊端。每個建立的通訊端都應在使用後關閉。呼叫函式後，通訊端 ID 就會失效。不過，只有在叫用回呼時，通訊端一定才保證關閉。

參數

• socketId

  數字

  通訊端 ID。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 121 以上版本

  Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

create()

Promise

chrome.sockets.tcpServer.create(
  properties?: SocketProperties,
  callback?: function,
)

建立 TCP 伺服器通訊端。

參數

• 資源

  SocketProperties 選用

  通訊端屬性 (選用)。

• 回呼

  函式 選用

  callback 參數如下所示：

  (createInfo: CreateInfo) => void

  • createInfo

    CreateInfo

    建立通訊端的結果。

傳回

• Promise&lt;CreateInfo&gt;

  Chrome 121 以上版本

  Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

disconnect()

Promise

chrome.sockets.tcpServer.disconnect(
  socketId: number,
  callback?: function,
)

中斷監聽通訊端的連線，例如停止接受新連線，並釋放通訊端繫結的位址/通訊埠。通訊端 ID 仍然有效，例如：可以與 listen 搭配使用，接受新通訊埠和位址的連線。

參數

• socketId

  數字

  通訊端 ID。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 121 以上版本

  Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getInfo()

Promise

chrome.sockets.tcpServer.getInfo(
  socketId: number,
  callback?: function,
)

擷取指定通訊端的狀態。

參數

• socketId

  數字

  通訊端 ID。

• 回呼

  函式 選用

  callback 參數如下所示：

  (socketInfo: SocketInfo) => void

  • socketInfo

    SocketInfo

    包含通訊端資訊的物件。

傳回

• Promise&lt;SocketInfo&gt;

  Chrome 121 以上版本

  Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getSockets()

Promise

chrome.sockets.tcpServer.getSockets(
  callback?: function,
)

擷取應用程式擁有且目前開啟的通訊端清單。

參數

• 回呼

  函式 選用

  callback 參數如下所示：

  (socketInfos: SocketInfo[]) => void

  • socketInfos

    SocketInfo[]

    包含通訊端資訊的物件陣列。

傳回

• Promise&lt;SocketInfo[]&gt;

  Chrome 121 以上版本

  Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

listen()

chrome.sockets.tcpServer.listen(
  socketId: number,
  address: string,
  port: number,
  backlog?: number,
  callback: function,
)

監聽指定通訊埠和位址的連線。如果通訊埠/地址正在使用中，回呼會指出失敗。

參數

• socketId

  數字

  通訊端 ID。

• 地址

  字串

  本機電腦的位址。

• 通訊埠

  數字

  本機電腦的通訊埠。設為 0 時，系統會動態選擇免費通訊埠。呼叫 getInfo 即可找到動態分配的通訊埠。

• 待處理工作量

  編號 選填

  通訊端的監聽佇列長度。預設值視作業系統 (SOMAXCONN) 而定，這可確保大多數應用程式合理的佇列長度。

• 回呼

  函式

  callback 參數如下所示：

  (result: number) => void

  • 結果

    數字

    基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。

setPaused()

Promise

chrome.sockets.tcpServer.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
)

啟用或停用監聽通訊端，停止接收新連線。暫停時，監聽通訊端會接受新的連線，直到待處理工作量用盡 (請參閱 listen 函式) 為止，接著會拒絕其他連線要求。只有在通訊端取消暫停時，才會引發 onAccept 事件。

參數

• socketId

  數字

• 已暫停

  布林值

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 121 以上版本

  Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

update()

Promise

chrome.sockets.tcpServer.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
)

更新通訊端屬性。

參數

• socketId

  數字

  通訊端 ID。

• 資源

  SocketProperties

  要更新的屬性。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 121 以上版本

  Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

活動

onAccept

chrome.sockets.tcpServer.onAccept.addListener(
  callback: function,
)

連線至伺服器通訊端時引發的事件。

參數

• 回呼

  函式

  callback 參數如下所示：

  (info: AcceptInfo) => void

  • 資訊

    AcceptInfo

onAcceptError

chrome.sockets.tcpServer.onAcceptError.addListener(
  callback: function,
)

當執行階段在通訊端位址和通訊埠上等待新連線時，發生網路錯誤，就會引發事件。引發這個事件後，通訊端將設為 paused，且在通訊端恢復運作前，通訊端將不會再引發其他 onAccept 事件。

參數

• 回呼

  函式

  callback 參數如下所示：

  (info: AcceptErrorInfo) => void

  • 資訊

    AcceptErrorInfo