مقابس UDP/datagram

[مستقر: 2 - مستقر]

رمز المصدر: lib/dgram.js

يوفر نموذج node:dgram تنفيذاً لمقابس بيانات UDP.

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`خطأ في الخادم:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`الخادم حصل على: ${msg} من ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`الخادم يستمع على ${address.address}:${address.port}`)
})

server.bind(41234)
// يطبع: الخادم يستمع على 0.0.0.0:41234

const dgram = require('node:dgram')
const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`خطأ في الخادم:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`الخادم حصل على: ${msg} من ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`الخادم يستمع على ${address.address}:${address.port}`)
})

server.bind(41234)
// يطبع: الخادم يستمع على 0.0.0.0:41234

الصف: `dgram.Socket`

مضاف في: v0.1.99

يمتد: <EventEmitter>

يُغلف وظائف البيانات.

يتم إنشاء مثيلات جديدة من dgram.Socket باستخدام dgram.createSocket(). لا يجب استخدام كلمة new لإنشاء مثيلات dgram.Socket.

الحدث: `'close'`

مضاف في: v0.1.99

يتم إصدار حدث 'close' بعد إغلاق مقبس باستخدام close(). بمجرد تشغيله، لن يتم إصدار أحداث 'message' جديدة على هذا المقبس.

الحدث: `'connect'`

مضاف في: v12.0.0

يتم إصدار حدث 'connect' بعد ربط مقبس بعنوان بعيد نتيجة لنجاح مكالمة connect().

حدث: `'error'`

مضاف في: v0.1.99

exception <Error>

يُصدر حدث 'error' كلما حدث أي خطأ. تُمرر دالة مُعالِج الحدث كائن Error واحدًا.

حدث: `'listening'`

مضاف في: v0.1.99

يُصدر حدث 'listening' بمجرد أن يصبح dgram.Socket قابلاً للوصول إليه ويمكنه استقبال البيانات. يحدث هذا إما بشكلٍ صريحٍ باستخدام socket.bind() أو ضمناً في المرة الأولى التي تُرسل فيها البيانات باستخدام socket.send(). حتى يستمع dgram.Socket، لا توجد موارد النظام الأساسية، وستفشل المكالمات مثل socket.address() و socket.setTTL().

حدث: `'message'`

[السجل]

الإصدار	التغييرات
v18.4.0	تُعيد خاصية `family` الآن سلسلةً بدلاً من رقم.
v18.0.0	تُعيد خاصية `family` الآن رقمًا بدلاً من سلسلة.
v0.1.99	مضاف في: v0.1.99

يُصدر حدث 'message' عندما تتوفر بيانات جديدة على مقبس. تُمرر دالة مُعالِج الحدث حُجتين: msg و rinfo.

msg <Buffer> الرسالة.
rinfo <Object> معلومات عنوان المُرسِل البعيد.
- address <string> عنوان المُرسِل.
- family <string> عائلة العنوان ('IPv4' أو 'IPv6').
- port <number> منفذ المُرسِل.
- size <number> حجم الرسالة.

إذا كان عنوان المصدر للحزمة الواردة هو عنوان ارتباط محلي IPv6، فسيتم إضافة اسم الواجهة إلى address. على سبيل المثال، قد يكون لحزمة تم استلامها على واجهة en0 حقل عنوان مُعيّن لـ 'fe80::2618:1234:ab11:3b9c%en0'، حيث '%en0' هو اسم الواجهة كلاحقة معرف المنطقة.

`socket.addMembership(multicastAddress[, multicastInterface])`

أضيف في: v0.6.9

multicastAddress <string>
multicastInterface <string>

يُخبر النظام الأساسي بالانضمام إلى مجموعة بث متعدد في multicastAddress و multicastInterface المُعطاة باستخدام خيار المقبس IP_ADD_MEMBERSHIP. إذا لم يتم تحديد وسيطة multicastInterface, فسوف يختار نظام التشغيل واجهة واحدة ويضيف العضوية إليها. لإضافة العضوية إلى كل واجهة متاحة، اتصل بـ addMembership عدة مرات، مرة واحدة لكل واجهة.

عند استدعائه على مقبس غير مرتبط، ستقوم هذه الطريقة ضمنيًا بربط منفذ عشوائي، والاستماع على جميع الواجهات.

عند مشاركة مقبس UDP عبر العديد من عمال cluster، يجب استدعاء دالة socket.addMembership() مرة واحدة فقط، وإلا فسوف يحدث خطأ EADDRINUSE:

ESMCJS

import cluster from 'node:cluster'
import dgram from 'node:dgram'

if (cluster.isPrimary) {
  cluster.fork() // يعمل بشكل جيد.
  cluster.fork() // يفشل مع EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

const cluster = require('node:cluster')
const dgram = require('node:dgram')

if (cluster.isPrimary) {
  cluster.fork() // يعمل بشكل جيد.
  cluster.fork() // يفشل مع EADDRINUSE.
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

`socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

أضيف في: v13.1.0، v12.16.0

sourceAddress <string>
groupAddress <string>
multicastInterface <string>

يُخبر النظام الأساسي بالانضمام إلى قناة بث متعدد محددة المصدر في sourceAddress و groupAddress المُعطاة، باستخدام multicastInterface مع خيار المقبس IP_ADD_SOURCE_MEMBERSHIP. إذا لم يتم تحديد وسيطة multicastInterface, فسوف يختار نظام التشغيل واجهة واحدة ويضيف العضوية إليها. لإضافة العضوية إلى كل واجهة متاحة، اتصل بـ socket.addSourceSpecificMembership() عدة مرات، مرة واحدة لكل واجهة.

عند استدعائه على مقبس غير مرتبط، ستقوم هذه الطريقة ضمنيًا بربط منفذ عشوائي، والاستماع على جميع الواجهات.

`socket.address()`

مضاف في: v0.1.99

مُخرجات: <Object>

يُرجع كائنًا يحتوي على معلومات عنوان المقبس. بالنسبة لمقابس UDP، سيحتوي هذا الكائن على خصائص address و family و port.

تُلقي هذه الطريقة خطأ EBADF إذا تم استدعاؤها على مقبس غير مرتبط.

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

[السجل]

الإصدار	التغييرات
v0.9.1	تم تغيير الأسلوب إلى نموذج تنفيذ غير متزامن. ستحتاج التعليمات البرمجية القديمة إلى تغييرها لإرسال دالة مُعامل إلى مُكالمة الأسلوب.
v0.1.99	مضاف في: v0.1.99

port <integer>
address <string>
callback <Function> بدون معلمات. يتم استدعاؤها عند اكتمال الارتباط.

بالنسبة لمقابس UDP، يتسبب في استماع dgram.Socket لرسائل البيانات على port مُسَمّى وaddress اختياري. إذا لم يتم تحديد port أو كان 0، فسيحاول نظام التشغيل الارتباط بمنفذ عشوائي. إذا لم يتم تحديد address، فسيحاول نظام التشغيل الاستماع على جميع العناوين. بمجرد اكتمال الارتباط، يتم إصدار حدث 'listening' ويتم استدعاء دالة callback الاختيارية.

إن تحديد كل من مُستمع حدث 'listening' وإرسال callback إلى أسلوب socket.bind() ليس ضارًا ولكنه ليس مفيدًا جدًا.

يُبقي مقبس البيانات المُرتبط عملية Node.js قيد التشغيل لتلقي رسائل البيانات.

إذا فشل الارتباط، فسيتم إنشاء حدث 'error' . في حالة نادرة (مثل محاولة الارتباط بمقبس مغلق)، قد يتم إلقاء خطأ Error.

مثال لخادم UDP يستمع على المنفذ 41234:

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`خطأ الخادم:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`الخادم حصل على: ${msg} من ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`الخادم يستمع على ${address.address}:${address.port}`)
})

server.bind(41234)
// يُطبع: الخادم يستمع على 0.0.0.0:41234

const dgram = require('node:dgram')
const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`خطأ الخادم:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`الخادم حصل على: ${msg} من ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`الخادم يستمع على ${address.address}:${address.port}`)
})

server.bind(41234)
// يُطبع: الخادم يستمع على 0.0.0.0:41234

`socket.bind(options[, callback])`

مضاف في: v0.11.14

options <Object> مطلوب. يدعم الخصائص التالية:
- port <integer>
- address <string>
- exclusive <boolean>
- fd <integer>
callback <Function>

بالنسبة لمقابس UDP، يتسبب ذلك في استماع dgram.Socket إلى رسائل البيانات على port باسم وعنوان اختياري address يتم تمريرهما كخصائص لكائن options الذي يتم تمريره كحجة أولى. إذا لم يتم تحديد port أو كان 0، فسيحاول نظام التشغيل الارتباط بمنفذ عشوائي. إذا لم يتم تحديد address، فسيحاول نظام التشغيل الاستماع على جميع العناوين. بمجرد اكتمال الربط، يتم إصدار حدث 'listening' ويتم استدعاء دالة callback الاختيارية.

قد يحتوي كائن options على خاصية fd. عندما يتم تعيين fd أكبر من 0، فسيتم لفها حول مقبس موجود باستخدام مُعرّف الملف المعطى. في هذه الحالة، سيتم تجاهل خصائص port و address.

تحديد كل من مُستمع حدث 'listening' وتمرير callback إلى طريقة socket.bind() ليس ضارًا ولكنه ليس مفيدًا جدًا.

قد يحتوي كائن options على خاصية exclusive إضافية تُستخدم عند استخدام كائنات dgram.Socket مع وحدة cluster. عندما يتم تعيين exclusive على false (الافتراضي)، سيستخدم عمال العنقود نفس مُقبض المقبس الأساسي مما يسمح بمشاركة واجبات معالجة الاتصال. ومع ذلك، عندما يكون exclusive هو true، لا يتم مشاركة المُقبض وتؤدي محاولة مشاركة المنفذ إلى حدوث خطأ. يؤدي إنشاء dgram.Socket مع خيار reusePort المُعيّن على true إلى جعل exclusive دائمًا true عند استدعاء socket.bind().

يُبقي مقبس البيانات المُرتبط عملية Node.js قيد التشغيل لتلقي رسائل البيانات.

إذا فشل الربط، فسيتم إنشاء حدث 'error' . في حالة نادرة (مثل محاولة الربط بمقبس مغلق)، قد يتم طرح Error.

يُظهر المثال التالي مقبسًا يستمع على منفذ حصري.

socket.bind({
  address: 'localhost',
  port: 8000,
  exclusive: true,
})

`socket.close([callback])`

مضاف في: v0.1.99

callback <Function> يتم استدعاء هذه الدالة عندما يتم إغلاق المقبس.

يقوم بإغلاق المقبس الأساسي ووقف الاستماع للبيانات عليه. إذا تم توفير دالة مُعاودة للاتصال، فسيتم إضافتها كمُستمع لحدث 'close'.

`socket[Symbol.asyncDispose]()`

مضاف في: v20.5.0, v18.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 ثبات: 1 - تجريبي

يقوم باستدعاء socket.close() ويعيد وعدًا يتم الوفاء به عندما يتم إغلاق المقبس.

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

مضاف في: v12.0.0

port <integer>
address <string>
callback <Function> يتم استدعاء هذه الدالة عند اكتمال الاتصال أو عند حدوث خطأ.

يربط dgram.Socket بعنوان و منفذ بعيدين. يتم إرسال كل رسالة يتم إرسالها بواسطة هذا المُعامل تلقائيًا إلى تلك الوجهة. أيضًا، سيتلقى المقبس الرسائل فقط من هذا النظير البعيد. سيؤدي محاولة استدعاء connect() على مقبس متصل بالفعل إلى استثناء ERR_SOCKET_DGRAM_IS_CONNECTED. إذا لم يتم توفير address، فسيتم استخدام '127.0.0.1' (للمقابس udp4) أو '::1' (للمقابس udp6) افتراضيًا. بمجرد اكتمال الاتصال، يتم إصدار حدث 'connect' ويتم استدعاء دالة callback الاختيارية. في حالة الفشل، يتم استدعاء callback، أو في حالة الفشل، يتم إصدار حدث 'error'.

`socket.disconnect()`

مضاف في: v12.0.0

دالة متزامنة تقوم بفك ارتباط dgram.Socket المتصل من عنوانه البعيد. سيؤدي محاولة استدعاء disconnect() على مقبس غير مرتبط أو مقبس تم فصله بالفعل إلى استثناء ERR_SOCKET_DGRAM_NOT_CONNECTED.

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

أضيف في: v0.6.9

multicastAddress <string>
multicastInterface <string>

يلقي تعليمات إلى نواة النظام لمغادرة مجموعة بث متعدد في multicastAddress باستخدام خيار مقبس IP_DROP_MEMBERSHIP. يتم استدعاء هذه الطريقة تلقائيًا بواسطة النواة عند إغلاق المقبس أو إنهاء العملية، لذلك لن يكون لدى معظم التطبيقات سبب لاستدعاء هذه الطريقة.

إذا لم يتم تحديد multicastInterface، فسيحاول نظام التشغيل إسقاط العضوية على جميع الواجهات الصالحة.

`socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

أضيف في: v13.1.0، v12.16.0

sourceAddress <string>
groupAddress <string>
multicastInterface <string>

يلقي تعليمات إلى نواة النظام لمغادرة قناة بث متعدد محددة المصدر في sourceAddress و groupAddress المعطاة باستخدام خيار مقبس IP_DROP_SOURCE_MEMBERSHIP. يتم استدعاء هذه الطريقة تلقائيًا بواسطة النواة عند إغلاق المقبس أو إنهاء العملية، لذلك لن يكون لدى معظم التطبيقات سبب لاستدعاء هذه الطريقة.

إذا لم يتم تحديد multicastInterface، فسيحاول نظام التشغيل إسقاط العضوية على جميع الواجهات الصالحة.

`socket.getRecvBufferSize()`

أضيف في: v8.7.0

الإرجاع: <number> حجم مُخزن مؤقت استقبال المقبس SO_RCVBUF بالبايت.

ترمي هذه الطريقة ERR_SOCKET_BUFFER_SIZE إذا تم استدعائها على مقبس غير مرتبط.

`socket.getSendBufferSize()`

أضيف في: v8.7.0

الإرجاع: <number> حجم مُخزن مؤقت إرسال المقبس SO_SNDBUF بالبايت.

ترمي هذه الطريقة ERR_SOCKET_BUFFER_SIZE إذا تم استدعائها على مقبس غير مرتبط.

`socket.getSendQueueSize()`

تم الإضافة في: v18.8.0، v16.19.0

مُخرجات: <number> عدد البايتات المُصطفة للإرسال.

`socket.getSendQueueCount()`

تم الإضافة في: v18.8.0، v16.19.0

مُخرجات: <number> عدد طلبات الإرسال الموجودة حاليًا في قائمة الانتظار في انتظار المعالجة.

`socket.ref()`

تم الإضافة في: v0.9.1

مُخرجات: <dgram.Socket>

بشكل افتراضي، سيؤدي ربط مقبس إلى منعه من إخراج عملية Node.js طالما أن المقبس مفتوح. يمكن استخدام طريقة socket.unref() لاستبعاد المقبس من عدّ المرجع الذي يحافظ على نشاط عملية Node.js. تضيف طريقة socket.ref() المقبس مرة أخرى إلى عدّ المرجع وتستعيد السلوك الافتراضي.

لن يكون لاستدعاء socket.ref() عدة مرات أي تأثير إضافي.

ترجع طريقة socket.ref() مرجعًا إلى المقبس حتى يمكن سلسلة المكالمات.

`socket.remoteAddress()`

تم الإضافة في: v12.0.0

مُخرجات: <Object>

يُرجع كائنًا يحتوي على address و family و port لنقطة النهاية البعيدة. تُلقي هذه الطريقة استثناءً ERR_SOCKET_DGRAM_NOT_CONNECTED إذا لم يكن المقبس متصلاً.

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

[السجل]

الإصدار	التغييرات
v17.0.0	معلمة `address` تقبل الآن سلسلة نصية فقط، أو `null` أو `undefined`.
v14.5.0، v12.19.0	يمكن أن تكون معلمة `msg` الآن أي `TypedArray` أو `DataView`.
v12.0.0	تم إضافة دعم لإرسال البيانات على المقابس المتصلة.
v8.0.0	يمكن أن تكون معلمة `msg` الآن `Uint8Array`.
v8.0.0	أصبحت معلمة `address` اختيارية دائمًا الآن.
v6.0.0	عند النجاح، سيتم استدعاء `callback` الآن مع وسيطة `error` تساوي `null` بدلاً من `0`.
v5.7.0	يمكن أن تكون معلمة `msg` الآن مصفوفة. أيضًا، أصبحت معلمات `offset` و `length` اختيارية الآن.
v0.1.99	تم الإضافة في: v0.1.99

msg <Buffer> | <TypedArray> | <DataView> | <string> | <Array> الرسالة المراد إرسالها.
offset <integer> الإزاحة في المخزن المؤقت حيث تبدأ الرسالة.
length <integer> عدد البايتات في الرسالة.
port <integer> منفذ الوجهة.
address <string> اسم المضيف أو عنوان IP للوجهة.
callback <Function> يتم استدعاؤه عند إرسال الرسالة.

يبث مخططًا بياناتيًا على المقبس. بالنسبة للمقابس غير المتصلة، يجب تحديد منفذ الوجهة وعنوانها. من ناحية أخرى، ستستخدم المقابس المتصلة نقطة النهاية البعيدة المرتبطة بها، لذلك يجب عدم تعيين وسيطات port و address.

تحتوي وسيطة msg على الرسالة المراد إرسالها. اعتمادًا على نوعها، يمكن تطبيق سلوك مختلف. إذا كانت msg عبارة عن Buffer، أو أي TypedArray أو DataView، فإن offset و length يُحددان الإزاحة داخل Buffer حيث تبدأ الرسالة وعدد البايتات في الرسالة، على التوالي. إذا كانت msg عبارة عن String، فسيتم تحويلها تلقائيًا إلى Buffer باستخدام ترميز 'utf8' . مع الرسائل التي تحتوي على أحرف متعددة البايتات، سيتم حساب offset و length فيما يتعلق بطول البايت وليس موضع الحرف. إذا كانت msg عبارة عن مصفوفة، يجب عدم تحديد offset و length.

وسيطة address هي سلسلة نصية. إذا كانت قيمة address هي اسم مضيف، فسيتم استخدام DNS لحل عنوان المضيف. إذا لم يتم توفير address أو كان قيمته nullish، فسيتم استخدام '127.0.0.1' (للمقابس udp4) أو '::1' (للمقابس udp6) افتراضيًا.

إذا لم يتم ربط المقبس مسبقًا باستدعاء إلى bind، فسيتم تعيين رقم منفذ عشوائي للمقبس ويتم ربطه بعنوان "جميع الواجهات" ('0.0.0.0' للمقابس udp4، '::0' للمقابس udp6).

يمكن تحديد دالة callback اختيارية كطريقة للإبلاغ عن أخطاء DNS أو لتحديد متى يكون من الآمن إعادة استخدام كائن buf. تؤخر عمليات بحث DNS وقت الإرسال لمدة دورة واحدة على الأقل من حلقة أحداث Node.js.

الطريقة الوحيدة للتأكد من أن مخطط البيانات قد تم إرساله هي استخدام callback. إذا حدث خطأ وتم إعطاء callback، فسيتم تمرير الخطأ كوسيطة أولى إلى callback. إذا لم يتم إعطاء callback، فسيتم إصدار الخطأ كحدث 'error' على كائن socket.

الإزاحة والطول اختياريان ولكن يجب تعيين كليهما إذا تم استخدام أحدهما. يتم دعمهما فقط عندما تكون الوسيطة الأولى Buffer أو TypedArray أو DataView.

تلقي هذه الطريقة استثناء ERR_SOCKET_BAD_PORT إذا تم استدعاؤها على مقبس غير مرتبط.

مثال على إرسال حزمة UDP إلى منفذ على localhost؛

ESMCJS

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.send(message, 41234, 'localhost', err => {
  client.close()
})

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.send(message, 41234, 'localhost', err => {
  client.close()
})

مثال على إرسال حزمة UDP مكونة من مخازن مؤقتة متعددة إلى منفذ على 127.0.0.1؛

ESMCJS

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const buf1 = Buffer.from('Some ')
const buf2 = Buffer.from('bytes')
const client = dgram.createSocket('udp4')
client.send([buf1, buf2], 41234, err => {
  client.close()
})

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const buf1 = Buffer.from('Some ')
const buf2 = Buffer.from('bytes')
const client = dgram.createSocket('udp4')
client.send([buf1, buf2], 41234, err => {
  client.close()
})

قد يكون إرسال مخازن مؤقتة متعددة أسرع أو أبطأ اعتمادًا على التطبيق ونظام التشغيل. قم بتشغيل المقاييس لتحديد الاستراتيجية المثلى على أساس كل حالة على حدة. بشكل عام، ومع ذلك، فإن إرسال مخازن مؤقتة متعددة يكون أسرع.

مثال على إرسال حزمة UDP باستخدام مقبس متصل بمنفذ على localhost:

ESMCJS

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.connect(41234, 'localhost', err => {
  client.send(message, err => {
    client.close()
  })
})

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.connect(41234, 'localhost', err => {
  client.send(message, err => {
    client.close()
  })
})

ملاحظة حول حجم البيانات في بروتوكول UDP

يعتمد الحجم الأقصى لبيانات بروتوكول IPv4/v6 على وحدة النقل القصوى (MTU) وحجم حقل Payload Length.

حقل Payload Length عرضه 16 بت، مما يعني أن حمولة البيانات العادية لا يمكن أن تتجاوز 64 كيلوبايت بما في ذلك رأس الإنترنت والبيانات (65,507 بايت = 65,535 - 8 بايت رأس UDP - 20 بايت رأس IP)؛ وهذا صحيح بشكل عام بالنسبة لواجهات الحلقة الخلفية، لكن مثل هذه الرسائل الطويلة من البيانات غير عملية بالنسبة لمعظم أجهزة الاستضافة والشبكات.
MTU هو أكبر حجم يمكن أن تدعمه تقنية طبقة الربط المعطاة لرسائل البيانات. بالنسبة لأي رابط، يفرض بروتوكول IPv4 الحد الأدنى لـ MTU وهو 68 بايت، بينما يوصى بـ MTU لـ IPv4 بقيمة 576 (يوصى بها عادةً كـ MTU لتطبيقات الاتصال الهاتفي)، سواء وصلت كاملة أو مجزأة. بالنسبة إلى IPv6، الحد الأدنى لـ MTU هو 1280 بايت. ومع ذلك، فإن الحد الأدنى الإلزامي لحجم المخزن المؤقت لإعادة تجميع الأجزاء هو 1500 بايت. قيمة 68 بايت صغيرة جدًا، نظرًا لأن معظم تقنيات طبقة الربط الحالية، مثل Ethernet، لها حد أدنى لـ MTU يبلغ 1500.

من المستحيل معرفة مُسبقًا وحدة النقل القصوى لكل رابط قد تنتقل من خلاله حزمة. لن يعمل إرسال بيانات أكبر من وحدة النقل القصوى للمستقبل لأن الحزمة ستُحذف بصمت دون إبلاغ المصدر بأن البيانات لم تصل إلى المستلم المقصود.

`socket.setBroadcast(flag)`

تمت الإضافة في: v0.6.9

flag <boolean>

يُعيّن أو يُلغي خيار المقبس SO_BROADCAST. عند تعيينه على true، يمكن إرسال حزم UDP إلى عنوان البث الخاص بواجهة محلية.

تُلقي هذه الطريقة استثناء EBADF إذا تم استدعاؤها على مقبس غير مرتبط.

`socket.setMulticastInterface(multicastInterface)`

تمت الإضافة في: v8.6.0

multicastInterface <string>

جميع الإشارات إلى النطاق في هذا القسم تشير إلى مؤشرات نطاق IPv6، والتي تُعرّفها RFC 4007. بصيغة نصية، يُكتب عنوان IP مع مؤشر نطاق كـ 'IP%scope' حيث النطاق هو اسم الواجهة أو رقم الواجهة.

يُعيّن واجهة الإرسال الافتراضية للبث المتعدد للمقبس إلى واجهة مختارة أو يعود إلى اختيار واجهة النظام. يجب أن يكون multicastInterface تمثيلًا سلسلةً صالحًا لعنوان IP من عائلة المقبس.

بالنسبة لمقابس IPv4، يجب أن يكون هذا هو عنوان IP المُهيأ للواجهة المادية المطلوبة. سيتم إرسال جميع الحزم المرسلة إلى البث المتعدد على المقبس على الواجهة التي يحددها الاستخدام الناجح الأخير لهذه الدعوة.

بالنسبة لمقابس IPv6، يجب أن يتضمن multicastInterface نطاقًا للإشارة إلى الواجهة كما هو موضح في الأمثلة التالية. في IPv6، يمكن أيضًا لاستدعاءات send الفردية استخدام نطاق صريح في العناوين، لذلك تتأثر فقط الحزم المرسلة إلى عنوان بث متعدد بدون تحديد نطاق صريح بالاستخدام الناجح الأخير لهذه الدعوة.

تُلقي هذه الطريقة استثناء EBADF إذا تم استدعاؤها على مقبس غير مرتبط.

مثال: واجهة بث متعدد الاتجاهات IPv6 صادرة

في معظم الأنظمة، حيث يستخدم تنسيق النطاق اسم الواجهة:

const socket = dgram.createSocket('udp6')

socket.bind(1234, () => {
  socket.setMulticastInterface('::%eth1')
})

في نظام التشغيل Windows، حيث يستخدم تنسيق النطاق رقم الواجهة:

const socket = dgram.createSocket('udp6')

socket.bind(1234, () => {
  socket.setMulticastInterface('::%2')
})

مثال: واجهة بث متعدد الاتجاهات IPv4 صادرة

تستخدم جميع الأنظمة عنوان IP للجهاز المضيف على الواجهة المادية المطلوبة:

const socket = dgram.createSocket('udp4')

socket.bind(1234, () => {
  socket.setMulticastInterface('10.0.0.2')
})

نتائج الدعوة

قد تُلقي مكالمة على مقبس غير جاهز للإرسال أو لم يعد مفتوحًا خطأ غير قيد التشغيل Error.

إذا تعذر تحليل multicastInterface إلى عنوان IP، فسيتم إرسال خطأ نظام EINVAL System Error.

في IPv4، إذا كان multicastInterface عنوانًا صالحًا ولكنه لا يتطابق مع أي واجهة، أو إذا لم يتطابق العنوان مع العائلة، فسيتم إرسال System Error مثل EADDRNOTAVAIL أو EPROTONOSUP.

في IPv6، ستؤدي معظم الأخطاء في تحديد نطاق أو حذفه إلى استمرار استخدام المقبس (أو العودة إلى) تحديد الواجهة الافتراضية للنظام.

يمكن استخدام عنوان ANY الخاص بعائلة عناوين المقبس (IPv4 '0.0.0.0' أو IPv6 '::') لإرجاع التحكم في واجهة الإرسال الصادرة الافتراضية للمقابس إلى النظام لحزم البث المتعدد المستقبلية.

`socket.setMulticastLoopback(flag)`

تمت الإضافة في: v0.3.8

flag <boolean>

يحدد أو يمسح خيار مقبس IP_MULTICAST_LOOP. عند تعيينه على true، سيتم استقبال حزم البث المتعدد أيضًا على الواجهة المحلية.

تُلقي هذه الطريقة EBADF إذا تم استدعاؤها على مقبس غير مرتبط.

`socket.setMulticastTTL(ttl)`

تمت الإضافة في: v0.3.8

ttl <integer>

يحدد خيار مقبس IP_MULTICAST_TTL. بينما يمثل TTL بشكل عام "وقت البقاء"، في هذا السياق، فإنه يحدد عدد قفزات IP التي يُسمح للحزمة بالسفر عبرها، وتحديدًا لحركة مرور البث المتعدد. يقوم كل جهاز توجيه أو بوابة يُعيد توجيه حزمة بتقليل TTL. إذا تم تقليل TTL إلى 0 بواسطة جهاز توجيه، فلن يتم إعادة توجيهه.

قد تكون وسيطة ttl بين 0 و 255. القيمة الافتراضية في معظم الأنظمة هي 1.

تُلقي هذه الطريقة EBADF إذا تم استدعاؤها على مقبس غير مرتبط.

`socket.setRecvBufferSize(size)`

مضاف في: v8.7.0

size <integer>

يُعيّن خيار المقبس SO_RCVBUF. يُعيّن الحد الأقصى لمُخزن استقبال المقبس بالبايت.

تُلقي هذه الطريقة استثناء ERR_SOCKET_BUFFER_SIZE إذا تم استدعاؤها على مقبس غير مرتبط.

`socket.setSendBufferSize(size)`

مضاف في: v8.7.0

size <integer>

يُعيّن خيار المقبس SO_SNDBUF. يُعيّن الحد الأقصى لمُخزن إرسال المقبس بالبايت.

تُلقي هذه الطريقة استثناء ERR_SOCKET_BUFFER_SIZE إذا تم استدعاؤها على مقبس غير مرتبط.

`socket.setTTL(ttl)`

مضاف في: v0.1.101

ttl <integer>

يُعيّن خيار المقبس IP_TTL. بينما يُشير TTL عمومًا إلى "وقت الحياة"، فإنه في هذا السياق يُحدد عدد قفزات IP التي يُسمح للحزمة بالسفر من خلالها. يقوم كل جهاز توجيه أو بوابة يُعيد توجيه الحزمة بتقليل TTL. إذا تم تقليل TTL إلى 0 بواسطة جهاز توجيه، فلن يتم إعادة توجيهه. يتم عادةً تغيير قيم TTL لاختبارات الشبكة أو عند البث المتعدد.

قد تكون وسيطة ttl بين 1 و 255. القيمة الافتراضية على معظم الأنظمة هي 64.

تُلقي هذه الطريقة استثناء EBADF إذا تم استدعاؤها على مقبس غير مرتبط.

`socket.unref()`

مضاف في: v0.9.1

القيمة المُرجعه: <dgram.Socket>

بشكل افتراضي، سيؤدي ربط مقبس إلى منعه من إنهاء عملية Node.js طالما أن المقبس مفتوح. يمكن استخدام طريقة socket.unref() لاستبعاد المقبس من عدّ الإشارات التي تحافظ على نشاط عملية Node.js، مما يسمح لعملية الخروج حتى إذا كان المقبس لا يزال يستمع.

لن يكون لاستدعاء socket.unref() عدة مرات أي تأثير إضافي.

ترجع طريقة socket.unref() مرجعًا إلى المقبس حتى يمكن سلسلة المكالمات.

دوال وحدة `node:dgram`

`dgram.createSocket(options[, callback])`

[السجل]

الإصدار	التغييرات
v23.1.0	تم دعم خيار `reusePort`.
v15.8.0	تم إضافة دعم `AbortSignal`.
v11.4.0	تم دعم خيار `ipv6Only`.
v8.7.0	تم دعم خياري `recvBufferSize` و `sendBufferSize` الآن.
v8.6.0	تم دعم خيار `lookup`.
v0.11.13	تمت الإضافة في: v0.11.13

options <Object> الخيارات المتاحة هي:
- type <string> عائلة المقبس. يجب أن تكون إما 'udp4' أو 'udp6'. مطلوب.
- reuseAddr <boolean> عندما تكون true، فإن socket.bind() سيعيد استخدام العنوان، حتى لو قامت عملية أخرى بربط مقبس عليه بالفعل، ولكن مقبس واحد فقط يمكنه استقبال البيانات. الافتراضي: false.
- reusePort <boolean> عندما تكون true، فإن socket.bind() سيعيد استخدام المنفذ، حتى لو قامت عملية أخرى بربط مقبس عليه بالفعل. يتم توزيع البيانات الواردة على المقابس المستمعة. يتوفر الخيار فقط على بعض الأنظمة الأساسية، مثل Linux 3.9+، وDragonFlyBSD 3.6+، وFreeBSD 12.0+، وSolaris 11.4، وAIX 7.2.5+. على الأنظمة الأساسية غير المدعومة، يثير هذا الخيار خطأً عند ربط المقبس. الافتراضي: false.
- ipv6Only <boolean> يؤدي تعيين ipv6Only إلى true إلى تعطيل دعم المكدس المزدوج، أي أن الربط بالعنوان :: لن يجعل 0.0.0.0 مرتبطًا. الافتراضي: false.
- recvBufferSize <number> يحدد قيمة مقبس SO_RCVBUF.
- sendBufferSize <number> يحدد قيمة مقبس SO_SNDBUF.
- lookup <Function> دالة بحث مخصصة. الافتراضي: dns.lookup().
- signal <AbortSignal> إشارة AbortSignal التي يمكن استخدامها لإغلاق مقبس.
- receiveBlockList <net.BlockList> يمكن استخدام receiveBlockList لرفض البيانات الواردة إلى عناوين IP محددة، أو نطاقات IP، أو شبكات فرعية IP. هذا لا يعمل إذا كان الخادم خلف وكيل عكسي، أو NAT، إلخ، لأن العنوان الذي يتم التحقق منه مقابل القائمة المحظورة هو عنوان الوكيل، أو العنوان المحدد بواسطة NAT.
- sendBlockList <net.BlockList> يمكن استخدام sendBlockList لتعطيل الوصول الخارجي إلى عناوين IP محددة، أو نطاقات IP، أو شبكات فرعية IP.
callback <Function> مُرفق كمستمع لأحداث 'message'. اختياري.
الإرجاع: <dgram.Socket>

يُنشئ كائنًا dgram.Socket. بمجرد إنشاء المقبس، سيُصدر استدعاء socket.bind() تعليمات للمقبس بالبدء في الاستماع إلى رسائل البيانات. عندما لا يتم تمرير address و port إلى socket.bind()، ستقوم الطريقة بربط المقبس بعنوان "جميع الواجهات" على منفذ عشوائي (يقوم بالشيء الصحيح لكل من مقابس udp4 و udp6). يمكن استرداد العنوان والمنفذ المرتبطين باستخدام socket.address().address و socket.address().port.

إذا تم تمكين خيار signal، فإن استدعاء .abort() على AbortController المقابل مشابه لاستدعاء .close() على المقبس:

const controller = new AbortController()
const { signal } = controller
const server = dgram.createSocket({ type: 'udp4', signal })
server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`)
})
// في وقت لاحق، عندما تريد إغلاق الخادم.
controller.abort()

`dgram.createSocket(type[, callback])`

مضاف في: v0.1.99

type <string> إما 'udp4' أو 'udp6'.
callback <Function> مُرفق كمستمع لأحداث 'message' .
مُخرجات: <dgram.Socket>

يُنشئ كائن dgram.Socket من النوع المحدد.

بمجرد إنشاء المقبس، سيؤدي استدعاء socket.bind() إلى توجيه المقبس لبدء الاستماع لرسائل البيانات. عندما لا يتم تمرير address و port إلى socket.bind() ، ستقوم الطريقة بربط المقبس بعنوان "جميع الواجهات" على منفذ عشوائي (يقوم بالعمل الصحيح لكل من مقابس udp4 و udp6). يمكن استرداد عنوان المنفذ المرتبط باستخدام socket.address().address و socket.address().port.

مقابس UDP/datagram ​

الصف: dgram.Socket ​

الحدث: 'close' ​

الحدث: 'connect' ​

حدث: 'error' ​

حدث: 'listening' ​

حدث: 'message' ​

socket.addMembership(multicastAddress[, multicastInterface]) ​

socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface]) ​

socket.address() ​

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

socket.bind(options[, callback]) ​

socket.close([callback]) ​

socket[Symbol.asyncDispose]() ​

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

socket.disconnect() ​

socket.dropMembership(multicastAddress[, multicastInterface]) ​

socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface]) ​

socket.getRecvBufferSize() ​

socket.getSendBufferSize() ​

socket.getSendQueueSize() ​

socket.getSendQueueCount() ​

socket.ref() ​

socket.remoteAddress() ​

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

ملاحظة حول حجم البيانات في بروتوكول UDP ​

socket.setBroadcast(flag) ​

socket.setMulticastInterface(multicastInterface) ​

مثال: واجهة بث متعدد الاتجاهات IPv6 صادرة ​

مثال: واجهة بث متعدد الاتجاهات IPv4 صادرة ​

نتائج الدعوة ​

socket.setMulticastLoopback(flag) ​

socket.setMulticastTTL(ttl) ​

socket.setRecvBufferSize(size) ​

socket.setSendBufferSize(size) ​

socket.setTTL(ttl) ​

socket.unref() ​

دوال وحدة node:dgram ​

dgram.createSocket(options[, callback]) ​

dgram.createSocket(type[, callback]) ​

مقابس UDP/datagram

الصف: `dgram.Socket`

الحدث: `'close'`

الحدث: `'connect'`

حدث: `'error'`

حدث: `'listening'`

حدث: `'message'`

`socket.addMembership(multicastAddress[, multicastInterface])`

`socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

`socket.address()`

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

`socket.bind(options[, callback])`

`socket.close([callback])`

`socket[Symbol.asyncDispose]()`

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

`socket.disconnect()`

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

`socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

`socket.getRecvBufferSize()`

`socket.getSendBufferSize()`

`socket.getSendQueueSize()`

`socket.getSendQueueCount()`

`socket.ref()`

`socket.remoteAddress()`

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

ملاحظة حول حجم البيانات في بروتوكول UDP

`socket.setBroadcast(flag)`

`socket.setMulticastInterface(multicastInterface)`

مثال: واجهة بث متعدد الاتجاهات IPv6 صادرة

مثال: واجهة بث متعدد الاتجاهات IPv4 صادرة

نتائج الدعوة

`socket.setMulticastLoopback(flag)`

`socket.setMulticastTTL(ttl)`

`socket.setRecvBufferSize(size)`

`socket.setSendBufferSize(size)`

`socket.setTTL(ttl)`

`socket.unref()`

دوال وحدة `node:dgram`

`dgram.createSocket(options[, callback])`

`dgram.createSocket(type[, callback])`