chrome.sockets.udp

説明

chrome.sockets.udp API を使用して、UDP 接続でネットワーク経由でデータを送受信します。この API は、以前の「socket」API にあった UDP 機能に代わるものです。

マニフェスト

この API を使用するには、次のキーをマニフェストで宣言する必要があります。

"sockets"

型

CreateInfo

プロパティ

  • socketId

    数値

    新しく作成されたソケットの ID。この API で作成されたソケット ID は、非推奨の [socket](../socket/) API など、他の 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

    number 省略可

    送信されたバイト数（result == 0 の場合）

  • resultCode

    数値

    基盤となるネットワーク呼び出しから返された結果コード。負の値はエラーを示します。

SocketInfo

プロパティ

  • bufferSize

    number 省略可

    データの受信に使用されるバッファのサイズ。バッファサイズが明示的に指定されていない場合、値は提供されません。

  • localAddress

    文字列 省略可

    基盤となるソケットがバインドされている場合は、そのローカル IPv4/6 アドレスが含まれます。

  • localPort

    number 省略可

    基盤となるソケットがバインドされている場合は、そのローカルポートが含まれます。

  • name

    文字列 省略可

    ソケットに関連付けられたアプリケーション定義の文字列。

  • 一時停止

    ブール値

    ソケットが onReceive イベントの発生をブロックされているかどうかを示すフラグ。

  • 永続

    ブール値

    アプリケーションが一時停止されたときにソケットを開いたままにするかどうかを示すフラグ（SocketProperties.persistent を参照）。

  • socketId

    数値

    ソケット識別子。

SocketProperties

プロパティ

  • bufferSize

    number 省略可

    データの受信に使用されるバッファのサイズ。バッファが小さすぎて UDP パケットを受信できない場合、データは失われます。デフォルト値は 4096 です。

  • name

    文字列 省略可

    ソケットに関連付けられたアプリケーション定義の文字列。

  • 永続

    boolean 省略可

    アプリケーションのイベントページがアンロードされたときにソケットを開いたままにするかどうかを示すフラグ（アプリのライフサイクルを管理するを参照）。デフォルト値は「false」です。アプリケーションが読み込まれると、persistent=true で以前に開かれたソケットを getSockets で取得できます。

メソッド

bind()

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

ソケットのローカル アドレスとポートをバインドします。クライアント ソケットの場合は、ポート 0 を使用して、プラットフォームが空きポートを選択できるようにすることをおすすめします。

bind オペレーションが正常に完了すると、指定されたアドレス / ポートに UDP パケットが到着したときに onReceive イベントが発生します（ソケットが一時停止されている場合を除く）。

パラメータ

  • socketId

    数値

    ソケット ID。

  • 住所

    文字列

    ローカルマシンのアドレス。DNS 名、IPv4、IPv6 の形式がサポートされています。「0.0.0.0」を使用すると、利用可能なすべてのローカル ネットワーク インターフェースからパケットを受け入れることができます。

  • ポート

    数値

    ローカルマシンのポート。「0」を使用して空きポートにバインドします。

  • callback

    関数

    callback パラメータは次のようになります。 

    (result: number) => void

    • 件の結果

      数値

      基盤となるネットワーク呼び出しから返された結果コード。負の値はエラーを示します。

close()

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

ソケットを閉じ、ソケットがバインドされているアドレス / ポートを解放します。作成したソケットは、使用後に閉じる必要があります。関数が呼び出されるとすぐに、ソケット ID は無効になります。ただし、ソケットが閉じられることが保証されるのは、コールバックが呼び出されたときのみです。

パラメータ

  • socketId

    数値

    ソケット ID。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 121 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

create()

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

指定されたプロパティを持つ UDP ソケットを作成します。

パラメータ

  • プロパティ

    SocketProperties 省略可

    ソケットのプロパティ（省略可）。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      ソケット作成の結果。

戻り値

  • Promise<CreateInfo>

    Chrome 121 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getInfo()

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

指定されたソケットの状態を取得します。

パラメータ

  • socketId

    数値

    ソケット ID。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      ソケット情報を含むオブジェクト。

戻り値

  • Promise<SocketInfo>

    Chrome 121 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getJoinedGroups()

Promise 
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
): Promise<string[]>

ソケットが現在参加しているマルチキャスト グループ アドレスを取得します。

パラメータ

  • socketId

    数値

    ソケット ID。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (groups: string[]) => void

    • グループ

      string[]

      ソケットが参加したグループの配列。

戻り値

  • Promise<string[]>

    Chrome 121 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getSockets()

Promise 
chrome.sockets.udp.getSockets(
  callback?: function,
): Promise<SocketInfo[]>

アプリケーションが所有する、現在開いているソケットのリストを取得します。

パラメータ

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

マルチキャスト グループに参加し、そのグループからパケットの受信を開始します。このメソッドを呼び出す前に、ソケットをローカルポートにバインドする必要があります。

パラメータ

  • socketId

    数値

    ソケット ID。

  • 住所

    文字列

    参加するグループのアドレス。ドメイン名はサポートされていません。

  • callback

    関数

    callback パラメータは次のようになります。 

    (result: number) => void

    • 件の結果

      数値

      基盤となるネットワーク呼び出しから返された結果コード。負の値はエラーを示します。

leaveGroup()

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

以前に joinGroup を使用して参加したマルチキャスト グループから離脱します。これは、ソケットが閉じられると OS によって自動的に行われるため、その後もソケットを使用し続ける場合にのみ呼び出す必要があります。

グループから離脱すると、ルーターはマルチキャスト データグラムをローカルホストに送信しなくなります。ただし、ホスト上の他のプロセスがグループに参加していないことが前提となります。

パラメータ

  • socketId

    数値

    ソケット ID。

  • 住所

    文字列

    退会するグループのアドレス。ドメイン名はサポートされていません。

  • callback

    関数

    callback パラメータは次のようになります。 

    (result: number) => void

    • 件の結果

      数値

      基盤となるネットワーク呼び出しから返された結果コード。負の値はエラーを示します。

send()

chrome.sockets.udp.send(
  socketId: number,
  data: ArrayBuffer,
  address: string,
  port: number,
  dnsQueryType?: DnsQueryType,
  callback: function,
): void

指定されたソケットのデータを指定されたアドレスとポートに送信します。このメソッドを呼び出す前に、ソケットをローカルポートにバインドする必要があります。

パラメータ

  • socketId

    数値

    ソケット ID。

  • データ

    ArrayBuffer

    送信するデータ。

  • 住所

    文字列

    リモートマシンのアドレス。

  • ポート

    数値

    リモートマシンのポート。

  • dnsQueryType

    DnsQueryType 省略可

    Chrome 103 以降

    アドレス解決の設定。

  • callback

    関数

    callback パラメータは次のようになります。 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      send メソッドの結果。

setBroadcast()

Chrome 44 以降 
chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
): void

このソケットでブロードキャスト パケットを有効または無効にします。

パラメータ

  • socketId

    数値

    ソケット ID。

  • 有効

    ブール値

    true: ブロードキャスト パケットを有効にします。false: ブロードキャスト パケットを無効にします。

  • callback

    関数

    callback パラメータは次のようになります。 

    (result: number) => void

    • 件の結果

      数値

      基盤となるネットワーク呼び出しから返された結果コード。

setMulticastLoopbackMode()

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

ホストからマルチキャスト グループに送信されたマルチキャスト パケットをホストにループバックするかどうかを設定します。

注: setMulticastLoopbackMode の動作は、Windows と Unix 系のシステムで若干異なります。この不整合は、同じホスト上の複数のアプリケーションが同じマルチキャスト グループに参加し、マルチキャスト ループバック モードの設定が異なる場合にのみ発生します。Windows では、ループバックがオフになっているアプリケーションはループバック パケットを受信しません。一方、Unix ライクなシステムでは、ループバックがオフになっているアプリケーションは、同じホスト上の他のアプリケーションにループバック パケットを送信しません。MSDN（https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2）をご覧ください。

このメソッドを呼び出すためにマルチキャスト権限は必要ありません。

パラメータ

  • socketId

    数値

    ソケット ID。

  • 有効

    ブール値

    ループバック モードを有効にするかどうかを指定します。

  • callback

    関数

    callback パラメータは次のようになります。 

    (result: number) => void

    • 件の結果

      数値

      基盤となるネットワーク呼び出しから返された結果コード。負の値はエラーを示します。

setMulticastTimeToLive()

chrome.sockets.udp.setMulticastTimeToLive(
  socketId: number,
  ttl: number,
  callback: function,
): void

マルチキャスト グループに送信されるマルチキャスト パケットの有効期間を設定します。

このメソッドを呼び出すためにマルチキャスト権限は必要ありません。

パラメータ

  • socketId

    数値

    ソケット ID。

  • ttl

    数値

    有効期間の値。

  • callback

    関数

    callback パラメータは次のようになります。 

    (result: number) => void

    • 件の結果

      数値

      基盤となるネットワーク呼び出しから返された結果コード。負の値はエラーを示します。

setPaused()

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

ソケットを一時停止または一時停止解除します。一時停止されたソケットは、onReceive イベントを発生させることができません。

パラメータ

  • socketId

    数値

    ソケット ID。

  • 一時停止

    ブール値

    一時停止するか一時停止を解除するかを示すフラグ。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 121 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

update()

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

ソケットのプロパティを更新します。

パラメータ

  • socketId

    数値

    ソケット ID。

  • プロパティ

    SocketProperties

    更新するプロパティ。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 121 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

イベント

onReceive

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

指定されたソケットで UDP パケットが受信されたときに発生するイベント。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (info: ReceiveInfo) => void

onReceiveError

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

ランタイムがソケットのアドレスとポートでデータを待機しているときにネットワーク エラーが発生した場合に発生するイベント。このイベントが発生すると、ソケットは一時停止され、ソケットが再開されるまで、このソケットに対して onReceive イベントは発生しません。

パラメータ