Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: add added: information for dgram #8196

Closed
wants to merge 1 commit into from
Closed

doc: add added: information for dgram #8196

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions doc/api/dgram.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@ server.bind(41234);
```

## Class: dgram.Socket
<!-- YAML
added: v0.1.99
-->

The `dgram.Socket` object is an [`EventEmitter`][] that encapsulates the
datagram functionality.
Expand All @@ -37,23 +40,35 @@ New instances of `dgram.Socket` are created using [`dgram.createSocket()`][].
The `new` keyword is not to be used to create `dgram.Socket` instances.

### Event: 'close'
<!-- YAML
added: v0.1.99
-->

The `'close'` event is emitted after a socket is closed with [`close()`][].
Once triggered, no new `'message'` events will be emitted on this socket.

### Event: 'error'
<!-- YAML
added: v0.1.99
-->

* `exception` {Error}

The `'error'` event is emitted whenever any error occurs. The event handler
function is passed a single Error object.

### Event: 'listening'
<!-- YAML
added: v0.1.99
-->

The `'listening'` event is emitted whenever a socket begins listening for
datagram messages. This occurs as soon as UDP sockets are created.

### Event: 'message'
<!-- YAML
added: v0.1.99
-->

* `msg` {Buffer} - The message
* `rinfo` {Object} - Remote address information
Expand Down Expand Up @@ -85,12 +100,18 @@ one interface and will add membership to it. To add membership to every
available interface, call `addMembership` multiple times, once per interface.

### socket.address()
<!-- YAML
added: v0.1.99
-->

Returns an object containing the address information for a socket.
For UDP sockets, this object will contain `address`, `family` and `port`
properties.

### socket.bind([port][, address][, callback])
<!-- YAML
added: v0.1.99
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The callback argument was actually added in version 0.9.1. I'm not sure what version to use.
There are other inconsistencies like this below.

Copy link
Contributor

@yorkie yorkie Aug 20, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be noted as updated: v0.9.1 even thought we have not that option :-(

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC, we have not documenting when an argument or something like a property in an options object is added.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, we don't currently document changes well. It'd be nice if we had per-function changelogs, like PHP.

-->

* `port` {Number} - Integer, Optional
* `address` {String}, Optional
Expand Down Expand Up @@ -139,6 +160,9 @@ server.bind(41234);
```

### socket.bind(options[, callback])
<!-- YAML
added: v0.11.14
-->

* `options` {Object} - Required. Supports the following properties:
* `port` {Number} - Required.
Expand Down Expand Up @@ -172,6 +196,9 @@ socket.bind({
```

### socket.close([callback])
<!-- YAML
added: v0.1.99
-->

Close the underlying socket and stop listening for data on it. If a callback is
provided, it is added as a listener for the [`'close'`][] event.
Expand All @@ -193,6 +220,9 @@ If `multicastInterface` is not specified, the operating system will attempt to
drop membership on all valid interfaces.

### socket.send(msg, [offset, length,] port, address[, callback])
<!-- YAML
added: v0.1.99
-->

* `msg` {Buffer|String|Array} Message to be sent
* `offset` {Number} Integer. Optional. Offset in the buffer where the message starts.
Expand Down Expand Up @@ -300,13 +330,19 @@ Sets or clears the `SO_BROADCAST` socket option. When set to `true`, UDP
packets may be sent to a local interface's broadcast address.

### socket.setMulticastLoopback(flag)
<!-- YAML
added: v0.3.8
-->

* `flag` {Boolean}

Sets or clears the `IP_MULTICAST_LOOP` socket option. When set to `true`,
multicast packets will also be received on the local interface.

### socket.setMulticastTTL(ttl)
<!-- YAML
added: v0.3.8
-->

* `ttl` {Number} Integer

Expand All @@ -320,6 +356,9 @@ The argument passed to to `socket.setMulticastTTL()` is a number of hops
between 0 and 255. The default on most systems is `1` but can vary.

### socket.setTTL(ttl)
<!-- YAML
added: v0.1.101
-->

* `ttl` {Number} Integer

Expand All @@ -333,6 +372,9 @@ The argument to `socket.setTTL()` is a number of hops between 1 and 255.
The default on most systems is 64 but can vary.

### socket.ref()
<!-- YAML
added: v0.9.1
-->

By default, binding a socket will cause it to block the Node.js process from
exiting as long as the socket is open. The `socket.unref()` method can be used
Expand All @@ -346,6 +388,9 @@ The `socket.ref()` method returns a reference to the socket so calls can be
chained.

### socket.unref()
<!-- YAML
added: v0.9.1
-->

By default, binding a socket will cause it to block the Node.js process from
exiting as long as the socket is open. The `socket.unref()` method can be used
Expand Down Expand Up @@ -383,6 +428,9 @@ s.bind(1234, () => {
## `dgram` module functions

### dgram.createSocket(options[, callback])
<!-- YAML
added: v0.11.13
-->

* `options` {Object}
* `callback` {Function} Attached as a listener to `'message'` events.
Expand All @@ -405,6 +453,9 @@ and `udp6` sockets). The bound address and port can be retrieved using
[`socket.address().address`][] and [`socket.address().port`][].

### dgram.createSocket(type[, callback])
<!-- YAML
added: v0.1.99
-->

* `type` {String} - Either 'udp4' or 'udp6'
* `callback` {Function} - Attached as a listener to `'message'` events.
Expand Down