chrome.socket

說明

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

權限

socket

類型

AcceptInfo

屬性

  • resultCode

    數字

  • socketId

    號碼 選填

    已接受的 Socket ID。

CreateInfo

屬性

  • socketId

    數字

    新建立的 Socket ID。

CreateOptions

NetworkInterface

屬性

  • 地址

    字串

    可用的 IPv4/6 位址。

  • 名稱

    字串

    顯示卡的基礎名稱。在 *nix 上，這通常會是「eth0」、「lo」等。

  • prefixLength

    數字

    前置字串長度

ReadInfo

屬性

  • 資料

    ArrayBuffer

  • resultCode

    數字

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

RecvFromInfo

屬性

  • 地址

    字串

    遠端機器的位址。

  • 資料

    ArrayBuffer

  • 通訊埠

    數字

  • resultCode

    數字

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

SecureOptions

屬性

SocketInfo

屬性

  • 已連線。

    布林值

    是否已連線至基礎的 Socket。

    對於 tcp 套接字，即使遠端對等端已中斷連線，此情況仍會維持不變。讀取或寫入套接字可能會導致錯誤，暗示這個套接字應透過 disconnect() 中斷連線。

    對於 udp 套接字，這只是代表是否已指定讀取和寫入封包的預設遠端位址。

  • localAddress

    string 選填

    如果底層套接字已繫結或連線，則包含本機 IPv4/6 位址。

  • localPort

    號碼 選填

    如果底層 Socket 已繫結或連線，則包含本機通訊埠。

  • peerAddress

    string 選填

    如果底層 Socket 已連線，則包含對等端的 IPv4/6 位址。

  • peerPort

    號碼 選填

    如果底層 Socket 已連線，則包含已連線對等端的連接埠。

  • socketType

    SocketType

    傳遞的 Socket 類型。這會是 tcp 或 udp。

SocketType

列舉

"tcp"

"udp"

TLSVersionConstraints

屬性

  • 最高

    string 選填

  • 分鐘

    string 選填

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

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

WriteInfo

屬性

  • bytesWritten

    數字

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

方法

accept()

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

這個方法僅適用於 TCP 通訊端。註冊回呼函式，以便在這個監聽伺服器 Socket 上接受連線時呼叫。必須先呼叫 Listen。如果已存在有效的接受回呼，系統會立即叫用此回呼，並將錯誤做為 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,
)

將 Socket 連線至遠端機器 (適用於 tcp Socket)。對於 udp 通訊端，這會設定預設的封包傳送和讀取位置，以便進行 read() 和 write() 呼叫。

參數

  • socketId

    數字

    socketId。

  • 主機名稱

    字串

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

  • 通訊埠

    數字

    遠端電腦的通訊埠。

  • 回呼

    函式

    callback 參數如下所示： 

    (result: number) => void

    • 結果

      數字

create()

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

建立指定類型的 Socket，以便連線至指定的遠端機器。

參數

  • 類型

    SocketType

    要建立的 Socket 類型。必須是 tcp 或 udp。

  • 選項

    CreateOptions 選填

    套接字選項。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (createInfo: CreateInfo) => void

傳回

  • Promise<CreateInfo>

    Chrome 121 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

destroy()

chrome.socket.destroy(
  socketId: number,
)

銷毀 Socket。每個建立的 Socket 都應在使用後銷毀。

參數

  • socketId

    數字

    socketId。

disconnect()

chrome.socket.disconnect(
  socketId: number,
)

中斷 Socket。對於 UDP 通訊端，disconnect 是無操作，但可安全呼叫。

參數

  • socketId

    數字

    socketId。

getInfo()

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

擷取指定 Socket 的狀態。

參數

  • socketId

    數字

    socketId。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (result: SocketInfo) => void

傳回

  • Promise<SocketInfo>

    Chrome 121 以上版本

    承諾僅支援資訊清單 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 以上版本

    承諾僅支援資訊清單 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 用戶端 Socket 啟動 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。

  • 啟用

    布林值

    如果為 true，則會啟用保活功能。

  • delay

    號碼 選填

    設定最後一次收到資料封包與第一次探測保活功能之間的延遲秒數。預設值為 0。

  • 回呼

    函式

    callback 參數如下所示： 

    (result: boolean) => void

    • 結果

      布林值

setMulticastLoopbackMode()

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

設定從主機傳送至多播群組的多播封包是否會迴傳至主機。

注意：Windows 和類 Unix 系統的 setMulticastLoopbackMode 行為略有不同。只有在同一個主機上有多個應用程式加入同一個多播群組，且多播迴送模式設定不同時，才會發生不一致的情形。在 Windows 上，關閉迴送的應用程式不會接收迴送封包；在類 Unix 系統上，關閉迴送的應用程式不會將迴送封包傳送至相同主機上的其他應用程式。請參閱 MSDN：http://goo.gl/6vqbj

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

參數

  • socketId

    數字

    socketId。

  • 已啟用

    布林值

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

  • 回呼

    函式

    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

    布林值

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

  • 回呼

    函式

    callback 參數如下所示： 

    (result: boolean) => void

    • 結果

      布林值

write()

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

在指定的已連接套接字上寫入資料。

參數

  • socketId

    數字

    socketId。

  • 資料

    ArrayBuffer

    要寫入的資料。

  • 回呼

    函式

    callback 參數如下所示： 

    (writeInfo: WriteInfo) => void