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

屬性

SocketInfo

屬性

  • 已連線。

    boolean

    是否已連接基礎通訊端。

    對於 tcp 通訊端，即使遠端對等點已中斷連線，此權限仍將為 true。讀取或寫入通訊端可能會發生錯誤，提示該通訊端應透過 disconnect() 中斷連線。

    對於 udp 通訊端，這只是表示是否已指定預設的遠端位址來讀取和寫入封包。

  • localAddress

    字串 選用

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

  • localPort

    數字 選填

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

  • peerAddress

    字串 選用

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

  • peerPort

    數字 選填

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

  • socketType

    SocketType

    已傳遞通訊端的類型。將會是 tcp 或 udp。

SocketType

列舉

TLSVersionConstraints

屬性

  • 最高

    字串 選用

  • 分鐘

    字串 選用

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

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

WriteInfo

屬性

  • bytesWritten

    號碼

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

方法

accept()

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

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

參數

  • socketId

    號碼

    socketId.

  • 回呼

    功能

    callback 參數如下所示： 

    (acceptInfo: AcceptInfo)=>void

bind()

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

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

參數

  • socketId

    號碼

    socketId.

  • 地址

    字串

    本機電腦的位址。

  • 通訊埠

    號碼

    本機電腦的通訊埠。

  • 回呼

    功能

    callback 參數如下所示： 

    (result: number)=>void

    • 結果

      號碼

connect()

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

將通訊端連接到遠端機器 (用於 tcp 通訊端)。對於 udp 通訊端，這會設定 read() 和 write() 呼叫傳送及讀取封包的預設位址。

參數

  • socketId

    號碼

    socketId.

  • 主機名稱

    字串

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

  • 通訊埠

    號碼

    遠端電腦的通訊埠。

  • 回呼

    功能

    callback 參數如下所示： 

    (result: number)=>void

    • 結果

      號碼

create()

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

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

參數

  • 類型

    SocketType

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

  • 選項

    CreateOptions 選用

    通訊端選項。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (createInfo: CreateInfo)=>void

傳回

  • Promise<CreateInfo>

    Chrome 121 以上版本

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

destroy()

chrome.socket.destroy(
  socketId: number,
)

刪除通訊端。使用之後，應刪除已建立的每個通訊端。

參數

  • socketId

    號碼

    socketId.

disconnect()

chrome.socket.disconnect(
  socketId: number,
)

拔除通訊端。對於 UDP 通訊端，disconnect 是非作業，但可以安全呼叫。

參數

  • socketId

    號碼

    socketId.

getInfo()

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

擷取指定通訊端的狀態。

參數

  • socketId

    號碼

    socketId.

  • 回呼

    函式選用

    callback 參數如下所示： 

    (result: SocketInfo)=>void

傳回

  • Promise<SocketInfo>

    Chrome 121 以上版本

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

getJoinedGroups()

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

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

參數

  • socketId

    號碼

    socketId.

  • 回呼

    功能

    callback 參數如下所示： 

    (groups: string[])=>void

    • 群組

      string[]

getNetworkList()

Promise 
chrome.socket.getNetworkList(
  callback?: function,
)

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

參數

傳回

  • Promise<NetworkInterface[]>

    Chrome 121 以上版本

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

joinGroup()

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

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

參數

  • socketId

    號碼

    socketId.

  • 地址

    字串

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

  • 回呼

    功能

    callback 參數如下所示： 

    (result: number)=>void

    • 結果

      號碼

leaveGroup()

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

退出先前使用 joinGroup 加入的多點傳播群組。刪除通訊端或退出之前，您不需要退出多點傳送群組。作業系統會自動呼叫此方法。

如果離開群組，路由器就無法向本機主機傳送多點傳播資料圖，假設主機上沒有任何其他程序仍加入群組。

參數

  • socketId

    號碼

    socketId.

  • 地址

    字串

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

  • 回呼

    功能

    callback 參數如下所示： 

    (result: number)=>void

    • 結果

      號碼

listen()

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

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

參數

  • socketId

    號碼

    socketId.

  • 地址

    字串

    本機電腦的位址。

  • 通訊埠

    號碼

    本機電腦的通訊埠。

  • 待處理

    數字 選填

    通訊端的監聽佇列長度。

  • 回呼

    功能

    callback 參數如下所示： 

    (result: number)=>void

    • 結果

      號碼

read()

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

這個外掛程式能從指定的已連線通訊端讀取資料。

參數

  • socketId

    號碼

    socketId.

  • bufferSize

    數字 選填

    讀取緩衝區空間。

  • 回呼

    功能

    callback 參數如下所示： 

    (readInfo: ReadInfo)=>void

recvFrom()

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

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

參數

  • socketId

    號碼

    socketId.

  • bufferSize

    數字 選填

    接收緩衝區空間。

  • 回呼

    功能

    callback 參數如下所示： 

    (recvFromInfo: RecvFromInfo)=>void

secure()

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

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

參數

  • socketId

    號碼

    要使用的已連線通訊端。

  • 選項

    SecureOptions 選用

    TLS 連線的限制和參數。

  • 回呼

    功能

    callback 參數如下所示： 

    (result: number)=>void

    • 結果

      號碼

sendTo()

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

這個外掛程式能將指定 UDP 通訊端的資料傳送到指定的位址和通訊埠。

參數

  • socketId

    號碼

    socketId.

  • 資料或曾存取這類資料的人員

    ArrayBuffer

    要寫入的資料。

  • 地址

    字串

    遠端機器的位址。

  • 通訊埠

    號碼

    遠端電腦的通訊埠。

  • 回呼

    功能

    callback 參數如下所示： 

    (writeInfo: WriteInfo)=>void

setKeepAlive()

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

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

參數

  • socketId

    號碼

    socketId.

  • enable

    boolean

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

  • delay

    數字 選填

    設定在最後一個資料封包接收到與第一次保持運作探測之間之間的延遲時間 (秒)。預設值為 0。

  • 回呼

    功能

    callback 參數如下所示： 

    (result: boolean)=>void

    • 結果

      boolean

setMulticastLoopbackMode()

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

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

注意：setMulticastLoopbackMode 的行為在 Windows 和類似 Unix 的系統之間稍有不同。只有在相同主機上有多個應用程式加入相同的多點傳播群組時，並在多點回送模式下設定不同設定時，才會發生不一致的情況。在 Windows 上，具有回送機制的應用程式不會「收到」回送封包；在 Unix 類似系統上，掛回功能的應用程式將不會傳送回送封包給同一主機上其他應用程式的回送封包。請參閱 MSDN：http://goo.gl/6vqbj

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

參數

  • socketId

    號碼

    socketId.

  • 已啟用

    boolean

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

  • 回呼

    功能

    callback 參數如下所示： 

    (result: number)=>void

    • 結果

      號碼

setMulticastTimeToLive()

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

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

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

參數

  • socketId

    號碼

    socketId.

  • ttl

    號碼

    存留時間值。

  • 回呼

    功能

    callback 參數如下所示： 

    (result: number)=>void

    • 結果

      號碼

setNoDelay()

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

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

參數

  • socketId

    號碼

    socketId.

  • noDelay

    boolean

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

  • 回呼

    功能

    callback 參數如下所示： 

    (result: boolean)=>void

    • 結果

      boolean

write()

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

這個外掛程式能在指定的已連線通訊端上寫入資料。

參數

  • socketId

    號碼

    socketId.

  • 資料或曾存取這類資料的人員

    ArrayBuffer

    要寫入的資料。

  • 回呼

    功能

    callback 參數如下所示： 

    (writeInfo: WriteInfo)=>void