dgram: add support for UDP connected sockets · nodejs/node@9e96017 (original) (raw)

`@@ -49,6 +49,14 @@ added: v0.1.99

49

`` The 'close' event is emitted after a socket is closed with [close()][].

50

`` Once triggered, no new 'message' events will be emitted on this socket.

51

52

Event: 'connect'

53

56

+

57

`` +

The 'connect' event is emitted after a socket is associated to a remote

58

`` +

address as a result of a successful connect() call.

59

+

52

60

`### Event: 'error'

53

61

`<!-- YAML

54

62

`added: v0.1.99

`@@ -237,6 +245,34 @@ added: v0.1.99

237

245

`Close the underlying socket and stop listening for data on it. If a callback is

238

246

`` provided, it is added as a listener for the ['close'][] event.

239

247

248

socket.connect(port[, address][, callback])

249

252

+

253

`` +

port {integer}

254

`` +

address {string}

255

`` +

callback {Function} Called when the connection is completed or on error.

256

+

257

`` +

Associates the dgram.Socket to a remote address and port. Every

258

message sent by this handle is automatically sent to that destination. Also,

259

the socket will only receive messages from that remote peer.

260

`` +

Trying to call connect() on an already connected socket will result

261

`` +

in an ERR_SOCKET_DGRAM_IS_CONNECTED exception. If address is not

262

`` +

provided, '127.0.0.1' (for udp4 sockets) or '::1' (for udp6 sockets)

263

`` +

will be used by default. Once the connection is complete, a 'connect' event

264

`` +

is emitted and the optional callback function is called. In case of failure,

265

`` +

the callback is called or, failing this, an 'error' event is emitted.

266

+

267

socket.disconnect()

268

271

+

272

`` +

A synchronous function that disassociates a connected dgram.Socket from

273

`` +

its remote address. Trying to call disconnect() on an already disconnected

274

`` +

socket will result in an ERR_SOCKET_DGRAM_NOT_CONNECTED exception.

275

+

240

276

`### socket.dropMembership(multicastAddress[, multicastInterface])

241

277

`<!-- YAML

242

278

`added: v0.6.9

`` @@ -283,7 +319,18 @@ Calling socket.ref() multiples times will have no additional effect.

283

319

`` The socket.ref() method returns a reference to the socket so calls can be

284

320

`chained.

285

321

286

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

322

socket.remoteAddress()

323

326

+

327

Returns: {Object}

328

+

329

`` +

Returns an object containing the address, family, and port of the remote

330

`` +

endpoint. It throws an ERR_SOCKET_DGRAM_NOT_CONNECTED exception if the

331

socket is not connected.

332

+

333

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

287

334

`<!-- YAML

288

335

`added: v0.1.99

289

336

`changes:

`@@ -301,6 +348,9 @@ changes:

301

348

` pr-url: https://github.com/nodejs/node/pull/4374

302

349

`` description: The msg parameter can be an array now. Also, the offset

303

350

`` and length parameters are optional now.

351

version: REPLACEME

352

pr-url: https://github.com/nodejs/node/pull/26871

353

description: Added support for sending data on connected sockets.

304

354

`-->

305

355

306

356

`` * msg {Buffer|Uint8Array|string|Array} Message to be sent.

`@@ -310,8 +360,10 @@ changes:

310

360

`` * address {string} Destination hostname or IP address.

311

361

`` * callback {Function} Called when the message has been sent.

312

362

313

`` -

Broadcasts a datagram on the socket. The destination port and address must

314

be specified.

363

Broadcasts a datagram on the socket.

364

`` +

For connectionless sockets, the destination port and address must be

365

specified. Connected sockets, on the other hand, will use their associated

366

`` +

remote endpoint, so the port and address arguments must not be set.

315

367

316

368

`` The msg argument contains the message to be sent.

317

369

`` Depending on its type, different behavior can apply. If msg is a Buffer

`@@ -375,6 +427,20 @@ application and operating system. It is important to run benchmarks to

375

427

`determine the optimal strategy on a case-by-case basis. Generally speaking,

376

428

`however, sending multiple buffers is faster.

377

429

430

Example of sending a UDP packet using a socket connected to a port on

431

`` +

localhost:

432

+

433


```js

434

const dgram = require('dgram');

435

const message = Buffer.from('Some bytes');

436

const client = dgram.createSocket('udp4');

437

client.connect(41234, 'localhost', (err) => {

438

client.send(message, (err) => {

439

client.close();

440

});

441

});

442

```

443

+

378

444

`A Note about UDP datagram size

379

445

380

446

`` The maximum size of an IPv4/v6 datagram depends on the MTU

`` @@ -651,10 +717,13 @@ and udp6 sockets). The bound address and port can be retrieved using

651

717

652

718

`` ['close']: #dgram_event_close

653

719

`` [Error]: errors.html#errors_class_error

720

`` +

721

`` +

654

722

`` [EventEmitter]: events.html

655

723

`` [System Error]: errors.html#errors_class_systemerror

656

724

`` [close()]: #dgram_socket_close_callback

657

725

`` [cluster]: cluster.html

726

`` +

658

727

`` [dgram.Socket#bind()]: #dgram_socket_bind_options_callback

659

728

`` [dgram.createSocket()]: #dgram_dgram_createsocket_options_callback

660

729

`` [dns.lookup()]: dns.html#dns_dns_lookup_hostname_options_callback