الشبكة (Net)

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

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

توفر وحدة node:net واجهة برمجة تطبيقات شبكة غير متزامنة لإنشاء خوادم TCP أو IPC القائمة على التدفق (net.createServer()) وعملاء (net.createConnection()).

يمكن الوصول إليها باستخدام:

ESMCJS

import net from 'node:net'

const net = require('node:net')

دعم IPC

[السجل]

الإصدار	التغييرات
v20.8.0	دعم الربط بمسار مقبس نطاق يونكس المجرد مثل `\0abstract`. يمكننا ربط '\0' لـ Node.js `\< v20.4.0`.

تدعم وحدة node:net IPC مع الأنابيب المسماة على Windows، ومقابس نطاق يونكس على أنظمة التشغيل الأخرى.

تحديد مسارات اتصالات IPC

تقبل net.connect()، وnet.createConnection()، وserver.listen()، وsocket.connect() معلمة path لتحديد نقاط نهاية IPC.

على يونكس، يُعرف النطاق المحلي أيضًا باسم نطاق يونكس. المسار هو اسم مسار نظام الملفات. سيلقي خطأ عندما يكون طول اسم المسار أكبر من طول sizeof(sockaddr_un.sun_path). القيم النموذجية هي 107 بايت على Linux و 103 بايت على macOS. إذا قام تجريد واجهة برمجة تطبيقات Node.js بإنشاء مقبس نطاق يونكس، فسوف يزيل ارتباط مقبس نطاق يونكس أيضًا. على سبيل المثال، قد يقوم net.createServer() بإنشاء مقبس نطاق يونكس وserver.close() سيُزيل ارتباطه. ولكن إذا قام المستخدم بإنشاء مقبس نطاق يونكس خارج هذه التجريدات، فسيلزم المستخدم إزالته. ينطبق الشيء نفسه عندما تقوم واجهة برمجة تطبيقات Node.js بإنشاء مقبس نطاق يونكس ولكن البرنامج يتعطل بعد ذلك. باختصار، سيكون مقبس نطاق يونكس مرئيًا في نظام الملفات وسيستمر حتى يتم إلغاء ارتباطه. على Linux، يمكنك استخدام مقبس يونكس المجرد عن طريق إضافة \0 إلى بداية المسار، مثل \0abstract. مسار مقبس يونكس المجرد غير مرئي في نظام الملفات وسيختفي تلقائيًا عند إغلاق جميع المراجع المفتوحة للمقبس.

على Windows، يتم تنفيذ النطاق المحلي باستخدام أنبوب مسمى. يجب أن يشير المسار إلى إدخال في \\?\pipe\ أو \\.\pipe\. جميع الأحرف مسموح بها، لكن الأخير قد يقوم ببعض معالجة أسماء الأنابيب، مثل حل تسلسلات ... على الرغم مما قد يبدو عليه، فإن مساحة اسم الأنبوب مسطحة. الأنابيب لن تستمر. يتم إزالتها عند إغلاق آخر مرجع لها. على عكس مقابس نطاق يونكس، سيقوم Windows بإغلاق وإزالة الأنبوب عند خروج العملية المالكة.

يتطلب إفلات سلسلة JavaScript تحديد المسارات مع إفلات باك سلاش إضافي مثل:

net.createServer().listen(path.join('\\\\?\\pipe', process.cwd(), 'myctl'))

الصنف: `net.BlockList`

مضاف في: v15.0.0، v14.18.0

يمكن استخدام كائن BlockList مع بعض واجهات برمجة تطبيقات الشبكة لتحديد قواعد تعطيل الوصول الوارد أو الصادر إلى عناوين IP محددة، أو نطاقات IP، أو شبكات فرعية IP.

`blockList.addAddress(address[, type])`

مضاف في: v15.0.0، v14.18.0

address <string> | <net.SocketAddress> عنوان IPv4 أو IPv6.
type <string> إما 'ipv4' أو 'ipv6'. افتراضي: 'ipv4'.

يضيف قاعدة لحظر عنوان IP المعطى.

`blockList.addRange(start, end[, type])`

مضاف في: v15.0.0، v14.18.0

start <string> | <net.SocketAddress> عنوان IPv4 أو IPv6 الأول في النطاق.
end <string> | <net.SocketAddress> عنوان IPv4 أو IPv6 الأخير في النطاق.
type <string> إما 'ipv4' أو 'ipv6'. افتراضي: 'ipv4'.

يضيف قاعدة لحظر نطاق من عناوين IP من start (ضمنيًا) إلى end (ضمنيًا).

`blockList.addSubnet(net, prefix[, type])`

مضاف في: v15.0.0، v14.18.0

net <string> | <net.SocketAddress> عنوان شبكة IPv4 أو IPv6.
prefix <number> عدد بتات بادئة CIDR. بالنسبة إلى IPv4، يجب أن تكون هذه قيمة بين 0 و 32. بالنسبة إلى IPv6، يجب أن تكون هذه بين 0 و 128.
type <string> إما 'ipv4' أو 'ipv6'. افتراضي: 'ipv4'.

يضيف قاعدة لحظر نطاق من عناوين IP المحددة كقناع شبكة فرعية.

`blockList.check(address[, type])`

مضاف في: v15.0.0, v14.18.0

address <string> | <net.SocketAddress> عنوان IP المراد التحقق منه
type <string> إما 'ipv4' أو 'ipv6'. الافتراضي: 'ipv4'.
القيمة المُرجعه: <boolean>

يرجع true إذا تطابق عنوان IP المُعطى مع أي من القواعد المضافة إلى BlockList.

const blockList = new net.BlockList()
blockList.addAddress('123.123.123.123')
blockList.addRange('10.0.0.1', '10.0.0.10')
blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6')

console.log(blockList.check('123.123.123.123')) // يطبع: true
console.log(blockList.check('10.0.0.3')) // يطبع: true
console.log(blockList.check('222.111.111.222')) // يطبع: false

// تدوين IPv6 ل عناوين IPv4 يعمل:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')) // يطبع: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')) // يطبع: true

`blockList.rules`

مضاف في: v15.0.0, v14.18.0

النوع: <string[]>

قائمة القواعد المضافة إلى القائمة السوداء.

`BlockList.isBlockList(value)`

مضاف في: v23.4.0

value <any> أي قيمة JS
يرجع true إذا كانت value هي net.BlockList.

الصنف: `net.SocketAddress`

مضاف في: v15.14.0, v14.18.0

`new net.SocketAddress([options])`

مضاف في: v15.14.0, v14.18.0

options <Object>
- address <string> عنوان الشبكة كسلسلة IPv4 أو IPv6. الافتراضي: '127.0.0.1' إذا كان family هو 'ipv4'; '::' إذا كان family هو 'ipv6'.
- family <string> واحد من إما 'ipv4' أو 'ipv6'. الافتراضي: 'ipv4'.
- flowlabel <number> علامة تدفق IPv6 تُستخدم فقط إذا كان family هو 'ipv6'.
- port <number> منفذ IP.

`socketaddress.address`

مضاف في: v15.14.0، v14.18.0

النوع <string>

`socketaddress.family`

مضاف في: v15.14.0، v14.18.0

النوع <string> إما 'ipv4' أو 'ipv6'

`socketaddress.flowlabel`

مضاف في: v15.14.0، v14.18.0

النوع <number>

`socketaddress.port`

مضاف في: v15.14.0، v14.18.0

النوع <number>

`SocketAddress.parse(input)`

مضاف في: v23.4.0

input <string> سلسلة إدخال تحتوي على عنوان IP ومنفذ اختياري، مثل 123.1.2.3:1234 أو [1::1]:1234.
القيمة المُرجعه: <net.SocketAddress> يرجع SocketAddress إذا نجح التحليل. وإلا يُرجع undefined.

الصف: `net.Server`

مضاف في: v0.1.90

يمتد: <EventEmitter>

يستخدم هذا الصف لإنشاء خادم TCP أو IPC.

`new net.Server([options][, connectionListener])`

options <Object> انظر net.createServer([options][, connectionListener]).
connectionListener <Function> مُعيّن تلقائيًا كمستمع لحدث 'connection'.
القيمة المُرجعه: <net.Server>

net.Server هو مُصدر أحداث EventEmitter مع الأحداث التالية:

الحدث: `'close'`

مضاف في: v0.5.0

يُصدر عند إغلاق الخادم. إذا كانت هناك اتصالات، فلن يتم إصدار هذا الحدث حتى يتم إنهاء جميع الاتصالات.

الحدث: `'connection'`

مضاف في: v0.1.90

<net.Socket> كائن الاتصال

يُصدر عند إنشاء اتصال جديد. socket هو مثيل لـ net.Socket.

الحدث: `'error'`

مضاف في: v0.1.90

<Error>

يُصدر عند حدوث خطأ. على عكس net.Socket، لن يتم إصدار حدث 'close' مباشرةً بعد هذا الحدث ما لم يتم استدعاء server.close() يدويًا. انظر المثال في مناقشة server.listen().

الحدث: `'listening'`

مضاف في: v0.1.90

يُصدر عندما يتم ربط الخادم بعد استدعاء server.listen().

الحدث: `'drop'`

مضاف في: v18.6.0، v16.17.0

عندما يصل عدد الاتصالات إلى الحد الأقصى لـ server.maxConnections، سيقوم الخادم بإسقاط الاتصالات الجديدة ويصدر حدث 'drop' بدلاً من ذلك. إذا كان خادم TCP، فستكون الوسيطة كما يلي، وإلا ستكون الوسيطة undefined.

data <Object> الوسيطة الممررة إلى مُستمع الحدث.
- localAddress <string> العنوان المحلي.
- localPort <number> المنفذ المحلي.
- localFamily <string> عائلة الاتصال المحلي.
- remoteAddress <string> العنوان البعيد.
- remotePort <number> المنفذ البعيد.
- remoteFamily <string> عائلة عنوان IP البعيد. 'IPv4' أو 'IPv6'.

`server.address()`

[السجل]

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

القيمة المُرجعة: <Object> | <string> | <null>

ترجع عنوان الاتصال المُرتبط address، واسم عائلة العنوان family، وport للخادم كما هو مُبلغ عنه بواسطة نظام التشغيل إذا كان يستمع على مقبس IP (مفيد للعثور على المنفذ الذي تم تعيينه عند الحصول على عنوان مُعين من قِبل نظام التشغيل): { port: 12346, family: 'IPv4', address: '127.0.0.1' }.

بالنسبة للخادم الذي يستمع على أنبوب أو مقبس مجال يونكس، يتم إرجاع الاسم كسلسلة نصية.

const server = net
  .createServer(socket => {
    socket.end('goodbye\n')
  })
  .on('error', err => {
    // التعامل مع الأخطاء هنا.
    throw err
  })

// الحصول على منفذ غير مستخدم عشوائي.
server.listen(() => {
  console.log('opened server on', server.address())
})

server.address() تُرجع null قبل بث حدث 'listening' أو بعد استدعاء server.close().

`server.close([callback])`

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

callback <Function> يُستدعى عند إغلاق الخادم.
القيمة المُرجعة: <net.Server>

يوقف الخادم عن قبول اتصالات جديدة ويحافظ على الاتصالات الحالية. هذه الوظيفة غير متزامنة، حيث يتم إغلاق الخادم أخيرًا عند إنهاء جميع الاتصالات ويُصدر الخادم حدث 'close'. سيتم استدعاء callback الاختياري مرة واحدة عند حدوث حدث 'close' . على عكس هذا الحدث، سيتم استدعاء هذه الوظيفة باستخدام Error كوسيطتها الوحيدة إذا لم يكن الخادم مفتوحًا عند إغلاقه.

`server[Symbol.asyncDispose]()`

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

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

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

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

`server.getConnections(callback)`

مضاف في: v0.9.7

callback <Function>
المُرجَع: <net.Server>

الحصول بشكل غير متزامن على عدد الاتصالات المتزامنة على الخادم. يعمل عندما يتم إرسال المقابس إلى عمليات التشعب.

يجب أن يأخذ دالة الردّ الوسيطتين err و count.

`server.listen()`

بدء خادم يستمع إلى الاتصالات. يمكن أن يكون net.Server خادم TCP أو خادم IPC اعتمادًا على ما يستمع إليه.

التوقيعات الممكنة:

server.listen(handle[, backlog][, callback])
server.listen(options[, callback])
server.listen(path[, backlog][, callback]) لخوادم IPC
server.listen([port[, host[, backlog]]][, callback]) لخوادم TCP

هذه الوظيفة غير متزامنة. عندما يبدأ الخادم في الاستماع، سيتم إصدار حدث 'listening'. سيتم إضافة المعلمة الأخيرة callback كـمستمع لحدث 'listening'.

يمكن لجميع طرق listen() أن تأخذ معلمة backlog لتحديد الحد الأقصى لطول قائمة الانتظار للاتصالات المعلقة. سيتم تحديد الطول الفعلي بواسطة نظام التشغيل من خلال إعدادات sysctl مثل tcp_max_syn_backlog و somaxconn على Linux. القيمة الافتراضية لهذه المعلمة هي 511 (وليس 512).

يتم تعيين جميع net.Socket إلى SO_REUSEADDR (انظر socket(7) للحصول على التفاصيل).

يمكن استدعاء طريقة server.listen() مرة أخرى إذا وفقط إذا كان هناك خطأ أثناء أول استدعاء server.listen() أو تم استدعاء server.close(). خلاف ذلك، سيتم طرح خطأ ERR_SERVER_ALREADY_LISTEN.

أحد أكثر الأخطاء شيوعًا التي يتم رفعها عند الاستماع هو EADDRINUSE. يحدث هذا عندما يكون خادم آخر يستمع بالفعل على port/path/handle المطلوب. إحدى طرق التعامل مع هذا الأمر هي إعادة المحاولة بعد فترة زمنية معينة:

server.on('error', e => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...')
    setTimeout(() => {
      server.close()
      server.listen(PORT, HOST)
    }, 1000)
  }
})

`server.listen(handle[, backlog][, callback])`

مضاف في: v0.5.10

handle <Object>
backlog <number> معلمة شائعة لوظائف server.listen()
callback <Function>
القيمة المُرجعة: <net.Server>

بدء تشغيل خادم يستمع للاتصالات على مُعامل handle مُعيّن تم ربطه بالفعل بمنفذ، أو مقبس مجال يونكس، أو أنبوب مُسمّى بنظام ويندوز.

يمكن أن يكون كائن handle إما خادمًا، أو مقبسًا (أي شيء يحتوي على عضو _handle أساسي)، أو كائنًا يحتوي على عضو fd وهو مُعرّف ملف صالح.

لا يتم دعم الاستماع على مُعرّف ملف في ويندوز.

`server.listen(options[, callback])`

[السجل]

الإصدار	التغييرات
v23.1.0	يتم دعم خيار `reusePort`.
v15.6.0	تمت إضافة دعم `AbortSignal`.
v11.4.0	يتم دعم خيار `ipv6Only`.
v0.11.14	مضاف في: v0.11.14

options <Object> مطلوب. يدعم الخصائص التالية:
- backlog <number> معلمة شائعة لوظائف server.listen().
- exclusive <boolean> افتراضي: false
- host <string>
- ipv6Only <boolean> بالنسبة لخوادم TCP، فإن تعيين ipv6Only إلى true سيؤدي إلى تعطيل دعم المكدس المزدوج، أي أن الربط بالجهاز المضيف :: لن يجعل 0.0.0.0 مُرتبطًا. افتراضي: false.
- reusePort <boolean> بالنسبة لخوادم TCP، فإن تعيين reusePort إلى true يسمح لمقابس متعددة على نفس المضيف بالربط بنفس المنفذ. يتم توزيع الاتصالات الواردة بواسطة نظام التشغيل على المقابس المُستمعة. هذا الخيار متوفر فقط على بعض الأنظمة الأساسية، مثل Linux 3.9+، وDragonFlyBSD 3.6+، وFreeBSD 12.0+، وSolaris 11.4، وAIX 7.2.5+. افتراضي: false.
- path <string> سيتم تجاهله إذا تم تحديد port. انظر تحديد المسارات لاتصالات IPC.
- port <number>
- readableAll <boolean> بالنسبة لخوادم IPC، يجعل الأنبوب قابلاً للقراءة لجميع المستخدمين. افتراضي: false.
- signal <AbortSignal> إشارة AbortSignal يمكن استخدامها لإغلاق خادم مُستمع.
- writableAll <boolean> بالنسبة لخوادم IPC، يجعل الأنبوب قابلاً للكتابة لجميع المستخدمين. افتراضي: false.
callback <Function> وظائف.
القيمة المُرجعة: <net.Server>

إذا تم تحديد port، فسيتصرف بنفس طريقة server.listen([port[, host[, backlog]]][, callback]). خلاف ذلك، إذا تم تحديد path، فسيتصرف بنفس طريقة server.listen(path[, backlog][, callback]). إذا لم يتم تحديد أي منهما، فسيتم إرسال خطأ.

إذا كان exclusive يساوي false (افتراضيًا)، فستستخدم وحدات عمل العنقود نفس المُعامل الأساسي، مما يسمح بمشاركة واجبات معالجة الاتصال. عندما يكون exclusive يساوي true، لا يتم مشاركة المُعامل، وتؤدي محاولة مشاركة المنفذ إلى حدوث خطأ. يظهر أدناه مثال يستمع على منفذ حصري.

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true,
})

عندما يكون exclusive يساوي true ويتم مشاركة المُعامل الأساسي، فمن الممكن أن تستعلم عدة وحدات عمل عن مُعامل مع تراكمات مختلفة. في هذه الحالة، سيتم استخدام أول backlog تم تمريره إلى عملية المُضيف.

قد يؤدي بدء تشغيل خادم IPC كجذر إلى جعل مسار الخادم غير قابل للوصول للمستخدمين الذين لا يتمتعون بامتيازات. سيجعل استخدام readableAll و writableAll الخادم متاحًا لجميع المستخدمين.

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

const controller = new AbortController()
server.listen({
  host: 'localhost',
  port: 80,
  signal: controller.signal,
})
// لاحقًا، عندما تريد إغلاق الخادم.
controller.abort()

`server.listen(path[, backlog][, callback])`

مضاف في: v0.1.90

path <string> المسار الذي يجب أن يستمع إليه الخادم. انظر تحديد المسارات لاتصالات IPC.
backlog <number> معلمة شائعة لوظائف server.listen().
callback <Function>.
القيمة المعادة: <net.Server>

بدء تشغيل خادم IPC يستمع للاتصالات على path المعطى.

`server.listen([port[, host[, backlog]]][, callback])`

مضاف في: v0.1.90

port <number>
host <string>
backlog <number> معلمة شائعة لوظائف server.listen().
callback <Function>.
القيمة المعادة: <net.Server>

بدء تشغيل خادم TCP يستمع للاتصالات على port و host المعطيين.

إذا تم حذف port أو كان 0، فسيتم تعيين نظام التشغيل منفذاً عشوائياً غير مستخدم، والذي يمكن استرجاعه باستخدام server.address().port بعد إصدار حدث 'listening'.

إذا تم حذف host، فسيقبل الخادم الاتصالات على عنوان IPv6 غير محدد (::) عندما يكون IPv6 متوفراً، أو عنوان IPv4 غير محدد (0.0.0.0) خلاف ذلك.

في معظم أنظمة التشغيل، قد يتسبب الاستماع إلى عنوان IPv6 غير محدد (::) في استماع net.Server أيضاً على عنوان IPv4 غير محدد (0.0.0.0).

`server.listening`

مضاف في: v5.7.0

<boolean> يشير إلى ما إذا كان الخادم يستمع إلى الاتصالات أم لا.

`server.maxConnections`

[السجل]

الإصدار	التغييرات
v21.0.0	يؤدي تعيين `maxConnections` إلى `0` إلى إسقاط جميع الاتصالات الواردة. سابقًا، كان يُفسر على أنه `Infinity`.
v0.2.0	مضاف في: v0.2.0

<integer>

عندما يصل عدد الاتصالات إلى عتبة server.maxConnections:

لا يُوصى باستخدام هذا الخيار بمجرد إرسال مقبس إلى عملية فرعية باستخدام child_process.fork().

`server.dropMaxConnection`

مضاف في: v23.1.0

<boolean>

اضبط هذه الخاصية على true لبدء إغلاق الاتصالات بمجرد وصول عدد الاتصالات إلى عتبة [server.maxConnections][]. هذا الإعداد فعال فقط في وضع العنقود.

`server.ref()`

مضاف في: v0.9.1

المرتجع: <net.Server>

على عكس unref()، لن يسمح استدعاء ref() على خادم تم إلغاء مرجعه مسبقًا للبرنامج بالخروج إذا كان الخادم الوحيد المتبقي (السلوك الافتراضي). إذا تم عمل مرجع للخادم، فلن يكون لاستدعاء ref() مرة أخرى أي تأثير.

`server.unref()`

مضاف في: v0.9.1

المرتجع: <net.Server>

سيسمح استدعاء unref() على خادم للبرنامج بالخروج إذا كان هذا هو الخادم النشط الوحيد في نظام الأحداث. إذا تم إلغاء مرجع الخادم بالفعل، فلن يكون لاستدعاء unref() مرة أخرى أي تأثير.

الصف: `net.Socket`

مضاف في: v0.3.4

يمتد: <stream.Duplex>

هذا الصف هو تجريد لمقبس TCP أو نقطة نهاية تدفق IPC (يستخدم أنابيب مسماة على Windows، ومقابس مجال Unix بخلاف ذلك). وهو أيضًا مُرسِل EventEmitter.

يمكن إنشاء net.Socket بواسطة المستخدم واستخدامه مباشرةً للتفاعل مع الخادم. على سبيل المثال، يتم إرجاعه بواسطة net.createConnection()، حتى يتمكن المستخدم من استخدامه للتحدث إلى الخادم.

يمكن أيضًا إنشاؤه بواسطة Node.js ومروره إلى المستخدم عند استلام اتصال. على سبيل المثال، يتم تمريره إلى مستمعي حدث 'connection' المُرسل على net.Server، حتى يتمكن المستخدم من استخدامه للتفاعل مع العميل.

`new net.Socket([options])`

[السجل]

الإصدار	التغييرات
v15.14.0	تمت إضافة دعم AbortSignal.
v12.10.0	تمت إضافة خيار `onread`.
v0.3.4	تمت الإضافة في: v0.3.4

options <Object> الخيارات المتاحة هي:
- allowHalfOpen <boolean> إذا تم تعيينه على false، فسوف ينهي المقبس تلقائيًا الجانب القابل للكتابة عندما ينتهي الجانب القابل للقراءة. راجع net.createServer() وحدث 'end' للحصول على التفاصيل. الافتراضي: false.
- fd <number> إذا تم تحديده، فقم بالتغليف حول مقبس موجود باستخدام مُعرّف الملف المعطى، وإلا سيتم إنشاء مقبس جديد.
- onread <Object> إذا تم تحديده، فسيتم تخزين البيانات الواردة في buffer واحد ومروره إلى callback المُعطى عند وصول البيانات على المقبس. سيؤدي هذا إلى عدم توفير وظيفة البث لأي بيانات. سيصدر المقبس أحداثًا مثل 'error' و 'end' و 'close' كالمعتاد. ستعمل الطرق مثل pause() و resume() كما هو متوقع أيضًا.
- buffer <Buffer> | <Uint8Array> | <Function> إما جزء قابل لإعادة الاستخدام من الذاكرة لاستخدامه لتخزين البيانات الواردة أو دالة تُرجع مثل هذا.
- callback <Function> يتم استدعاء هذه الدالة لكل جزء من البيانات الواردة. يتم تمرير حججين إليها: عدد البايتات المكتوبة في buffer ومرجع إلى buffer. قم بإرجاع false من هذه الدالة لإيقاف المقبس ضمنيًا pause(). سيتم تنفيذ هذه الدالة في السياق العام.
- readable <boolean> السماح بالقراءة على المقبس عند تمرير fd، وإلا يتم تجاهله. الافتراضي: false.
- signal <AbortSignal> إشارة الإلغاء التي يمكن استخدامها لتدمير المقبس.
- writable <boolean> السماح بالكتابة على المقبس عند تمرير fd، وإلا يتم تجاهله. الافتراضي: false.
الإرجاع: <net.Socket>

يُنشئ كائن مقبس جديد.

يمكن أن يكون المقبس الذي تم إنشاؤه حديثًا إما مقبس TCP أو نقطة نهاية تدفق IPC، اعتمادًا على ما يتصل به connect().

الحدث: `'close'`

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

hadError <boolean> true إذا كان للقابس خطأ في الإرسال.

يتم بثه مرة واحدة عند إغلاق القابس بالكامل. الوسيط hadError هو قيمة منطقية تشير إلى ما إذا كان القابس قد تم إغلاقه بسبب خطأ في الإرسال.

الحدث: `'connect'`

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

يتم بثه عند إنشاء اتصال قابس بنجاح. انظر net.createConnection().

الحدث: `'connectionAttempt'`

تم الإضافة في: v21.6.0، v20.12.0

ip <string> عنوان IP الذي يحاول القابس الاتصال به.
port <number> المنفذ الذي يحاول القابس الاتصال به.
family <number> عائلة عنوان IP. يمكن أن تكون 6 لـ IPv6 أو 4 لـ IPv4.

يتم بثه عند بدء محاولة اتصال جديدة. قد يتم بثه عدة مرات إذا تم تمكين خوارزمية تحديد العائلة تلقائيًا في socket.connect(options).

الحدث: `'connectionAttemptFailed'`

تم الإضافة في: v21.6.0، v20.12.0

ip <string> عنوان IP الذي حاول القابس الاتصال به.
port <number> المنفذ الذي حاول القابس الاتصال به.
family <number> عائلة عنوان IP. يمكن أن تكون 6 لـ IPv6 أو 4 لـ IPv4.
error <Error> الخطأ المرتبط بالفشل.

يتم بثه عند فشل محاولة الاتصال. قد يتم بثه عدة مرات إذا تم تمكين خوارزمية تحديد العائلة تلقائيًا في socket.connect(options).

الحدث: `'connectionAttemptTimeout'`

تم الإضافة في: v21.6.0، v20.12.0

ip <string> عنوان IP الذي حاول المقبس الاتصال به.
port <number> المنفذ الذي حاول المقبس الاتصال به.
family <number> عائلة عنوان IP. يمكن أن يكون 6 لـ IPv6 أو 4 لـ IPv4.

يتم بث هذا الحدث عند انتهاء مهلة محاولة الاتصال. لا يتم بث هذا الحدث (وقد يتم بثه عدة مرات) إلا إذا تم تمكين خوارزمية تحديد عائلة عنوان IP تلقائيًا في socket.connect(options).

الحدث: `'data'`

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

<Buffer> | <string>

يتم بث هذا الحدث عند استلام البيانات. ستكون الوسيطة data عبارة عن Buffer أو String. يتم تعيين ترميز البيانات بواسطة socket.setEncoding().

ستضيع البيانات إذا لم يكن هناك مستمع عندما يصدر Socket حدث 'data'.

الحدث: `'drain'`

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

يتم بث هذا الحدث عندما يصبح مُخزن مؤقت الكتابة فارغًا. يمكن استخدامه للتحكم في عمليات التحميل.

انظر أيضًا: قيم الإرجاع لـ socket.write().

الحدث: `'end'`

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

يتم بث هذا الحدث عندما يشير الطرف الآخر من المقبس إلى نهاية الإرسال، وبالتالي ينهي الجانب القابل للقراءة من المقبس.

بشكل افتراضي (allowHalfOpen هو false) سيرسل المقبس حزمة نهاية الإرسال ويدمر مُعرّف الملف الخاص به بمجرد كتابة قائمة الانتظار المعلقة للكتابة. ومع ذلك، إذا تم تعيين allowHalfOpen على true، فلن ينهي المقبس تلقائيًا جانبه القابل للكتابة end()، مما يسمح للمستخدم بكتابة كميات تعسفية من البيانات. يجب على المستخدم الاتصال بـ end() صراحةً لإغلاق الاتصال (أي إرسال حزمة FIN).

حدث: `'error'`

مضاف في: v0.1.90

<Error>

يتم إصداره عند حدوث خطأ. سيتم استدعاء حدث 'close' مباشرة بعد هذا الحدث.

حدث: `'lookup'`

[السجل]

الإصدار	التغييرات
v5.10.0	تم دعم معامل `host` الآن.
v0.11.3	مضاف في: v0.11.3

يتم إصداره بعد حل اسم المضيف ولكن قبل الاتصال. غير قابل للتطبيق على مقابس يونكس.

err <Error> | <null> كائن الخطأ. انظر dns.lookup().
address <string> عنوان IP.
family <number> | <null> نوع العنوان. انظر dns.lookup().
host <string> اسم المضيف.

حدث: `'ready'`

مضاف في: v9.11.0

يتم إصداره عندما يكون المقبس جاهزًا للاستخدام.

يتم تشغيله مباشرة بعد 'connect'.

حدث: `'timeout'`

مضاف في: v0.1.90

يتم إصداره إذا انتهى وقت انتظار المقبس بسبب عدم النشاط. هذا فقط لإخطار بأن المقبس كان خاملاً. يجب على المستخدم إغلاق الاتصال يدويًا.

انظر أيضًا: socket.setTimeout().

`socket.address()`

[السجل]

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

الإرجاع: <Object>

يرجع العنوان المُرتبط address، واسم عائلة العنوان family، وport للمقبس كما هو مُبلغ عنه بواسطة نظام التشغيل: { port: 12346, family: 'IPv4', address: '127.0.0.1' }

`socket.autoSelectFamilyAttemptedAddresses`

مضاف في: v19.4.0، v18.18.0

<string[]>

تظهر هذه الخاصية فقط إذا تم تمكين خوارزمية تحديد عائلة العناوين تلقائيًا في socket.connect(options) وهي عبارة عن مصفوفة من العناوين التي تم محاولة الاتصال بها.

كل عنوان هو سلسلة نصية بالشكل $IP:$PORT. إذا نجح الاتصال، فإن العنوان الأخير هو العنوان الذي تم توصيل المقبس به حاليًا.

`socket.bufferSize`

مضاف في: v0.3.8

مُهمل منذ: v14.6.0

[مستقر: 0 - مُهمل]

مستقر: 0 استقرار: 0 - مُهمل: استخدم writable.writableLength بدلاً من ذلك.

<integer>

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

يملك net.Socket خاصية أن socket.write() تعمل دائمًا. هذا لمساعدة المستخدمين على البدء بسرعة. لا يمكن للكمبيوتر دائمًا مواكبة كمية البيانات التي يتم كتابتها إلى مقبس. قد يكون اتصال الشبكة بطيئًا جدًا ببساطة. سيقوم Node.js داخليًا بوضع البيانات المكتوبة في قائمة انتظار إلى مقبس وإرسالها عبر الشبكة عندما يكون ذلك ممكنًا.

نتيجة هذا التخزين المؤقت الداخلي هي أن الذاكرة قد تنمو. يجب على المستخدمين الذين يواجهون bufferSize كبيرًا أو متزايدًا محاولة "خنق" تدفقات البيانات في برنامجهم باستخدام socket.pause() و socket.resume().

`socket.bytesRead`

مضاف في: v0.5.3

<integer>

كمية البايتات المستلمة.

`socket.bytesWritten`

مضاف في: v0.5.3

<integer>

كمية البايت المرسلة.

`socket.connect()`

بدء اتصال على مقبس معين.

التواقيع الممكنة:

socket.connect(options[, connectListener])
socket.connect(path[, connectListener]) لاتصالات IPC.
socket.connect(port[, host][, connectListener]) لاتصالات TCP.
الإرجاع: <net.Socket> المقبس نفسه.

هذه الدالة غير متزامنة. عند إنشاء الاتصال، سيتم إصدار حدث 'connect'. إذا كانت هناك مشكلة في الاتصال، بدلاً من حدث 'connect'، سيتم إصدار حدث 'error' مع الخطأ الممرر إلى مُستمع 'error'. سيتم إضافة المعلمة الأخيرة connectListener، إذا تم توفيرها، كمستمع لحدث 'connect' مرة واحدة.

يجب استخدام هذه الدالة فقط لإعادة توصيل مقبس بعد إصدار 'close' وإلا فقد يؤدي ذلك إلى سلوك غير محدد.

`socket.connect(options[, connectListener])`

[السجل]

الإصدار	التغييرات
v19.4.0	يمكن تغيير القيمة الافتراضية لخيار autoSelectFamily وقت التشغيل باستخدام `setDefaultAutoSelectFamily` أو عبر خيار سطر الأوامر `--enable-network-family-autoselection`.
v20.0.0, v18.18.0	أصبحت القيمة الافتراضية لخيار autoSelectFamily الآن صحيحة. تم إعادة تسمية علم سطر الأوامر `--enable-network-family-autoselection` إلى `--network-family-autoselection`. الاسم القديم هو الآن اسم مستعار ولكنه غير مُشجع.
v19.3.0, v18.13.0	تمت إضافة خيار `autoSelectFamily`.
v17.7.0, v16.15.0	يتم دعم خيارات `noDelay` و `keepAlive` و `keepAliveInitialDelay` الآن.
v6.0.0	خيار `hints` يساوي `0` افتراضيًا في جميع الحالات الآن. سابقًا، في حالة عدم وجود خيار `family`، كان يساوي `dns.ADDRCONFIG
v5.11.0	يتم دعم خيار `hints` الآن.
v0.1.90	مضاف في: v0.1.90

options <Object>
connectListener <Function> معلمة شائعة لأساليب socket.connect(). سيتم إضافتها كمستمع لحدث 'connect' مرة واحدة.
الإرجاع: <net.Socket> المقبس نفسه.

بدء اتصال على مقبس معين. عادةً لا تكون هذه الطريقة ضرورية، يجب إنشاء المقبس وفتحه باستخدام net.createConnection(). استخدم هذا فقط عند تنفيذ مقبس مخصص.

للاتصالات TCP، الخيارات options المتاحة هي:

autoSelectFamily <boolean>: إذا تم تعيينه على true، فإنه يمكّن خوارزمية الكشف التلقائي للعائلة التي تُنفذ بشكل فضفاض القسم 5 من RFC 8305. يتم تعيين خيار all الممرر إلى البحث على true ويحاول المقابس الاتصال بجميع عناوين IPv6 و IPv4 المُحصل عليها، بالتسلسل، حتى يتم إنشاء اتصال. يتم تجربة أول عنوان AAAA المُرجع أولاً، ثم أول عنوان A المُرجع، ثم ثاني عنوان AAAA المُرجع وهكذا. يتم منح كل محاولة اتصال (إلا الأخيرة) مقدار الوقت المحدد بواسطة خيار autoSelectFamilyAttemptTimeout قبل انتهاء الوقت وتجربة العنوان التالي. يتم تجاهله إذا لم يكن خيار family هو 0 أو إذا تم تعيين localAddress. لا يتم إصدار أخطاء الاتصال إذا نجح اتصال واحد على الأقل. إذا فشلت جميع محاولات الاتصال، يتم إصدار AggregateError واحد مع جميع المحاولات الفاشلة. الافتراضي: net.getDefaultAutoSelectFamily().
autoSelectFamilyAttemptTimeout <number>: مقدار الوقت بالمللي ثانية للانتظار حتى تنتهي محاولة الاتصال قبل تجربة العنوان التالي عند استخدام خيار autoSelectFamily. إذا تم تعيينه على عدد صحيح موجب أقل من 10، فسيتم استخدام القيمة 10 بدلاً من ذلك. الافتراضي: net.getDefaultAutoSelectFamilyAttemptTimeout().
family <number>: إصدار مُكدس IP. يجب أن يكون 4 أو 6 أو 0. تشير القيمة 0 إلى أن عناوين IPv4 و IPv6 مسموح بها. الافتراضي: 0.
hints <number> dns.lookup() hints اختيارية.
host <string> المضيف الذي يجب أن يتصل به المقبس. الافتراضي: 'localhost'.
keepAlive <boolean> إذا تم تعيينه على true، فإنه يُمكّن وظيفة الحفاظ على الاتصال على المقبس فورًا بعد إنشاء الاتصال، بشكل مشابه لما يتم فعله في socket.setKeepAlive(). الافتراضي: false.
keepAliveInitialDelay <number> إذا تم تعيينه على رقم موجب، فإنه يُعيّن التأخير الأولي قبل إرسال أول اختبار للحفاظ على الاتصال على مقبس خامد. الافتراضي: 0.
localAddress <string> العنوان المحلي الذي يجب أن يتصل به المقبس.
localPort <number> المنفذ المحلي الذي يجب أن يتصل به المقبس.
lookup <Function> دالة بحث مخصصة. الافتراضي: dns.lookup().
noDelay <boolean> إذا تم تعيينه على true، فإنه يُعطل استخدام خوارزمية ناجل فورًا بعد إنشاء المقبس. الافتراضي: false.
port <number> مطلوب. المنفذ الذي يجب أن يتصل به المقبس.
blockList <net.BlockList> يمكن استخدام blockList لتعطيل الوصول الصادر إلى عناوين IP أو نطاقات IP أو شبكات فرعية IP محددة.

للاتصالات IPC، الخيارات options المتاحة هي:

path <string> مطلوب. المسار الذي يجب أن يتصل به العميل. انظر تحديد المسارات لاتصالات IPC. إذا تم توفيره، فسيتم تجاهل الخيارات المحددة لـ TCP أعلاه.

`socket.connect(path[, connectListener])`

path <string> المسار الذي يجب أن يتصل به العميل. انظر تحديد المسارات لاتصالات IPC.
connectListener <Function> معلمة شائعة لأساليب socket.connect(). سيتم إضافتها كمستمع لحدث 'connect' مرة واحدة.
الإرجاع: <net.Socket> المقبس نفسه.

بدء اتصال IPC على المقبس المعطى.

مُرادف لـ socket.connect(options[, connectListener]) الذي يتم استدعاؤه باستخدام { path: path } كـ options.

`socket.connect(port[, host][, connectListener])`

مضاف في: v0.1.90

port <number> المنفذ الذي يجب أن يتصل به العميل.
host <string> المضيف الذي يجب أن يتصل به العميل.
connectListener <Function> معلمة شائعة لأساليب socket.connect(). سيتم إضافتها كمستمع لحدث 'connect' مرة واحدة.
الإرجاع: <net.Socket> المقبس نفسه.

بدء اتصال TCP على المقبس المعطى.

مُرادف لـ socket.connect(options[, connectListener]) الذي يتم استدعاؤه باستخدام {port: port, host: host} كـ options.

`socket.connecting`

مضاف في: v6.1.0

<boolean>

إذا كان true، فقد تم استدعاء socket.connect(options[, connectListener]) ولم ينتهِ بعد. سيبقى true حتى يصبح المقبس متصلاً، ثم يتم تعيينه إلى false ويتم إصدار حدث 'connect'. لاحظ أن دالة الاستدعاء socket.connect(options[, connectListener]) هي مستمع لحدث 'connect'.

`socket.destroy([error])`

مضاف في: v0.1.90

error <Object>
القيمة المعادة: <net.Socket>

يضمن عدم حدوث أي نشاط إدخال/إخراج آخر على هذا المقبس. يدمر الدفق ويغلق الاتصال.

انظر إلى writable.destroy() لمزيد من التفاصيل.

`socket.destroyed`

<boolean> يشير إلى ما إذا كان الاتصال قد تم تدميره أم لا. بمجرد تدمير اتصال، لا يمكن نقل المزيد من البيانات باستخدام هذا الاتصال.

انظر إلى writable.destroyed لمزيد من التفاصيل.

`socket.destroySoon()`

مضاف في: v0.3.4

يدمر المقبس بعد كتابة جميع البيانات. إذا تم إصدار حدث 'finish' بالفعل، فسيتم تدمير المقبس على الفور. إذا كان المقبس لا يزال قابلاً للكتابة، فإنه ينادي ضمنيًا socket.end().

`socket.end([data[, encoding]][, callback])`

مضاف في: v0.1.90

data <string> | <Buffer> | <Uint8Array>
encoding <string> يستخدم فقط عندما تكون البيانات من نوع string. افتراضي: 'utf8'.
callback <Function> دالة اختيارية تُستدعى عند الانتهاء من المقبس.
القيمة المعادة: <net.Socket> المقبس نفسه.

يغلق المقبس نصف إغلاق. أي أنه يرسل حزمة FIN. من الممكن أن يظل الخادم يرسل بعض البيانات.

انظر إلى writable.end() لمزيد من التفاصيل.

`socket.localAddress`

مضاف في: v0.9.6

<string>

التعبير النصي لعنوان IP المحلي الذي يتصل به العميل البعيد. على سبيل المثال، في خادم يستمع على '0.0.0.0', إذا قام عميل بالاتصال على '192.168.1.1', ستكون قيمة socket.localAddress هي '192.168.1.1'.

`socket.localPort`

مضاف في: v0.9.6

<integer>

التّمثيل العددي للمنفذ المحلّي. على سبيل المثال، 80 أو 21.

`socket.localFamily`

مضاف في: v18.8.0، v16.18.0

<string>

التّمثيل النصّي لعائلة IP المحلّية. 'IPv4' أو 'IPv6'.

`socket.pause()`

قيمة مُرجعَة: <net.Socket> المُقبس نفسه.

يُوقّف قراءة البيانات. أي، لن يتم إصدار أحداث 'data'. مفيد لتقليل سرعة التّحميل.

`socket.pending`

مضاف في: v11.2.0، v10.16.0

<boolean>

هذه القيمة تكون true إذا لم يتمّ توصيل المُقبس بعد، إمّا لأنّ .connect() لم يتمّ استدعاؤها بعد أو لأنّها لا تزال في طور التّوصيل (انظر socket.connecting).

`socket.ref()`

مضاف في: v0.9.1

قيمة مُرجعَة: <net.Socket> المُقبس نفسه.

على عكس unref()، فإنّ استدعاء ref() على مُقبس تمّ إلغاء مرجعه سابقًا لن يسمح للبرنامج بالخروج إذا كان هو المُقبس الوحيد المتبقي (السلوك الافتراضي). إذا كان المُقبس مُرجعًا، فإنّ استدعاء ref مرة أخرى لن يكون له أيّ تأثير.

`socket.remoteAddress`

مضاف في: v0.5.10

<string>

التّمثيل النصّي لعنوان IP البعيد. على سبيل المثال، '74.125.127.100' أو '2001:4860:a005::68'. قد تكون القيمة undefined إذا تمّ تدمير المُقبس (على سبيل المثال، إذا قام العميل بقطع الاتّصال).

`socket.remoteFamily`

مضاف في: v0.11.14

<string>

التّمثيل النصّي لعائلة IP البعيدة. 'IPv4' أو 'IPv6'. قد تكون القيمة undefined إذا تمّ تدمير المُقبس (على سبيل المثال، إذا قام العميل بقطع الاتّصال).

`socket.remotePort`

مضاف في: v0.5.10

<integer>

التَمثيل العددي للمنفذ البعيد. على سبيل المثال، 80 أو 21. قد تكون القيمة undefined إذا تم تدمير المقبس (على سبيل المثال، إذا قام العميل بإنهاء الاتصال).

`socket.resetAndDestroy()`

مضاف في: v18.3.0، v16.17.0

المُرجَع: <net.Socket>

أغلق اتصال TCP عن طريق إرسال حزمة RST وقم بتدمير التدفق. إذا كان مقبس TCP هذا في حالة الاتصال، فسوف يرسل حزمة RST ويدمر مقبس TCP هذا بمجرد الاتصال. خلاف ذلك، فإنه سيتصل بـ socket.destroy مع خطأ ERR_SOCKET_CLOSED. إذا لم يكن هذا مقبس TCP (على سبيل المثال، أنبوب)، فإن استدعاء هذه الطريقة سيؤدي على الفور إلى طرح خطأ ERR_INVALID_HANDLE_TYPE.

`socket.resume()`

المُرجَع: <net.Socket> المقبس نفسه.

يُستأنف القراءة بعد استدعاء socket.pause().

`socket.setEncoding([encoding])`

مضاف في: v0.1.90

encoding <string>
المُرجَع: <net.Socket> المقبس نفسه.

عيّن ترميز المقبس كتدفق قابل للقراءة Readable Stream. راجع readable.setEncoding() لمزيد من المعلومات.

`socket.setKeepAlive([enable][, initialDelay])`

[السجل]

الإصدار	التغييرات
v13.12.0، v12.17.0	تم إضافة إعدادات افتراضية جديدة لخيارات مقبس `TCP_KEEPCNT` و `TCP_KEEPINTVL`.
v0.1.92	مضاف في: v0.1.92

enable <boolean> الافتراضي: false
initialDelay <number> الافتراضي: 0
المُرجَع: <net.Socket> المقبس نفسه.

تفعيل/تعطيل وظيفة الحفاظ على الاتصال، واختياريًا تعيين التأخير الأولي قبل إرسال أول اختبار للحفاظ على الاتصال على مقبس خامل.

عيّن initialDelay (بالميلي ثانية) لضبط التأخير بين آخر حزمة بيانات تم استلامها وأول اختبار للحفاظ على الاتصال. سيؤدي تعيين 0 لـ initialDelay إلى ترك القيمة دون تغيير من الإعداد الافتراضي (أو السابق).

سيؤدي تمكين وظيفة الحفاظ على الاتصال إلى تعيين خيارات المقبس التالية:

SO_KEEPALIVE=1
TCP_KEEPIDLE=initialDelay
TCP_KEEPCNT=10
TCP_KEEPINTVL=1

`socket.setNoDelay([noDelay])`

مضاف في: v0.1.90

noDelay <boolean> افتراضي: true
القيمة المعادة: <net.Socket> المقبس نفسه.

تمكين/تعطيل استخدام خوارزمية ناجل.

عند إنشاء اتصال TCP، سيتم تمكين خوارزمية ناجل.

تقوم خوارزمية ناجل بتأخير البيانات قبل إرسالها عبر الشبكة. تحاول تحسين الإنتاجية على حساب زمن الوصول.

سيؤدي تمرير true لـ noDelay أو عدم تمرير وسيطة إلى تعطيل خوارزمية ناجل للمقبس. سيؤدي تمرير false لـ noDelay إلى تمكين خوارزمية ناجل.

`socket.setTimeout(timeout[, callback])`

[السجل]

الإصدار	التغييرات
v18.0.0	يؤدي تمرير مُعامل استدعاء غير صالح إلى وسيطة `callback` الآن إلى إرسال `ERR_INVALID_ARG_TYPE` بدلاً من `ERR_INVALID_CALLBACK`.
v0.1.90	مضاف في: v0.1.90

timeout <number>
callback <Function>
القيمة المعادة: <net.Socket> المقبس نفسه.

يُعيّن المقبس لتنتهي مهلة زمنية بعد timeout ميلي ثانية من الخمول على المقبس. بشكل افتراضي، لا تحتوي net.Socket على مهلة زمنية.

عندما يتم تشغيل مهلة الخمول، سيستقبل المقبس حدث 'timeout' ولكن لن يتم قطع الاتصال. يجب على المستخدم الاتصال يدويًا بـ socket.end() أو socket.destroy() لإنهاء الاتصال.

socket.setTimeout(3000)
socket.on('timeout', () => {
  console.log('انتهت مهلة المقبس')
  socket.end()
})

إذا كانت قيمة timeout هي 0، فسيتم تعطيل مهلة الخمول الحالية.

سيتم إضافة وسيطة callback الاختيارية كمستمع لمرة واحدة لحدث 'timeout'.

`socket.timeout`

مضاف في: v10.7.0

<number> | <undefined>

مهلة المقبس بالميلي ثانية كما تم تعيينها بواسطة socket.setTimeout(). وهي undefined إذا لم يتم تعيين مهلة.

`socket.unref()`

مضاف في: v0.9.1

المُرجَع: <net.Socket> المقبس نفسه.

يسمح استدعاء unref() على مقبس للبرنامج بالخروج إذا كان هذا هو المقبس النشط الوحيد في نظام الحدث. إذا كان المقبس مُلغى الإسناد بالفعل، فلن يكون لاستدعاء unref() مرة أخرى أي تأثير.

`socket.write(data[, encoding][, callback])`

مضاف في: v0.1.90

data <string> | <Buffer> | <Uint8Array>
encoding <string> يستخدم فقط عندما تكون البيانات string. الافتراضي: utf8.
callback <Function>
المُرجَع: <boolean>

يرسل البيانات على المقبس. تحدد المعلمة الثانية الترميز في حالة السلسلة. الافتراضي هو ترميز UTF8.

يرجع true إذا تم تفريغ جميع البيانات بنجاح إلى مخزن مؤقت نواة النظام. يرجع false إذا تم وضع جميع البيانات أو جزء منها في ذاكرة المستخدم. سيتم إصدار 'drain' عندما يصبح المخزن المؤقت خاليًا مرة أخرى.

سيتم تنفيذ معلمة callback الاختيارية عندما يتم كتابة البيانات أخيرًا، والتي قد لا تكون فورية.

انظر طريقة تدفق Writable write() لمزيد من المعلومات.

`socket.readyState`

مُضاف في: v0.5.0

<string>

تمثل هذه الخاصية حالة الاتصال كسلسلة نصية.

إذا كان التدفق يتصل، فإن socket.readyState هو opening.
إذا كان التدفق قابلاً للقراءة والكتابة، فهو open.
إذا كان التدفق قابلاً للقراءة وغير قابل للكتابة، فهو readOnly.
إذا كان التدفق غير قابل للقراءة والكتابة، فهو writeOnly.

`net.connect()`

أسماء مستعارة إلى net.createConnection().

التواقيع الممكنة:

net.connect(options[, connectListener])
net.connect(path[, connectListener]) للاتصالات IPC.
net.connect(port[, host][, connectListener]) للاتصالات TCP.

`net.connect(options[, connectListener])`

مُضاف في: v0.7.0

options <Object>
connectListener <Function>
المُرجَع: <net.Socket>

اسم مستعار إلى net.createConnection(options[, connectListener]).

`net.connect(path[, connectListener])`

مُضاف في: v0.1.90

path <string>
connectListener <Function>
المُرجَع: <net.Socket>

اسم مستعار إلى net.createConnection(path[, connectListener]).

`net.connect(port[, host][, connectListener])`

مُضاف في: v0.1.90

port <number>
host <string>
connectListener <Function>
المُرجَع: <net.Socket>

اسم مستعار إلى net.createConnection(port[, host][, connectListener]).

`net.createConnection()`

دالة مصنع، تُنشئ كائنًا جديدًا من نوع net.Socket، وتُبدأ على الفور الاتصال باستخدام socket.connect()، ثم تُعيد كائن net.Socket الذي يبدأ الاتصال.

عندما يتم إنشاء الاتصال، سيتم إصدار حدث 'connect' على كائن المُقبس المُعاد. سيتم إضافة المعلمة الأخيرة connectListener، إذا وُجدت، كـ مُستمع لحدث 'connect' مرة واحدة.

التواقيع الممكنة:

net.createConnection(options[, connectListener])
net.createConnection(path[, connectListener]) للاتصالات IPC.
net.createConnection(port[, host][, connectListener]) للاتصالات TCP.

دالة net.connect() هي اسم مستعار لهذه الدالة.

`net.createConnection(options[, connectListener])`

مضافة في: v0.1.90

options <Object> مطلوب. سيتم تمريره لكل من نداء new net.Socket([options]) وطريقة socket.connect(options[, connectListener]).
connectListener <Function> معلمة مشتركة لدوال net.createConnection(). إذا وُجدت، سيتم إضافتها كمُستمع لحدث 'connect' على كائن المُقبس المُعاد مرة واحدة.
المُخرجات: <net.Socket> كائن المُقبس المُنشأ حديثًا المُستخدم لبدء الاتصال.

للاطلاع على الخيارات المتاحة، انظر new net.Socket([options]) و socket.connect(options[, connectListener]).

خيارات إضافية:

timeout <number> إذا تم تعيينه، فسيتم استخدامه للاتصال بـ socket.setTimeout(timeout) بعد إنشاء المُقبس، ولكن قبل بدء الاتصال.

فيما يلي مثال لعميل لخادم الصدى الموصوف في قسم net.createServer():

ESMCJS

import net from 'node:net'
const client = net.createConnection({ port: 8124 }, () => {
  // مُستمع 'connect'.
  console.log('connected to server!')
  client.write('world!\r\n')
})
client.on('data', data => {
  console.log(data.toString())
  client.end()
})
client.on('end', () => {
  console.log('disconnected from server')
})

const net = require('node:net')
const client = net.createConnection({ port: 8124 }, () => {
  // مُستمع 'connect'.
  console.log('connected to server!')
  client.write('world!\r\n')
})
client.on('data', data => {
  console.log(data.toString())
  client.end()
})
client.on('end', () => {
  console.log('disconnected from server')
})

للاتصال على المُقبس /tmp/echo.sock:

const client = net.createConnection({ path: '/tmp/echo.sock' })

فيما يلي مثال لعميل يستخدم الخيار port و onread. في هذه الحالة، سيتم استخدام خيار onread فقط للاتصال بـ new net.Socket([options]) وسيتم استخدام خيار port للاتصال بـ socket.connect(options[, connectListener]).

ESMCJS

import net from 'node:net'
import { Buffer } from 'node:buffer'
net.createConnection({
  port: 8124,
  onread: {
    // يعيد استخدام مُخزن مؤقت من 4 كيلوبايت لكل قراءة من المُقبس.
    buffer: Buffer.alloc(4 * 1024),
    callback: function (nread, buf) {
      // البيانات المُستقبلة متاحة في `buf` من 0 إلى `nread`.
      console.log(buf.toString('utf8', 0, nread))
    },
  },
})

const net = require('node:net')
net.createConnection({
  port: 8124,
  onread: {
    // يعيد استخدام مُخزن مؤقت من 4 كيلوبايت لكل قراءة من المُقبس.
    buffer: Buffer.alloc(4 * 1024),
    callback: function (nread, buf) {
      // البيانات المُستقبلة متاحة في `buf` من 0 إلى `nread`.
      console.log(buf.toString('utf8', 0, nread))
    },
  },
})

`net.createConnection(path[, connectListener])`

مضاف في: v0.1.90

path <string> المسار الذي يجب أن يتصل به المقبس. سيتم تمريره إلى socket.connect(path[, connectListener]). انظر تحديد مسارات اتصالات IPC.
connectListener <Function> معلمة مشتركة لوظائف net.createConnection()، وهي مُستمع "مرة واحدة" لحدث 'connect' على المقبس المُنشئ. سيتم تمريره إلى socket.connect(path[, connectListener]).
القيمة المُرجعة: <net.Socket> المقبس المُنشأ حديثًا المُستخدم لبدء الاتصال.

يُنشئ اتصال IPC.

تقوم هذه الوظيفة بإنشاء net.Socket جديد مع تعيين جميع الخيارات إلى القيمة الافتراضية، وتُنشئ اتصالًا على الفور باستخدام socket.connect(path[, connectListener])، ثم تُعيد net.Socket الذي يُنشئ الاتصال.

`net.createConnection(port[, host][, connectListener])`

مضاف في: v0.1.90

port <number> المنفذ الذي يجب أن يتصل به المقبس. سيتم تمريره إلى socket.connect(port[, host][, connectListener]).
host <string> المضيف الذي يجب أن يتصل به المقبس. سيتم تمريره إلى socket.connect(port[, host][, connectListener]). الافتراضي: 'localhost'.
connectListener <Function> معلمة مشتركة لوظائف net.createConnection()، وهي مُستمع "مرة واحدة" لحدث 'connect' على المقبس المُنشئ. سيتم تمريره إلى socket.connect(port[, host][, connectListener]).
القيمة المُرجعة: <net.Socket> المقبس المُنشأ حديثًا المُستخدم لبدء الاتصال.

يُنشئ اتصال TCP.

تقوم هذه الوظيفة بإنشاء net.Socket جديد مع تعيين جميع الخيارات إلى القيمة الافتراضية، وتُنشئ اتصالًا على الفور باستخدام socket.connect(port[, host][, connectListener])، ثم تُعيد net.Socket الذي يُنشئ الاتصال.

`net.createServer([options][, connectionListener])`

[السجل]

الإصدار	التغييرات
v20.1.0, v18.17.0	تم دعم خيار `highWaterMark` الآن.
v17.7.0, v16.15.0	تم دعم خيارات `noDelay` و `keepAlive` و `keepAliveInitialDelay` الآن.
v0.5.0	تمت الإضافة في: v0.5.0

options <Object>
- allowHalfOpen <boolean> إذا تم تعيينه على false، فسوف يقوم المقبس بإنهاء الجانب القابل للكتابة تلقائيًا عند انتهاء الجانب القابل للقراءة. الافتراضي: false.
- highWaterMark <number> يُلغي اختيارياً جميع علامات readableHighWaterMark و writableHighWaterMark الخاصة بـ net.Socket. الافتراضي: انظر stream.getDefaultHighWaterMark().
- keepAlive <boolean> إذا تم تعيينه على true، فإنه يُمكّن وظيفة الحفاظ على الاتصال على المقبس مباشرة بعد استقبال اتصال داخلي جديد، بشكل مشابه لما يتم في socket.setKeepAlive(). الافتراضي: false.
- keepAliveInitialDelay <number> إذا تم تعيينه على رقم موجب، فإنه يحدد التأخير الأولي قبل إرسال أول اختبار للحفاظ على الاتصال على مقبس خامد. الافتراضي: 0.
- noDelay <boolean> إذا تم تعيينه على true، فإنه يُعطل استخدام خوارزمية ناجل مباشرة بعد استقبال اتصال داخلي جديد. الافتراضي: false.
- pauseOnConnect <boolean> يشير إلى ما إذا كان يجب إيقاف المقبس مؤقتًا على الاتصالات الواردة. الافتراضي: false.
- blockList <net.BlockList> يمكن استخدام blockList لتعطيل الوصول الوارد إلى عناوين IP محددة، أو نطاقات IP، أو شبكات فرعية IP. هذا لا يعمل إذا كان الخادم خلف وكيل عكسي، أو NAT، إلخ، لأن العنوان الذي يتم التحقق منه مقابل قائمة الحظر هو عنوان الوكيل، أو العنوان المحدد بواسطة NAT.
connectionListener <Function> يتم تعيينه تلقائيًا كـ مستمع لحدث 'connection'.
المُخرجات: <net.Server>

يُنشئ خادم TCP أو خادم IPC جديدًا.

إذا تم تعيين allowHalfOpen على true، فعندما يُشير الطرف الآخر من المقبس إلى نهاية الإرسال، سيرسل الخادم فقط نهاية الإرسال عند استدعاء socket.end() صراحةً. على سبيل المثال، في سياق TCP، عندما يتم استقبال حزمة FIN، يتم إرسال حزمة FIN فقط عند استدعاء socket.end() صراحةً. حتى ذلك الحين، يكون الاتصال مغلقًا جزئيًا (غير قابل للقراءة ولكنه لا يزال قابلًا للكتابة). انظر حدث 'end' و RFC 1122 (القسم 4.2.2.13) لمزيد من المعلومات.

إذا تم تعيين pauseOnConnect على true، فسيتم إيقاف المقبس المرتبط بكل اتصال واردة مؤقتًا، ولن يتم قراءة أي بيانات من مقبضه. هذا يسمح بنقل الاتصالات بين العمليات دون قراءة أي بيانات بواسطة العملية الأصلية. لبدء قراءة البيانات من مقبس مؤقت، اتصل بـ socket.resume().

يمكن أن يكون الخادم خادم TCP أو خادم IPC، وهذا يتوقف على ما listen() إليه.

فيما يلي مثال على خادم صدى TCP يستمع للاتصالات على المنفذ 8124:

ESMCJS

import net from 'node:net'
const server = net.createServer(c => {
  // مستمع 'connection'.
  console.log('client connected')
  c.on('end', () => {
    console.log('client disconnected')
  })
  c.write('hello\r\n')
  c.pipe(c)
})
server.on('error', err => {
  throw err
})
server.listen(8124, () => {
  console.log('server bound')
})

const net = require('node:net')
const server = net.createServer(c => {
  // مستمع 'connection'.
  console.log('client connected')
  c.on('end', () => {
    console.log('client disconnected')
  })
  c.write('hello\r\n')
  c.pipe(c)
})
server.on('error', err => {
  throw err
})
server.listen(8124, () => {
  console.log('server bound')
})

اختبر هذا باستخدام telnet:

bash

telnet localhost 8124

للاستماع على المقبس /tmp/echo.sock:

server.listen('/tmp/echo.sock', () => {
  console.log('server bound')
})

استخدم nc للاتصال بخادم مقبس مجال يونكس:

bash

nc -U /tmp/echo.sock

`net.getDefaultAutoSelectFamily()`

مضاف في: v19.4.0

يحصل على القيمة الافتراضية الحالية لخيار autoSelectFamily من socket.connect(options). القيمة الافتراضية الأولية هي true، إلا إذا تم توفير خيار سطر الأوامر --no-network-family-autoselection.

الإرجاع: <boolean> القيمة الافتراضية الحالية لخيار autoSelectFamily.

`net.setDefaultAutoSelectFamily(value)`

مضاف في: v19.4.0

يحدد القيمة الافتراضية لخيار autoSelectFamily من socket.connect(options).

value <boolean> القيمة الافتراضية الجديدة. القيمة الافتراضية الأولية هي true، إلا إذا تم توفير خيار سطر الأوامر --no-network-family-autoselection.

`net.getDefaultAutoSelectFamilyAttemptTimeout()`

مضاف في: v19.8.0، v18.18.0

يحصل على القيمة الافتراضية الحالية لخيار autoSelectFamilyAttemptTimeout من socket.connect(options). القيمة الافتراضية الأولية هي 250 أو القيمة المحددة عبر خيار سطر الأوامر --network-family-autoselection-attempt-timeout.

الإرجاع: <number> القيمة الافتراضية الحالية لخيار autoSelectFamilyAttemptTimeout.

`net.setDefaultAutoSelectFamilyAttemptTimeout(value)`

مضاف في: v19.8.0، v18.18.0

يحدد القيمة الافتراضية لخيار autoSelectFamilyAttemptTimeout من socket.connect(options).

value <number> القيمة الافتراضية الجديدة، والتي يجب أن تكون رقمًا موجبًا. إذا كان الرقم أقل من 10، فسيتم استخدام القيمة 10 بدلاً من ذلك. القيمة الافتراضية الأولية هي 250 أو القيمة المحددة عبر خيار سطر الأوامر --network-family-autoselection-attempt-timeout.

`net.isIP(input)`

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

input <string>
قيمة الإرجاع: <integer>

ترجع 6 إذا كان input عنوان IPv6. ترجع 4 إذا كان input عنوان IPv4 بتدوين النقطة العشرية dot-decimal notation بدون أصفار بادئة. خلاف ذلك، ترجع 0.

net.isIP('::1') // ترجع 6
net.isIP('127.0.0.1') // ترجع 4
net.isIP('127.000.000.001') // ترجع 0
net.isIP('127.0.0.1/24') // ترجع 0
net.isIP('fhqwhgads') // ترجع 0

`net.isIPv4(input)`

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

input <string>
قيمة الإرجاع: <boolean>

ترجع true إذا كان input عنوان IPv4 بتدوين النقطة العشرية dot-decimal notation بدون أصفار بادئة. خلاف ذلك، ترجع false.

net.isIPv4('127.0.0.1') // ترجع true
net.isIPv4('127.000.000.001') // ترجع false
net.isIPv4('127.0.0.1/24') // ترجع false
net.isIPv4('fhqwhgads') // ترجع false

`net.isIPv6(input)`

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

input <string>
قيمة الإرجاع: <boolean>

ترجع true إذا كان input عنوان IPv6. خلاف ذلك، ترجع false.

net.isIPv6('::1') // ترجع true
net.isIPv6('fhqwhgads') // ترجع false

الشبكة (Net) ​

دعم IPC ​

تحديد مسارات اتصالات IPC ​

الصنف: net.BlockList ​

blockList.addAddress(address[, type]) ​

blockList.addRange(start, end[, type]) ​

blockList.addSubnet(net, prefix[, type]) ​

blockList.check(address[, type]) ​

blockList.rules ​

BlockList.isBlockList(value) ​

الصنف: net.SocketAddress ​

new net.SocketAddress([options]) ​

socketaddress.address ​

socketaddress.family ​

socketaddress.flowlabel ​

socketaddress.port ​

SocketAddress.parse(input) ​

الصف: net.Server ​

new net.Server([options][, connectionListener]) ​

الحدث: 'close' ​

الحدث: 'connection' ​

الحدث: 'error' ​

الحدث: 'listening' ​

الحدث: 'drop' ​

server.address() ​

server.close([callback]) ​

server[Symbol.asyncDispose]() ​

server.getConnections(callback) ​

server.listen() ​

server.listen(handle[, backlog][, callback]) ​

server.listen(options[, callback]) ​

server.listen(path[, backlog][, callback]) ​

server.listen([port[, host[, backlog]]][, callback]) ​

server.listening ​

server.maxConnections ​

server.dropMaxConnection ​

server.ref() ​

server.unref() ​

الصف: net.Socket ​

new net.Socket([options]) ​

الحدث: 'close' ​

الحدث: 'connect' ​

الحدث: 'connectionAttempt' ​

الحدث: 'connectionAttemptFailed' ​

الحدث: 'connectionAttemptTimeout' ​

الحدث: 'data' ​

الحدث: 'drain' ​

الحدث: 'end' ​

حدث: 'error' ​

حدث: 'lookup' ​

حدث: 'ready' ​

حدث: 'timeout' ​

socket.address() ​

socket.autoSelectFamilyAttemptedAddresses ​

socket.bufferSize ​

socket.bytesRead ​

socket.bytesWritten ​

socket.connect() ​

socket.connect(options[, connectListener]) ​

socket.connect(path[, connectListener]) ​

socket.connect(port[, host][, connectListener]) ​

socket.connecting ​

socket.destroy([error]) ​

socket.destroyed ​

socket.destroySoon() ​

socket.end([data[, encoding]][, callback]) ​

socket.localAddress ​

socket.localPort ​

socket.localFamily ​

socket.pause() ​

socket.pending ​

socket.ref() ​

socket.remoteAddress ​

socket.remoteFamily ​

socket.remotePort ​

socket.resetAndDestroy() ​

socket.resume() ​

socket.setEncoding([encoding]) ​

socket.setKeepAlive([enable][, initialDelay]) ​

socket.setNoDelay([noDelay]) ​

الشبكة (Net)

دعم IPC

تحديد مسارات اتصالات IPC

الصنف: `net.BlockList`

`blockList.addAddress(address[, type])`

`blockList.addRange(start, end[, type])`

`blockList.addSubnet(net, prefix[, type])`

`blockList.check(address[, type])`

`blockList.rules`

`BlockList.isBlockList(value)`

الصنف: `net.SocketAddress`

`new net.SocketAddress([options])`

`socketaddress.address`

`socketaddress.family`

`socketaddress.flowlabel`

`socketaddress.port`

`SocketAddress.parse(input)`

الصف: `net.Server`

`new net.Server([options][, connectionListener])`

الحدث: `'close'`

الحدث: `'connection'`

الحدث: `'error'`

الحدث: `'listening'`

الحدث: `'drop'`

`server.address()`

`server.close([callback])`

`server[Symbol.asyncDispose]()`

`server.getConnections(callback)`

`server.listen()`

`server.listen(handle[, backlog][, callback])`

`server.listen(options[, callback])`

`server.listen(path[, backlog][, callback])`

`server.listen([port[, host[, backlog]]][, callback])`

`server.listening`

`server.maxConnections`

`server.dropMaxConnection`

`server.ref()`

`server.unref()`

الصف: `net.Socket`

`new net.Socket([options])`

الحدث: `'close'`

الحدث: `'connect'`

الحدث: `'connectionAttempt'`

الحدث: `'connectionAttemptFailed'`

الحدث: `'connectionAttemptTimeout'`

الحدث: `'data'`

الحدث: `'drain'`

الحدث: `'end'`

حدث: `'error'`

حدث: `'lookup'`

حدث: `'ready'`

حدث: `'timeout'`

`socket.address()`

`socket.autoSelectFamilyAttemptedAddresses`

`socket.bufferSize`

`socket.bytesRead`

`socket.bytesWritten`

`socket.connect()`

`socket.connect(options[, connectListener])`

`socket.connect(path[, connectListener])`

`socket.connect(port[, host][, connectListener])`

`socket.connecting`

`socket.destroy([error])`

`socket.destroyed`

`socket.destroySoon()`

`socket.end([data[, encoding]][, callback])`

`socket.localAddress`

`socket.localPort`

`socket.localFamily`

`socket.pause()`

`socket.pending`

`socket.ref()`

`socket.remoteAddress`

`socket.remoteFamily`

`socket.remotePort`

`socket.resetAndDestroy()`

`socket.resume()`

`socket.setEncoding([encoding])`

`socket.setKeepAlive([enable][, initialDelay])`

`socket.setNoDelay([noDelay])`