chrome.sockets.tcp

說明

使用 chrome.sockets.tcp API 透過 TCP 連線透過網路傳送及接收資料。這個 API 會取代先前在 chrome.socket API 中找到的 TCP 功能。

資訊清單

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

"sockets"

類型

CreateInfo

屬性

  • socketId

    數字

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

DnsQueryType

Chrome 103 以上版本

DNS 解析偏好設定。預設值為 any，且會使用目前的 OS 設定 (可能會傳回 IPv4 或 IPv6)。ipv4 會強制 IPv4，ipv6 則強制使用 IPv6。

列舉

"any"

"ipv4"

"ipv6"

ReceiveErrorInfo

屬性

  • resultCode

    數字

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

  • socketId

    數字

    通訊端 ID。

ReceiveInfo

屬性

  • 資料

    ArrayBuffer

    已收到的資料，大小上限為 bufferSize。

  • socketId

    數字

    通訊端 ID。

SecureOptions

屬性

SendInfo

屬性

  • bytesSent

    編號 選填

    傳送的位元組數 (如果結果 == 0)

  • resultCode

    數字

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

SocketInfo

屬性

  • bufferSize

    編號 選填

    用於接收資料的緩衝區大小。如未明確指定緩衝區空間，則不提供此值。

  • 已連線。

    布林值

    標記，指出通訊端是否已連線至遠端對等點。

  • localAddress

    string optional

    如果基礎通訊端已連線，則會包含其本機 IPv4/6 位址。

  • localPort

    編號 選填

    如果基礎通訊端已連線，則包含其本機通訊埠。

  • 名稱

    string optional

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

  • 已暫停

    布林值

    此標記可註明連線通訊端是否封鎖了其對等點，使其無法傳送更多資料 (請參閱 setPaused)。

  • peerAddress

    string optional

    如果基礎通訊端已連線，會包含對等互連/ IPv4/6 位址。

  • peerPort

    編號 選填

    如果基礎通訊端已連線，則包含對等互連通訊埠。

  • 永久

    布林值

    此標記用於指出當應用程式暫停時，通訊端是否保持開啟 (請參閱 SocketProperties.persistent)。

  • socketId

    數字

    通訊端 ID。

SocketProperties

屬性

  • bufferSize

    編號 選填

    用於接收資料的緩衝區大小。預設值為 4096。

  • 名稱

    string optional

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

  • 永久

    布林值 選填

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

TLSVersionConstraints

屬性

  • 最高

    string optional

  • 分鐘

    string optional

    可接受的傳輸層安全標準 (TLS) 最高和最低版本。支援的值為 tls1.2 或 tls1.3。

    不再支援 tls1 和 tls1.1 值。如果將 min 設為其中一個值，則會自動限制為 tls1.2。如果將 max 設為其中一個值，或任何其他無法辨識的值，系統會直接忽略而不顯示任何通知。

方法

close()

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

關閉通訊端並釋出通訊端繫結的位址/通訊埠。每個建立的通訊端都應在使用後關閉。呼叫函式時，通訊端 ID 不再有效。不過，只有在叫用回呼時，通訊端一定才保證關閉。

參數

  • socketId

    數字

    通訊端 ID。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 121 以上版本

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

connect()

chrome.sockets.tcp.connect(
  socketId: number,
  peerAddress: string,
  peerPort: number,
  dnsQueryType?: DnsQueryType,
  callback: function,
)

將通訊端連線至遠端電腦。成功完成 connect 作業後，系統會從對等點收到資料時，發出 onReceive 事件。如果執行階段在接收封包時發生網路錯誤，就會引發 onReceiveError 事件，這時系統就不會再針對這個通訊端發出 onReceive 事件，直到呼叫 resume 方法為止。

參數

  • socketId

    數字

    通訊端 ID。

  • peerAddress

    字串

    遠端電腦的位址。支援 DNS 名稱、IPv4 和 IPv6 格式。

  • peerPort

    數字

    遠端電腦的通訊埠。

  • dnsQueryType

    DnsQueryType 選用

    Chrome 103 以上版本

    地址解析偏好設定。

  • 回呼

    函式

    callback 參數如下所示： 

    (result: number) => void

    • 結果

      數字

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

create()

Promise 
chrome.sockets.tcp.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.tcp.disconnect(
  socketId: number,
  callback?: function,
)

中斷通訊端。

參數

  • socketId

    數字

    通訊端 ID。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 121 以上版本

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

getInfo()

Promise 
chrome.sockets.tcp.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.tcp.getSockets(
  callback?: function,
)

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

傳回

  • Promise&lt;SocketInfo[]&gt;

    Chrome 121 以上版本

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

secure()

chrome.sockets.tcp.secure(
  socketId: number,
  options?: SecureOptions,
  callback: function,
)

透過已連線的 TCP 用戶端通訊端啟動 TLS 用戶端連線。

參數

  • socketId

    數字

    要使用的現有連線通訊端。

  • 選項

    SecureOptions 選用

    TLS 連線的限制和參數。

  • 回呼

    函式

    callback 參數如下所示： 

    (result: number) => void

    • 結果

      數字

send()

chrome.sockets.tcp.send(
  socketId: number,
  data: ArrayBuffer,
  callback: function,
)

這個外掛程式能在指定的 TCP 通訊端上傳送資料。

參數

  • socketId

    數字

    通訊端 ID。

  • 資料

    ArrayBuffer

    要傳送的資料。

  • 回呼

    函式

    callback 參數如下所示： 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      send 方法的結果。

setKeepAlive()

chrome.sockets.tcp.setKeepAlive(
  socketId: number,
  enable: boolean,
  delay?: number,
  callback: function,
)

啟用或停用 TCP 連線的保持運作功能。

參數

  • socketId

    數字

    通訊端 ID。

  • 啟用

    布林值

    如為 true，請啟用保持運作功能。

  • delay

    編號 選填

    設定最近一次接收的資料封包和第一次保持運作探測之間的延遲時間 (以秒為單位)。預設值為 0。

  • 回呼

    函式

    callback 參數如下所示： 

    (result: number) => void

    • 結果

      數字

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

setNoDelay()

chrome.sockets.tcp.setNoDelay(
  socketId: number,
  noDelay: boolean,
  callback: function,
)

設定或清除 TCP 連線的 TCP_NODELAY。設定 TCP_NODELAY 時，系統將停用 Nagle 的演算法。

參數

  • socketId

    數字

    通訊端 ID。

  • noDelay

    布林值

    如果設為 true，系統會停用 Nagle 的演算法。

  • 回呼

    函式

    callback 參數如下所示： 

    (result: number) => void

    • 結果

      數字

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

setPaused()

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

啟用或停用應用程式接收來自對等點的訊息。預設值是「false」。一般來說，應用程式會透過暫停通訊端，來調節其對等點傳送的資料。通訊端暫停時，系統不會引發 onReceive 事件。通訊端連線且未暫停時，接收訊息時會再次引發 onReceive 事件。

參數

  • socketId

    數字

  • 已暫停

    布林值

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 121 以上版本

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

update()

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

更新通訊端屬性。

參數

  • socketId

    數字

    通訊端 ID。

  • 要更新的屬性。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 121 以上版本

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

活動

onReceive

chrome.sockets.tcp.onReceive.addListener(
  callback: function,
)

系統收到特定通訊端的資料時引發的事件。

參數

onReceiveError

chrome.sockets.tcp.onReceiveError.addListener(
  callback: function,
)

當執行階段等待通訊端位址和通訊埠中的資料時，發生網路錯誤，就會引發事件。引發此事件後，通訊端會設為 paused，不再針對此通訊端引發其他 onReceive 事件。

參數