diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index 92bf993d486ef2..1a914920ab8ef7 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -4,16 +4,30 @@ + +データグラムソケットは `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() { @@ -23,11 +37,19 @@ You have to change it to this: ## 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` で取得することができます。 ## dgram.createSocket(options[, callback]) + + +* `options` Object +* `callback` Function. `'message'` イベントのリスナとして割り当てられる。 +* Returns: Socket object + + +`options` オブジェクトは `udp4` か `udp6` のいずれかの `type` フィールドを含む必要があります。そして、boolean値である `reuseAddr` フィールドを任意で含みます。 + +`reuseAddr` が true の時には、 `socket.bind()` は他のプロセスが既にソケットをバインドしていたとしても、アドレスを再利用します。 `reuseAddr` の初期値は `false` です。 + +オプションのコールバックは `message` イベントのリスナーとして加えられます。 + +データグラムを受信したい場合は `socket.bind()` を呼び出します。 +`socket.bind()` は「全てのインタフェース」のアドレスにランダムなポート +(`udp4` と `udp6` ソケットの両方で正しいものです) をバインドします。 +そのアドレスとポートは `socket.address().address` および +`socket.address().port` で取得することができます。 + ## Class: dgram.Socket + + +dgram Scoket クラスはデータグラム機能をカプセル化します。 +それは `dgram.createSocket(...)` を通じて生成されます。 ### 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', @@ -77,51 +147,111 @@ Emitted when a new datagram is available on a socket. `msg` is a `Buffer` and ### Event: 'listening' + + +ソケットでデータグラムの待ち受けを開始すると生成されます。 +これは UDP ソケットが作成されるとすぐに発生します。 ### Event: 'close' + + +`close()` によってソケットがクローズされた後に生成されます。 +このソケットでは新しい `message` イベントは生成されなくなります。 ### Event: 'error' * `exception` Error object + + +エラーが発生すると生成されます。 ### 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` は文字の位置ではなく、 +[バイト位置](buffer.html#buffer_class_method_buffer_bytelength_string_encoding) +に関係します。 + + +`localhost` の適当なポートに UDP パケットを送信する例; var dgram = require('dgram'); var message = new Buffer("Some bytes"); @@ -130,6 +260,7 @@ Example of sending a UDP packet to a random port on `localhost`; 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` の両方を指定しても有害ではありませんが +あまり役には立ちません。 + + + +束縛されたデータグラムソケットはデータグラムを受信するために io.js プロセスの +実行を維持し続けます。 + +バインディングが失敗すると、`'error'` イベントが生成されます。 +まれなケース (たとえばクローズしたソケットへのバインディング) では、 +このメソッドは `Error` をスローすることがあります。 + + + +41234 番ポートを待ち受ける UDP サーバの例: var dgram = require("dgram"); @@ -204,22 +397,37 @@ Example of a UDP server listening on port 41234: ### socket.bind(options[, callback]) + + +* `options` {Object} - 必須です。以下のプロパティをサポートします。: + * `port` {Number} - 必須です。 + * `address` {String} - 任意です。 + * `exclusive` {Boolean} - 任意です。 +* `callback` {Function} - 任意です。 + +`options` の `port` と `address` プロパティと任意の callback function は [socket.bind(port, \[address\], \[callback\]) の呼び出しと同様の動きをします。 +](#dgram_socket_bind_port_address_callback) + +`exclusive` が `false` (デフォルト)の場合は複数のワーカーは下層の同じハンドルを使用します。接続のハンドルを共有することを許容します。 `exclusive` が `true` の場合は、ハンドルは共有されず、ポートを共有しようとするとエラーになります。以下は占有したポートを待ち受ける例です。 socket.bind({ address: 'localhost', @@ -230,38 +438,65 @@ shown below. ### socket.close([callback]) + +下層のソケットをクローズし、データの待ち受けを終了します。コールバックが与えられた場合は、 ['close'](#dgram_event_close) イベントのリスナーとして加えられます。 + ### socket.address() + + +オブジェクトが持っているソケットのアドレス情報を返します。 +このオブジェクトは `address`、`port`、そして `family` を持っています。 ### socket.setBroadcast(flag) * `flag` Boolean + + +ソケットのオプション `SO_BROADCAST` を設定またはクリアします。 +このオプションが設定されると、UDP パケットはローカルインタフェースのブロードキャスト用アドレスに送信されます。 ### socket.setTTL(ttl) * `ttl` Integer + + +ソケットオプションの `IP_TTL` を設定します。 +TTL は「生存期間」を表しますが、このコンテキストではパケットが通過を許可される IP のホップ数を指定します。 +各ルータまたはゲートウェイはパケットを送出する際 TTL をデクリメントします。 +ルータによって TTL がデクリメントされて 0 になるとそれは送出されません。 +TTL 値の変更は通常、ネットワークの調査やマルチキャストで使われます。 + + +`setTTL()` の引数は 1 から 255 のホップ数でです。ほとんどのシステムでデフォルトは 64 です。 ### socket.setMulticastTTL(ttl) * `ttl` Integer + + +`IP_MULTICAST_TTL` ソケットオプションを設定します。 +TTL は「生存期間」を表しますが、この文脈では特にマルチキャストのトラフィックにおいてパケットが通過できるIPホップの数を指定します。 +それぞれのルーターまたはゲートウェイは、パケットを転送する際に TTL をデクリメントします。 +TTL がルーターによって 0 までデクリメントされると、それは転送されません。 +`setMulticastTTL()` の引数はホップを表す数値で、0 から 255 の間です。 +ほとんどのシステムでデフォルトは 1 です。 ### socket.setMulticastLoopback(flag) * `flag` Boolean + + +`IP_MULTICAST_LOOP` ソケットオプションを設定またはクリアします。 +このオプションが設定されると、マルチキャストのパケットはローカルインタフェースでも受信できるようになります。 ### socket.addMembership(multicastAddress[, multicastInterface]) * `multicastAddress` String * `multicastInterface` String, Optional + + +`IP_ADD_MEMBERSHIP` ソケットオプションを設定し、マルチキャストグループに参加することをカーネルに伝えます。 + +`multicastInterface` が指定されなかった場合は、全ての妥当なインタフェースをメンバーシップに加えようとします。 ### socket.dropMembership(multicastAddress[, multicastInterface]) * `multicastAddress` String * `multicastInterface` String, Optional + + +`addMembership` の反対です - `IP_DROP_MEMBERSHIP` ソケットオプションによって、マルチキャストグループから抜けることをカーネルに伝えます。 +これはソケットのクローズ時やプロセスの終了時にカーネルによって自動的に呼び出されるため、ほとんどのアプリケーションはこれを呼び出す必要がありません。 + +`multicastInterface` が指定されなかった場合は、全ての妥当なインタフェースをメンバーシップから削除しようとします。 ### socket.unref() + + +イベントシステムにおいて、このソケットだけがアクティブな場合にプログラムを +終了することができるように、`unref` を呼び出します。 +既に `unref` されたソケットで再び `unref` が呼び出されても影響はありません。 ### socket.ref() + + +`unref` とは逆に、以前に `unref` されたソケットが唯一残ったソケットになっても、 +プログラムが終了 (デフォルトの動作です) しないように、`ref` を呼び出します。 +既に `ref` されたソケットで再び `ref` が呼び出されても影響はありません。 \ No newline at end of file