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 (例如已淘汰的 [socket](../socket/) API) 建立的通訊端 ID 不相容。

SocketInfo

屬性

  • localAddress

    字串 選用

    如果通訊端正在監聽，請加入其本機 IPv4/6 位址。

  • localPort

    數字 選填

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

  • 名稱

    字串 選用

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

  • 已暫停

    boolean

    此標記可註明監聽通訊端的連線要求是否透過 onAccept 事件分派，還是排入監聽佇列待處理工作中。查看《setPaused》。預設值為「false」。

  • 永久

    boolean

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

  • socketId

    號碼

    通訊端 ID。

SocketProperties

屬性

  • 名稱

    字串 選用

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

  • 永久

    布林值 (選用)

    此標記可表示當應用程式的事件頁面卸載時，通訊端是否保持開啟狀態 (請參閱「管理應用程式生命週期」)。預設值為「false」。應用程式載入時，可使用 getSockets 擷取先前以 persistent=true 開啟的任何通訊端。

方法

close()

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

中斷連線並銷毀通訊端。使用之後，建立的每個通訊端都應該關閉。呼叫函式後，通訊端 ID 就會立即失效。但是，通訊端保證只有在叫用回呼時才會關閉。

參數

  • socketId

    號碼

    通訊端 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<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<CreateInfo>

    Chrome 121 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

disconnect()

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

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

參數

  • socketId

    號碼

    通訊端 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<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<SocketInfo>

    Chrome 121 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getSockets()

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

擷取應用程式擁有的通訊端清單。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    (socketInfos: SocketInfo[])=>void

    • socketInfos

      SocketInfo[]

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

傳回

  • Promise<SocketInfo[]>

    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

    號碼

  • 已暫停

    boolean

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 121 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

update()

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

更新通訊端屬性。

參數

  • socketId

    號碼

    通訊端 ID。

  • 要更新的屬性。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 121 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

活動

onAccept

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

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

參數

onAcceptError

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

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

參數