說明
使用 chrome.sockets.udp
API 透過網路使用 UDP 連線傳送及接收資料。這個 API 取代了之前在「socket」API 中找到的 UDP 功能。
資訊清單
類型
CreateInfo
屬性
-
socketId
號碼
新建通訊端的 ID。請注意,透過此 API 建立的通訊端 ID 與透過其他 API (例如已淘汰的
[
socket](../socket/)
API) 建立的通訊端 ID 不相容。
DnsQueryType
DNS 解析偏好設定。預設值為 any
,且採用目前的 OS 設定,可能會傳回 IPv4 或 IPv6。ipv4
會強制使用 IPv4,ipv6
則會強制使用 IPv6。
列舉
"any"
"ipv4"
「ipv6」
ReceiveErrorInfo
屬性
-
resultCode
號碼
基礎 recvfrom() 呼叫傳回的結果代碼。
-
socketId
號碼
通訊端 ID。
ReceiveInfo
屬性
-
資料或曾存取這類資料的人員
ArrayBuffer
UDP 封包內容 (會截斷至目前的緩衝區大小)。
-
remoteAddress
字串
封包來源的主機位址。
-
remotePort
號碼
封包來源主機的通訊埠。
-
socketId
號碼
通訊端 ID。
SendInfo
屬性
-
bytesSent
數字 選填
傳送的位元組數量 (如果結果 == 0)
-
resultCode
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
SocketInfo
屬性
-
bufferSize
數字 選填
用於接收資料的緩衝區大小。如果沒有明確指定緩衝區大小,系統就不會提供該值。
-
localAddress
字串 選用
如果基礎通訊端受到繫結,會包含其本機 IPv4/6 位址。
-
localPort
數字 選填
如果基礎通訊端受到繫結,則包含其本機通訊埠。
-
名稱
字串 選用
與通訊端相關聯的應用程式定義字串。
-
已暫停
boolean
此標記可註明通訊端是否遭到封鎖,無法觸發 onReceive 事件。
-
永久
boolean
此標記可註明應用程式暫停時,通訊端是否處於開啟狀態 (請參閱
SocketProperties.persistent
)。 -
socketId
號碼
通訊端 ID。
SocketProperties
屬性
-
bufferSize
數字 選填
用於接收資料的緩衝區大小。如果緩衝區太小,無法接收 UDP 封包,資料就會遺失。預設值為 4096。
-
名稱
字串 選用
與通訊端相關聯的應用程式定義字串。
-
永久
布林值 (選用)
此標記可表示當應用程式的事件頁面卸載時,通訊端是否處於開啟狀態 (請參閱「管理應用程式生命週期」)。預設值為「false」。應用程式載入時,可使用
getSockets
擷取先前以 persistent=true 開啟的任何通訊端。
方法
bind()
chrome.sockets.udp.bind(
socketId: number,
address: string,
port: number,
callback: function,
)
繫結通訊端的本機位址及通訊埠。如果是用戶端通訊端,建議使用通訊埠 0,讓平台選擇免費通訊埠。
bind
作業成功完成後,除非通訊端暫停,否則當 UDP 封包抵達指定的位址/通訊埠時,就會引發 onReceive
事件。
參數
-
socketId
號碼
通訊端 ID。
-
地址
字串
本機電腦的位址。系統支援 DNS 名稱、IPv4 和 IPv6 格式。使用「0.0.0.0」以接受來自所有本機可用網路介面的封包。
-
通訊埠
號碼
本機電腦的通訊埠。使用「0」可繫結至免費通訊埠,
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
-
close()
chrome.sockets.udp.close(
socketId: number,
callback?: function,
)
關閉通訊端並釋放通訊端所繫結的位址/通訊埠。使用之後,建立的每個通訊端都應該關閉。呼叫函式後,通訊端 ID 就會立即失效。但是,通訊端保證只有在叫用回呼時才會關閉。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
create()
chrome.sockets.udp.create(
properties?: SocketProperties,
callback?: function,
)
建立具有指定屬性的 UDP 通訊端。
參數
-
資源
通訊端屬性 (選用)。
-
回呼
函式選用
callback
參數如下所示:(createInfo: CreateInfo) => void
-
createInfo
通訊端建立的結果。
-
傳回
-
Promise<CreateInfo>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getInfo()
chrome.sockets.udp.getInfo(
socketId: number,
callback?: function,
)
擷取指定通訊端的狀態。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:(socketInfo: SocketInfo) => void
-
socketInfo
包含通訊端資訊的物件。
-
傳回
-
Promise<SocketInfo>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getJoinedGroups()
chrome.sockets.udp.getJoinedGroups(
socketId: number,
callback?: function,
)
取得通訊端目前加入的多點傳播群組位址。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:(groups: string[]) => void
-
群組
string[]
通訊端加入的群組陣列。
-
傳回
-
Promise<string[]>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getSockets()
chrome.sockets.udp.getSockets(
callback?: function,
)
擷取應用程式擁有的通訊端清單。
參數
-
回呼
函式選用
callback
參數如下所示:(socketInfos: SocketInfo[]) => void
-
socketInfos
包含通訊端資訊的物件陣列。
-
傳回
-
Promise<SocketInfo[]>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
joinGroup()
chrome.sockets.udp.joinGroup(
socketId: number,
address: string,
callback: function,
)
加入多點傳送群組,並開始接收該群組的封包。在呼叫這個方法之前,通訊端必須繫結至本機連接埠。
參數
-
socketId
號碼
通訊端 ID。
-
地址
字串
要加入的群組地址。系統不支援網域名稱。
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
-
leaveGroup()
chrome.sockets.udp.leaveGroup(
socketId: number,
address: string,
callback: function,
)
退出先前使用 joinGroup
加入的多點傳送群組。只有在您打算之後繼續使用通訊端時,才需要呼叫此方法,因為 OS 會在通訊端關閉時自動執行。
如果離開群組,路由器就無法向本機主機傳送多點傳播資料圖,假設主機上沒有任何其他程序仍加入群組。
參數
-
socketId
號碼
通訊端 ID。
-
地址
字串
要退出的群組地址。系統不支援網域名稱。
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
-
send()
chrome.sockets.udp.send(
socketId: number,
data: ArrayBuffer,
address: string,
port: number,
dnsQueryType?: DnsQueryType,
callback: function,
)
這個外掛程式能將指定通訊端的資料傳送至指定的位址和通訊埠。在呼叫這個方法之前,通訊端必須繫結至本機連接埠。
參數
-
socketId
號碼
通訊端 ID。
-
資料或曾存取這類資料的人員
ArrayBuffer
要傳送的資料。
-
地址
字串
遠端機器的位址。
-
通訊埠
號碼
遠端電腦的通訊埠。
-
dnsQueryType
DnsQueryType 選用
Chrome 103 以上版本地址解析度偏好設定。
-
回呼
功能
callback
參數如下所示:(sendInfo: SendInfo) => void
-
sendInfo
send
方法的結果。
-
setBroadcast()
chrome.sockets.udp.setBroadcast(
socketId: number,
enabled: boolean,
callback: function,
)
啟用或停用這個通訊端的廣播封包。
參數
-
socketId
號碼
通訊端 ID。
-
已啟用
boolean
如要啟用廣播封包,請設為
true
;如要停用,請設為false
。 -
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。
-
setMulticastLoopbackMode()
chrome.sockets.udp.setMulticastLoopbackMode(
socketId: number,
enabled: boolean,
callback: function,
)
設定是否針對從主機傳送至多點傳送群組的多點傳送封包,是否會將封包循環回主機。
注意:setMulticastLoopbackMode
的行為在 Windows 和類似 Unix 的系統之間稍有不同。只有在相同主機上有多個應用程式加入相同的多點傳播群組時,並在多點回送模式下設定不同設定時,才會發生不一致的情況。在 Windows 上,具有回送機制的應用程式不會「收到」回送封包;在 Unix 類似系統上,掛回功能的應用程式將不會傳送回送封包給同一主機上其他應用程式的回送封包。請參閱 MSDN:http://goo.gl/6vqbj
呼叫這個方法不需要多點傳播權限。
參數
-
socketId
號碼
通訊端 ID。
-
已啟用
boolean
指出是否要啟用回送模式。
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
-
setMulticastTimeToLive()
chrome.sockets.udp.setMulticastTimeToLive(
socketId: number,
ttl: number,
callback: function,
)
設定傳送至多點傳送群組的多點傳送封包的存留時間。
呼叫這個方法不需要多點傳播權限。
參數
-
socketId
號碼
通訊端 ID。
-
ttl
號碼
存留時間值。
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
-
setPaused()
chrome.sockets.udp.setPaused(
socketId: number,
paused: boolean,
callback?: function,
)
暫停或取消暫停通訊端。暫停的通訊端無法觸發 onReceive
事件。
參數
-
socketId
號碼
-
已暫停
boolean
表明要暫停或取消暫停的標記。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
update()
chrome.sockets.udp.update(
socketId: number,
properties: SocketProperties,
callback?: function,
)
更新通訊端屬性。
參數
-
socketId
號碼
通訊端 ID。
-
要更新的屬性。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
活動
onReceive
chrome.sockets.udp.onReceive.addListener(
callback: function,
)
系統收到指定通訊端的 UDP 封包時引發的事件。
參數
-
回呼
功能
callback
參數如下所示:(info: ReceiveInfo) => void
-
資訊
-
onReceiveError
chrome.sockets.udp.onReceiveError.addListener(
callback: function,
)
當執行階段等待通訊端位址和通訊埠上的資料時,發生網路錯誤時引發事件。引發這個事件後,通訊端就會暫停,而且在通訊端重新啟動前,通訊端不會再發出 onReceive
事件。
參數
-
回呼
功能
callback
參數如下所示:(info: ReceiveErrorInfo) => void