chrome.sockets.udp

說明

使用 chrome.sockets.udp API 透過網路使用 UDP 連線傳送及接收資料。這個 API 取代了之前在「socket」API 中找到的 UDP 功能。

資訊清單

您必須在資訊清單中宣告下列金鑰，才能使用這個 API。

"sockets"

類型

CreateInfo

屬性

  • socketId

    號碼

    新建通訊端的 ID。請注意，透過此 API 建立的通訊端 ID 與透過其他 API (例如已淘汰的 [socket](../socket/) API) 建立的通訊端 ID 不相容。

DnsQueryType

Chrome 103 以上版本

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()

Promise 
chrome.sockets.udp.close(
  socketId: number,
  callback?: function,
)

關閉通訊端並釋放通訊端所繫結的位址/通訊埠。使用之後，建立的每個通訊端都應該關閉。呼叫函式後，通訊端 ID 就會立即失效。但是，通訊端保證只有在叫用回呼時才會關閉。

參數

  • socketId

    號碼

    通訊端 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 121 以上版本

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

create()

Promise 
chrome.sockets.udp.create(
  properties?: SocketProperties,
  callback?: function,
)

建立具有指定屬性的 UDP 通訊端。

參數

  • 資源

    SocketProperties 選用

    通訊端屬性 (選用)。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (createInfo: CreateInfo)=>void

    • createInfo

      CreateInfo

      通訊端建立的結果。

傳回

  • Promise<CreateInfo>

    Chrome 121 以上版本

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

getInfo()

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

擷取指定通訊端的狀態。

參數

  • socketId

    號碼

    通訊端 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (socketInfo: SocketInfo)=>void

    • socketInfo

      SocketInfo

      包含通訊端資訊的物件。

傳回

  • Promise<SocketInfo>

    Chrome 121 以上版本

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

getJoinedGroups()

Promise 
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
)

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

參數

  • socketId

    號碼

    通訊端 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (groups: string[])=>void

    • 群組

      string[]

      通訊端加入的群組陣列。

傳回

  • Promise<string[]>

    Chrome 121 以上版本

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

getSockets()

Promise 
chrome.sockets.udp.getSockets(
  callback?: function,
)

擷取應用程式擁有的通訊端清單。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    (socketInfos: SocketInfo[])=>void

    • socketInfos

      SocketInfo[]

      包含通訊端資訊的物件陣列。

傳回

  • 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

      SendInfo

      send 方法的結果。

setBroadcast()

Chrome 44 以上版本 
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()

Promise 
chrome.sockets.udp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
)

暫停或取消暫停通訊端。暫停的通訊端無法觸發 onReceive 事件。

參數

  • socketId

    號碼

  • 已暫停

    boolean

    表明要暫停或取消暫停的標記。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 121 以上版本

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

update()

Promise 
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 封包時引發的事件。

參數

onReceiveError

chrome.sockets.udp.onReceiveError.addListener(
  callback: function,
)

當執行階段等待通訊端位址和通訊埠上的資料時，發生網路錯誤時引發事件。引發這個事件後，通訊端就會暫停，而且在通訊端重新啟動前，通訊端不會再發出 onReceive 事件。

參數