Table of Contents

• UDP / Datagram Sockets
  • dgram.createSocket(type, [callback])
  • Class: dgram.Socket
    • Event: 'message'
    • Event: 'listening'
    • Event: 'close'
    • Event: 'error'
    • socket.send(buf, offset, length, port, address, [callback])
    • socket.bind(port, [address], [callback])
    • socket.close()
    • socket.address()
    • socket.setBroadcast(flag)
    • socket.setTTL(ttl)
    • socket.setMulticastTTL(ttl)
    • socket.setMulticastLoopback(flag)
    • socket.addMembership(multicastAddress, [multicastInterface])
    • socket.dropMembership(multicastAddress, [multicastInterface])
    • socket.unref()
    • socket.ref()

UDP / Datagram Sockets#

Stability: 3 - Stable

データグラムソケットは require('dgram') で利用可能になります。

重要な注意: dgram.Socket#bind() の振る舞いは v0.10 で変更され、 それは常に非同期になりました。 もし次のようなコードがあると:

var s = dgram.createSocket('udp4');
s.bind(1234);
s.addMembership('224.0.0.114');

これは次のように変更されなければなりません。

var s = dgram.createSocket('udp4');
s.bind(1234, function() {
  s.addMembership('224.0.0.114');
});

dgram.createSocket(type, [callback])#

• type String. 'udp4' または 'udp6' のいずれか
• callback Function. 'message' イベントのリスナとして割り当てられる、 Optional
• Returns: Socket object

指定された種類のデータグラムソケットを作成します。 妥当な種類は udp4 と udp6です。

オプションのコールバックは message イベントのリスナーとして加えられます。

データグラムを受信したい場合は socket.bind() を呼び出します。 socket.bind() は「全てのインタフェース」のアドレスにランダムなポート (udp4 と udp6 ソケットの両方で正しいものです) をバインドします。 そのアドレスとポートは socket.address().address および socket.address().port で取得することができます。

Class: dgram.Socket#

dgram Scoket クラスはデータグラム機能をカプセル化します。 それは dgram.createSocket(type, [callback]) を通じて生成されます。

Event: 'message'#

• msg Buffer object. メッセージ
• rinfo Object. リモートアドレスの情報

ソケット上で新しいデータグラムが到着した時に生成されます。 msg は Buffer で、rinfo は送信者のアドレス情報を持ったオブジェクトです。

socket.on('message', function(msg, rinfo) {
  console.log('Received %d bytes from %s:%d\n',
              msg.length, rinfo.address, rinfo.port);
});

Event: 'listening'#

ソケットでデータグラムの待ち受けを開始すると生成されます。 これは UDP ソケットが作成されるとすぐに発生します。

Event: 'close'#

close() によってソケットがクローズすると生成されます。 このソケットでは新しい message イベントは生成されなくなります。

Event: 'error'#

エラーが発生すると生成されます。

socket.send(buf, offset, length, port, address, [callback])#

• buf Buffer オブジェクトまたは文字列。送信されるメッセージ
• offset Integer。メッセージの開始位置となるバッファ内のオフセット
• length Integer。メッセージのバイト長
• port 整数。接続先のポート番号。
• address 文字列。接続先のホスト名または IP アドレス。
• callback 関数。メッセージが送信されるとコールバックされる。任意。

UDP ソケットに対しては、相手先のポートとアドレスは必ず指定しなければなりません。 address パラメータに文字列を提供すると、それは DNS によって解決されます。

アドレスが省略された場合や空文字列だった場合は、代わりに '0.0.0.0' または '::0' が使われます。ネットワークの構成によっては、これらのデフォルト値は 動作したりしなかったりします; 相手先のアドレスは明示的に指定することが最適です。

ソケットが以前に bind の呼び出しによってバインドされていない場合は、 ランダムなポート番号が「全てのインタフェース」アドレスに対してバインドされます (udp4 ソケットでは 0.0.0.0、udp6 では ::0)。

DNS におけるエラー検出と、buf が再利用可能になったことを安全に知るために、 オプションのコールバックを指定することができます。 DNS ルックアップは送信を少なくとも次のイベントループまで遅らせることに 注意してください。 データグラムの送信が行われたことを確実に知る唯一の手段は、 コールバックを使うことです。

マルチバイト文字を考慮してください。 offset および length は文字の位置ではなく、 バイト位置 に関係します。

localhost の適当なポートに UDP パケットを送信する例;

var dgram = require('dgram');
var message = new Buffer("Some bytes");
var client = dgram.createSocket("udp4");
client.send(message, 0, message.length, 41234, "localhost", function(err) {
  client.close();
});

UDP データグラムのサイズについて

IPv4/v6 データグラムの最大のサイズは MTU (Maximum Transmission Unit) と、 Payload Length フィールドサイズに依存します。

• Payload Length フィールドサイズは 16bit 長で、これは通常のペイロードが IP ヘッダとデータ含めて 64K オクテットより長くなれないことを意味します (65,507 バイト = 65,535 − 8 バイトの UDP ヘッダ − 20 バイトの IP ヘッダ); これは一般的にループバックインタフェースでは正しいものの、 ほとんどのホストとネットワークにとって長大なデータグラムは 現実的ではありません。

• MTU はリンク層により大きなサイズを与える技術で、 データグラムもサポートできます。 どんなリンクでも、それらが全体として到着するか断片化されるかに関わらず、 IPv4 は最低 69 オクテット必要で、推奨される IPv4 の MTU は 576 です (典型的なダイヤルアップ型アプリケーションの MUT 推奨値)。

  IPv6 では最小の MTU は 1280 オクテットですが、フラグメントを再構築する バッファサイズは最低 1500 オクテットが必要です。 68 オクテットはとても小さいので、もっとも現代的なリンク層技術では、 最小の MTU は 1500 です (イーサネットと同じです)。

パケットが通過する各リンクの MTU をあらかじめ知ることは できないこと、(受信側の) MTU より大きなデータグラムを送信しても 通常は動作しないことに注意してください (パケットは送り主に知らされることなく黙って捨てられ、 意図した受信者に到達することはありません)。

socket.bind(port, [address], [callback])#

• port Integer
• address String、任意
• callback 引数のない関数、任意。バインディングが終了した時に コールバックされます。

UDP ソケット用です。port とオプションの address でデータグラムを 待ち受けます。 address が指定されなければ、OS は全てのアドレスからの待ち受けを試みます。 バインディングが完了すると、'listening' イベントが生成され、 (もし指定されていれば) callback が呼び出されます。 'listening' イベントリスナと callback の両方を指定しても有害ではありませんが あまり役には立ちません。

束縛されたデータグラムソケットはデータグラムを受信するために node プロセスの 実行を維持し続けます。

バインディングが失敗すると、'error' イベントが生成されます。 まれなケース (たとえばクローズしたソケットへのバインディング) では、 このメソッドは Error をスローすることがあります。

41234 番ポートを待ち受ける UDP サーバの例:

var dgram = require("dgram");

var server = dgram.createSocket("udp4");

server.on("error", function (err) {
  console.log("server error:\n" + err.stack);
  server.close();
});

server.on("message", function (msg, rinfo) {
  console.log("server got: " + msg + " from " +
    rinfo.address + ":" + rinfo.port);
});

server.on("listening", function () {
  var address = server.address();
  console.log("server listening " +
      address.address + ":" + address.port);
});

server.bind(41234);
// server listening 0.0.0.0:41234

socket.close()#

下層のソケットをクローズし、データの待ち受けを終了します。

socket.address()#

オブジェクトが持っているソケットのアドレス情報を返します。 このオブジェクトは address、port、そして family を持っています。

socket.setBroadcast(flag)#

ソケットのオプション SO_BROADCAST を設定またはクリアします。 このオプションが設定されると、UDP パケットはローカルインタフェースのブロードキャスト用アドレスに送信されます。

socket.setTTL(ttl)#

ソケットオプションの IP_TTL を設定します。 TTL は「生存期間」を表しますが、このコンテキストではパケットが通過を許可される IP のホップ数を指定します。 各ルータまたはゲートウェイはパケットを送出する際 TTL をデクリメントします。 ルータによって TTL がデクリメントされて 0 になるとそれは送出されません。 TTL 値の変更は通常、ネットワークの調査やマルチキャストで使われます。

setTTL() の引数は 1 から 255 のホップ数でです。ほとんどのシステムでデフォルトは 64 です。

socket.setMulticastTTL(ttl)#

IP_MULTICAST_TTL ソケットオプションを設定します。 TTL は「生存期間」を表しますが、この文脈では特にマルチキャストのトラフィックにおいてパケットが通過できるIPホップの数を指定します。 それぞれのルーターまたはゲートウェイは、パケットを転送する際に TTL をデクリメントします。 TTL がルーターによって 0 までデクリメントされると、それは転送されません。 setMulticastTTL() の引数はホップを表す数値で、0 から 255 の間です。 ほとんどのシステムでデフォルトは 1 です。

socket.setMulticastLoopback(flag)#

IP_MULTICAST_LOOP ソケットオプションを設定またはクリアします。 このオプションが設定されると、マルチキャストのパケットはローカルインタフェースでも受信できるようになります。

socket.addMembership(multicastAddress, [multicastInterface])#

IP_ADD_MEMBERSHIP ソケットオプションを設定し、マルチキャストグループに参加することをカーネルに伝えます。

multicastInterface が指定されなかった場合は、全ての妥当なインタフェースをメンバーシップに加えようとします。

socket.dropMembership(multicastAddress, [multicastInterface])#

addMembership の反対です - IP_DROP_MEMBERSHIP ソケットオプションによって、マルチキャストグループから抜けることをカーネルに伝えます。 これはソケットのクローズ時やプロセスの終了時にカーネルによって自動的に呼び出されるため、ほとんどのアプリケーションはこれを呼び出す必要がありません。

multicastInterface が指定されなかった場合は、全ての妥当なインタフェースをメンバーシップから削除しようとします。

socket.unref()#

イベントシステムにおいて、このソケットだけがアクティブな場合にプログラムを 終了することができるように、unref を呼び出します。 既に unref されたソケットで再び unref が呼び出されても影響はありません。

socket.ref()#

unref とは逆に、以前に unref されたソケットが唯一残ったソケットになっても、 プログラムが終了 (デフォルトの動作です) しないように、ref を呼び出します。 既に ref されたソケットで再び ref が呼び出されても影響はありません。