chrome.sockets.udp

說明

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

資訊清單

如要使用這個 API，您必須在資訊清單中宣告下列鍵。

"sockets"

類型

CreateInfo

屬性

  • socketId

    數字

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

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

    string 選填

    如果底層 Socket 已繫結，則包含本機 IPv4/6 位址。

  • localPort

    號碼 選填

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

  • 名稱

    string 選填

    與通訊端相關聯的應用程式定義字串。

  • 已暫停

    布林值

    此標記可指出是否封鎖了套接字，以免觸發 onReceive 事件。

  • 永久

    布林值

    此標記可指出應用程式暫停時是否會保留套接字 (請參閱 SocketProperties.persistent)。

  • socketId

    數字

    套接字 ID。

SocketProperties

屬性

  • bufferSize

    號碼 選填

    用來接收資料的緩衝區大小。如果緩衝區太小，無法接收 UDP 封包，資料就會遺失。預設值為 4096。

  • 名稱

    string 選填

    與通訊端相關聯的應用程式定義字串。

  • 永久

    boolean 選填

    標記，指出在卸載應用程式的事件頁面時，是否會保留開放的通訊端 (請參閱「管理應用程式生命週期」)。預設值為「false」。應用程式載入時，getSockets 可擷取先前以 persistent=true 開啟的任何 Socket。

方法

bind()

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

繫結 Socket 的本機位址和通訊埠。對於用戶端 Socket，建議使用 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,
)

關閉 Socket，並釋放 Socket 繫結的位址/連接埠。每個建立的 Socket 都應在使用後關閉。函式一呼叫，這個 Socket ID 就會失效。不過，只有在呼叫回呼時，系統才會保證關閉 Socket。

參數

  • socketId

    數字

    套接字 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 121 以上版本

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

create()

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

使用指定的屬性建立 UDP 通訊端。

參數

  • 資源

    SocketProperties 選填

    套接字屬性 (選用)。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      建立 Socket 的結果。

傳回

  • Promise<CreateInfo>

    Chrome 121 以上版本

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

getInfo()

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

擷取指定 Socket 的狀態。

參數

  • socketId

    數字

    套接字 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      包含 Socket 資訊的物件。

傳回

  • Promise<SocketInfo>

    Chrome 121 以上版本

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

getJoinedGroups()

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

取得目前已加入的通訊端連接埠多播群組位址。

參數

  • socketId

    數字

    套接字 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (groups: string[]) => void

    • 群組

      string[]

      套接字加入的群組陣列。

傳回

  • Promise<string[]>

    Chrome 121 以上版本

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

getSockets()

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

擷取應用程式目前已開啟的通訊端口清單。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

      包含 Socket 資訊的物件陣列。

傳回

  • Promise<SocketInfo[]>

    Chrome 121 以上版本

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

joinGroup()

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

加入多播群組，並開始接收該群組的封包。呼叫此方法前，必須先將 Socket 繫結至本機埠。

參數

  • socketId

    數字

    套接字 ID。

  • 地址

    字串

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

  • 回呼

    函式

    callback 參數如下所示： 

    (result: number) => void

    • 結果

      數字

      基礎網路呼叫傳回的結果代碼。負值表示錯誤。

leaveGroup()

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

離開先前使用 joinGroup 加入的多播群組。只有在您打算之後繼續使用這個 Socket 時，才需要呼叫這個方法，因為 OS 會在 Socket 關閉時自動執行這個動作。

離開群組後，路由器就無法將多播資料報傳送至本機主機，除非主機上沒有其他程序仍加入群組。

參數

  • 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,
)

啟用或停用此 Socket 上的廣播封包。

參數

  • socketId

    數字

    套接字 ID。

  • 已啟用

    布林值

    true 可啟用廣播封包，false 可停用廣播封包。

  • 回呼

    函式

    callback 參數如下所示： 

    (result: number) => void

    • 結果

      數字

      基礎網路呼叫傳回的結果代碼。

setMulticastLoopbackMode()

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

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

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

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

參數

  • socketId

    數字

    套接字 ID。

  • 已啟用

    布林值

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

  • 回呼

    函式

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

暫停或取消暫停一個 Socket。已暫停的通訊端會遭到封鎖，無法觸發 onReceive 事件。

參數

  • socketId

    數字

  • 已暫停

    布林值

    標記，用於指出是否要暫停或取消暫停。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 121 以上版本

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

update()

Promise 
chrome.sockets.udp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
)

更新 Socket 屬性。

參數

  • socketId

    數字

    套接字 ID。

  • 要更新的房源屬性。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 121 以上版本

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

活動

onReceive

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

當系統收到指定 Socket 的 UDP 封包時，會觸發此事件。

參數

onReceiveError

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

當執行階段等待套接字位址和通訊埠的資料時，發生網路錯誤時會觸發事件。這個事件一經觸發，Socket 就會暫停，且在 Socket 恢復之前，系統不會再為此 Socket 觸發 onReceive 事件。

參數