說明
使用 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
SocketInfo
屬性
-
已連線。
boolean
是否已連接基礎通訊端。
對於
tcp
通訊端,即使遠端對等點已中斷連線,此權限仍將為 true。讀取或寫入通訊端可能會發生錯誤,提示該通訊端應透過disconnect()
中斷連線。對於
udp
通訊端,這只是表示是否已指定預設的遠端位址來讀取和寫入封包。 -
localAddress
字串 選用
如果基礎通訊端已繫結或已連線,則包含本機 IPv4/6 位址。
-
localPort
數字 選填
如果基礎通訊端已繫結或已連線,則包含其本機通訊埠。
-
peerAddress
字串 選用
如果已連線至基礎通訊端,則會包含對等點的 IPv4/6 位址。
-
peerPort
數字 選填
如果已連接基礎通訊端,則會包含已連線對等點的通訊埠。
-
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
-
acceptInfo
-
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()
chrome.socket.create(
type: SocketType,
options?: CreateOptions,
callback?: function,
)
建立指定類型的通訊端,以便連線到指定遠端機器。
參數
-
類型
要建立的通訊端類型。必須為
tcp
或udp
。 -
選項
通訊端選項。
-
回呼
函式選用
callback
參數如下所示:(createInfo: CreateInfo) => void
-
createInfo
-
傳回
-
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()
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()
chrome.socket.getNetworkList(
callback?: function,
)
擷取系統上的本機轉接器相關資訊。
參數
-
回呼
函式選用
callback
參數如下所示:(result: NetworkInterface[]) => void
-
結果
-
傳回
-
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
-
readInfo
-
recvFrom()
chrome.socket.recvFrom(
socketId: number,
bufferSize?: number,
callback: function,
)
從指定的 UDP 通訊端接收資料。
參數
-
socketId
號碼
socketId.
-
bufferSize
數字 選填
接收緩衝區空間。
-
回呼
功能
callback
參數如下所示:(recvFromInfo: RecvFromInfo) => void
-
recvFromInfo
-
secure()
chrome.socket.secure(
socketId: number,
options?: SecureOptions,
callback: function,
)
透過已連線的 TCP 用戶端通訊端啟動 TLS 用戶端連線。
參數
-
socketId
號碼
要使用的已連線通訊端。
-
選項
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
-
writeInfo
-
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,
)
這個外掛程式能在指定的已連線通訊端上寫入資料。