From 9456cf8fe2b42ccfb2a9561cd50430e623bdc6d2 Mon Sep 17 00:00:00 2001 From: Duan Yao Date: Tue, 4 Dec 2012 18:12:10 +0800 Subject: [PATCH] doc: Add callback parameter to dgram socket.bind() Also, describe more details of bind(). --- doc/api/dgram.markdown | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index bb102b9484b..5f8a0a8ccc6 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -127,13 +127,21 @@ informing the source that the data did not reach its intended recipient). * `port` Integer * `address` String, Optional -* `callback` Function, Optional +* `callback` Function with no parameters, Optional. Callback when + binding is done. -For UDP sockets, listen for datagrams on a named `port` and optional `address`. -If `address` is not specified, the OS will try to listen on all addresses. +For UDP sockets, listen for datagrams on a named `port` and optional +`address`. If `address` is not specified, the OS will try to listen on +all addresses. After binding is done, an "listening" event is emitted +and the `callback`(if specified) is called. Specifying both an +"listening" event listener and `callback` is not harmful but not very +useful. -The `callback` argument, if provided, is added as a one-shot `'listening'` -event listener. +A bound datagram socket keeps the node process running to receive +datagrams. + +If binding fails, an "error" event is generated. In rare case (e.g. +binding a closed socket), an `Error` may be thrown by this method. Example of a UDP server listening on port 41234: @@ -141,6 +149,11 @@ Example of a UDP server listening on port 41234: 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);