chrome.socket

說明

使用 chrome.socket API，透過 TCP 和 UDP 連線在網路上傳送及接收資料。注意：自 Chrome 33 起，這個 API 已淘汰，改用 sockets.udp、sockets.tcp 和 sockets.tcpServer API。

權限

socket

類型

AcceptInfo

屬性

• resultCode

  數字

• socketId

  數字 選填

  已接受通訊端的 ID。

CreateInfo

屬性

• socketId

  數字

  新建立通訊端的 ID。

CreateOptions

NetworkInterface

屬性

• 地址

  字串

  可用的 IPv4/6 位址。

• 名稱

  字串

  轉接程式的基礎名稱。在 *nix 上，這通常會是「eth0」、「lo」等。

• prefixLength

  數字

  前置碼長度

ReadInfo

屬性

• 資料

  ArrayBuffer

• resultCode

  數字

  基礎 read() 呼叫傳回的 resultCode。

RecvFromInfo

屬性

• 地址

  字串

  遠端機器的位址。

• 資料

  ArrayBuffer

• 通訊埠

  數字

• resultCode

  數字

  基礎 recvfrom() 呼叫傳回的 resultCode。

SecureOptions

屬性

• tlsVersion

  TLSVersionConstraints 選用

SocketInfo

屬性

• 已連線。

  布林值

  基礎通訊端是否已連線。

  對於 tcp 通訊端，即使遠端對等互連已中斷連線，這項設定仍會保持 true。讀取或寫入通訊端可能會導致錯誤，表示應透過 disconnect() 中斷這個通訊端的連線。

  如果是 udp 通訊端，這只代表是否已指定預設遠端位址，用於讀取和寫入封包。

• localAddress

  字串 選填

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

• localPort

  數字 選填

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

• peerAddress

  字串 選填

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

• peerPort

  數字 選填

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

• socketType

  SocketType

  傳遞的通訊端類型。這個參數值應是 tcp 或 udp。

SocketType

列舉

"tcp"

"udp"

TLSVersionConstraints

屬性

• max

  字串 選填

• 分鐘

  字串 選填

  可接受的 TLS 最低和最高版本。支援的值為 tls1.2 或 tls1.3。

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

WriteInfo

屬性

• bytesWritten

  數字

  傳送的位元組數，或負數錯誤代碼。

方法

accept()

chrome.socket.accept(
  socketId: number,
  callback: function,
): void

這個方法僅適用於 TCP 通訊端。註冊回呼函式，在監聽伺服器通訊端接受連線時呼叫。必須先呼叫 Listen。如果已有有效的接受回呼，系統會立即叫用這個回呼，並將錯誤設為 resultCode。

參數

• socketId

  數字

  socketId。

• callback

  函式

  callback 參數如下：

  (acceptInfo: AcceptInfo) => void

  • acceptInfo

    AcceptInfo

bind()

chrome.socket.bind(
  socketId: number,
  address: string,
  port: number,
  callback: function,
): void

繫結通訊端的本機位址。目前不支援 TCP 通訊端。

參數

• socketId

  數字

  socketId。

• 地址

  字串

  本機機器的位址。

• 通訊埠

  數字

  本機電腦的通訊埠。

• callback

  函式

  callback 參數如下：

  (result: number) => void

  • 結果

    數字

connect()

chrome.socket.connect(
  socketId: number,
  hostname: string,
  port: number,
  callback: function,
): void

將通訊端連線至遠端機器 (適用於 tcp 通訊端)。如果是 udp 通訊端，這會設定預設位址，封包會傳送至該位址，並從該位址讀取 read() 和 write() 呼叫。

參數

• socketId

  數字

  socketId。

• 主機名稱

  字串

  遠端機器的主機名稱或 IP 位址。

• 通訊埠

  數字

  遠端機器的通訊埠。

• callback

  函式

  callback 參數如下：

  (result: number) => void

  • 結果

    數字

create()

Promise

chrome.socket.create(
  type: SocketType,
  options?: CreateOptions,
  callback?: function,
): Promise<CreateInfo>

建立指定類型的通訊端，連線至指定的遠端機器。

參數

• 類型

  SocketType

  要建立的通訊端類型。必須是 tcp 或 udp。

• 選項

  CreateOptions 選填

  通訊端選項。

• callback

  函式 選填

  callback 參數如下：

  (createInfo: CreateInfo) => void

  • createInfo

    CreateInfo

傳回

• Promise<CreateInfo>

  Chrome 121 以上版本

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

destroy()

chrome.socket.destroy(
  socketId: number,
): void

刪除通訊端。每個建立的通訊端都應在使用後刪除。

參數

• socketId

  數字

  socketId。

disconnect()

chrome.socket.disconnect(
  socketId: number,
): void

中斷通訊端連線。如果是 UDP 通訊端，disconnect 則為非作業，但可以安全呼叫。

參數

• socketId

  數字

  socketId。

getInfo()

Promise

chrome.socket.getInfo(
  socketId: number,
  callback?: function,
): Promise<SocketInfo>

擷取指定通訊端的狀態。

參數

• socketId

  數字

  socketId。

• callback

  函式 選填

  callback 參數如下：

  (result: SocketInfo) => void

  • 結果

    SocketInfo

傳回

• Promise<SocketInfo>

  Chrome 121 以上版本

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

getJoinedGroups()

chrome.socket.getJoinedGroups(
  socketId: number,
  callback: function,
): void

取得通訊端目前加入的多點傳播群組位址。

參數

• socketId

  數字

  socketId。

• callback

  函式

  callback 參數如下：

  (groups: string[]) => void

  • 群組

    string[]

getNetworkList()

Promise

chrome.socket.getNetworkList(
  callback?: function,
): Promise<NetworkInterface[]>

擷取這個系統上本機轉接器的相關資訊。

參數

• callback

  函式 選填

  callback 參數如下：

  (result: NetworkInterface[]) => void

  • 結果

    NetworkInterface[]

傳回

• Promise<NetworkInterface[]>

  Chrome 121 以上版本

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

joinGroup()

chrome.socket.joinGroup(
  socketId: number,
  address: string,
  callback: function,
): void

加入多點傳播群組，並開始接收該群組的封包。通訊端必須是 UDP 類型，且必須繫結至本機通訊埠，才能呼叫這個方法。

參數

• socketId

  數字

  socketId。

• 地址

  字串

  要加入的群組地址。系統不支援網域名稱。

• callback

  函式

  callback 參數如下：

  (result: number) => void

  • 結果

    數字

leaveGroup()

chrome.socket.leaveGroup(
  socketId: number,
  address: string,
  callback: function,
): void

退出先前使用 joinGroup 加入的多點傳播群組。您不必先離開多點傳播群組，再刪除通訊端或結束。OS 會自動呼叫這個方法。

離開群組後，路由器就不會將多點傳播資料圖傳送至本機主機，前提是主機上沒有其他程序仍加入群組。

參數

• socketId

  數字

  socketId。

• 地址

  字串

  要退出的群組地址。系統不支援網域名稱。

• callback

  函式

  callback 參數如下：

  (result: number) => void

  • 結果

    數字

listen()

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

這個方法僅適用於 TCP 通訊端。監聽指定通訊埠和位址的連線。這會使這個通訊端成為伺服器通訊端，且用戶端通訊端函式 (連線、讀取、寫入) 無法再用於這個通訊端。

參數

• socketId

  數字

  socketId。

• 地址

  字串

  本機機器的位址。

• 通訊埠

  數字

  本機電腦的通訊埠。

• 待處理工作

  數字 選填

  通訊端監聽佇列的長度。

• callback

  函式

  callback 參數如下：

  (result: number) => void

  • 結果

    數字

read()

chrome.socket.read(
  socketId: number,
  bufferSize?: number,
  callback: function,
): void

從指定的已連線通訊端讀取資料。

參數

• socketId

  數字

  socketId。

• bufferSize

  數字 選填

  讀取緩衝區空間。

• callback

  函式

  callback 參數如下：

  (readInfo: ReadInfo) => void

  • readInfo

    ReadInfo

recvFrom()

chrome.socket.recvFrom(
  socketId: number,
  bufferSize?: number,
  callback: function,
): void

接收來自指定 UDP 通訊端的資料。

參數

• socketId

  數字

  socketId。

• bufferSize

  數字 選填

  接收緩衝區空間。

• callback

  函式

  callback 參數如下：

  (recvFromInfo: RecvFromInfo) => void

  • recvFromInfo

    RecvFromInfo

secure()

chrome.socket.secure(
  socketId: number,
  options?: SecureOptions,
  callback: function,
): void

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

參數

• socketId

  數字

  要使用的已連線通訊端。

• 選項

  SecureOptions 選用

  TLS 連線的限制和參數。

• callback

  函式

  callback 參數如下：

  (result: number) => void

  • 結果

    數字

sendTo()

chrome.socket.sendTo(
  socketId: number,
  data: ArrayBuffer,
  address: string,
  port: number,
  callback: function,
): void

將指定 UDP 通訊端上的資料傳送至指定位址和通訊埠。

參數

• socketId

  數字

  socketId。

• 資料

  ArrayBuffer

  要寫入的資料。

• 地址

  字串

  遠端機器的位址。

• 通訊埠

  數字

  遠端機器的通訊埠。

• callback

  函式

  callback 參數如下：

  (writeInfo: WriteInfo) => void

  • writeInfo

    WriteInfo

setKeepAlive()

chrome.socket.setKeepAlive(
  socketId: number,
  enable: boolean,
  delay?: number,
  callback: function,
): void

啟用或停用 TCP 連線的 Keep-Alive 功能。

參數

• socketId

  數字

  socketId。

• 啟用

  布林值

  如果為 true，則啟用 keep-alive 功能。

• delay

  數字 選填

  設定收到最後一個資料封包到第一個 Keepalive 探測之間的延遲秒數。預設值為 0。

• callback

  函式

  callback 參數如下：

  (result: boolean) => void

  • 結果

    布林值

setMulticastLoopbackMode()

chrome.socket.setMulticastLoopbackMode(
  socketId: number,
  enabled: boolean,
  callback: function,
): void

設定是否要將從主機傳送至多點傳播群組的多點傳播封包，回送至主機。

注意：setMulticastLoopbackMode 的行為在 Windows 和 Unix 類系統之間略有不同。只有在同一主機上有多個應用程式加入同一個多點傳播群組，且多點傳播回送模式設定不同時，才會發生不一致的情況。在 Windows 上，關閉回送功能的應用程式不會「接收」回送封包；在類 Unix 系統上，關閉回送功能的應用程式不會將回送封包「傳送」至同一主機上的其他應用程式。請參閱 MSDN：https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

呼叫這個方法不需要多點傳播權限。

參數

• socketId

  數字

  socketId。

• 已啟用

  布林值

  指出是否要啟用回送模式。

• callback

  函式

  callback 參數如下：

  (result: number) => void

  • 結果

    數字

setMulticastTimeToLive()

chrome.socket.setMulticastTimeToLive(
  socketId: number,
  ttl: number,
  callback: function,
): void

設定傳送至多點傳播群組的多點傳播封包存留時間。

呼叫這個方法不需要多點傳播權限。

參數

• socketId

  數字

  socketId。

• ttl

  數字

  存留時間值。

• callback

  函式

  callback 參數如下：

  (result: number) => void

  • 結果

    數字

setNoDelay()

chrome.socket.setNoDelay(
  socketId: number,
  noDelay: boolean,
  callback: function,
): void

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

參數

• socketId

  數字

  socketId。

• noDelay

  布林值

  如果設為 true，則會停用 Nagle 演算法。

• callback

  函式

  callback 參數如下：

  (result: boolean) => void

  • 結果

    布林值

write()

chrome.socket.write(
  socketId: number,
  data: ArrayBuffer,
  callback: function,
): void

將資料寫入指定的連線通訊端。

參數

• socketId

  數字

  socketId。

• 資料

  ArrayBuffer

  要寫入的資料。

• callback

  函式

  callback 參數如下：

  (writeInfo: WriteInfo) => void

  • writeInfo

    WriteInfo