وحدة Net في Node.js
مؤشر الاستقرار: 2 - مستقر.
توفر الوحدة net
واجهة تطبيقات لشبكة اتصال غير متزامن لإنشاء خوادم قائمة على تدفق اتصالات TCP أو IPC أي (net.createServer()
) والعملاء (net.createConnection()
).
ويمكن الوصول إليه باستخدام:
const net = require('net');
دعم اتصالات IPC
تدعم وحدة net
اتصالات IPC بواسطة الأنابيب المُسماة (named pipes) في ويندوز، أو مقابس مجالات يونكس (UNIX domain sockets) في أنظمة التشغيل الأخرى.
تحديد مسارات اتصالات IPC
تحتاج التوابع net.connect()
و net.createConnection()
و server.listen()
و socket.connect()
المعامل path
لتحديد نهايات اتصالات IPC.
يُعرف النطاق المحلي في UNIX بنطاق UNIX. ويكون المسار هو اسم مسار نظام الملفات. ويجري اقتصاصها إلى حجم يساوي sizeof(sockaddr_un.sun_path)-1
، والذي يختلف من نظام تشغيل إلى آخر بين 91 و 107 بايت. القيم النموذجية هي 107 في نظام لينكس و 103 في نظام macOS. ويخضع المسار لنفس اصطلاحات التسمية وفحص الأذونات بنفس كيفية إنشاء ملف. إذا أُنشئ مقبس مجال UNIX (الذي يكون مرئياً كمسار نظام ملف) واستُخدم بالاقتران مع أحد تجريديات واجهات تطبيقات Node.js مثل net.createServer()
، سينقطع ارتباطه كجزء من server.close()
. من ناحية أخرى، إذا أُنشئ واستُخدم خارج هذه التجريديات، سوف يحتاج المستخدم لإزالته يدويًا. وينطبق الشيء نفسه عند إنشاء المسار من قِبَل واجهات تطبيقات Node.js ولكن البرنامج يتعطل فجأة. وباختصار، سيظهر مقبس مجال UNIX في نظام الملفات تم إنشاءه بنجاح، وسوف يستمر حتى يقطع ارتباطه.
في ويندوز، يتحقق النطاق المحلي باستخدام أنبوب مُسمّى. يجب أن يشير المسار إلى مُدخل في \\?\pipe\
أو \\.\pipe\
. مسموح بأي حروف، ولكن قد يجري هذا الأخير بعض المعالجة لأسماء الأنابيب مثل أن يُترجم متواليات ..
. على الرغم من كيف يمكن أن تبدو، فإن مجال أسماء الأنابيب مسطحة. لن تستمر الأنابيب. وتُزال عند إغلاق آخر مرجع إليها. على عكس مقابس مجال UNIX، يُغلق ويندوز الأنابيب ويُزيلها عند انتهاء العملية المالكة.
يتطلب الهروب من سلسلة JavaScript مسارات محددة باستخدام شرطة هروب مائلة عكسية \
إضافية مثل:
net.createServer().listen(
path.join('\\\\?\\pipe', process.cwd(), 'myctl'));
الصنف net.Server
أُضيف مع الإصدار: v0.1.90.
يستخدم هذا الصنف لإنشاء خادم 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()
.
server.address()
أُضيف مع الإصدار: v0.1.90.
يعيد العنوان address
المنضم واسم عائلة العنوان family
ومنفذ الخادم port
كما يذكره نظام التشغيل إذا كان يستمع إلى مقبس IP (وهو يفيد في العثور على أي منفذ الذي عُيّن عند الحصول على عنوان مُعيَّن من قِبل نظام التشغيل): { port: 12346, family: 'IPv4', address: '127.0.0.1' }
.
بالنسبة لخادم يستمع إلى أنابيب أو مقبس نطاق UNIX، يُعاد الاسم كسلسلة نصية.
على سبيل المثال:
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()
حتى ينطلق الحدث 'listening'
.
server.close([callback])
أُضيف مع الإصدار: v0.1.90.
callback
<Function>: الدالة التي ستستدعى عند إغلاق الاتصال مع الخادم.
- القيمة المُعادة: من النوع
<net.Server>
.
يمنع الخادم من قبول اتصالات جديدة ويحافظ على الاتصالات الموجودة. وهو دالة غير متزامنة، ويُغلَق الخادم أخيراً عند إنهاء كافة الاتصالات ويُطلِق الخادم حدث 'close'
. وتُستدعى دالة رد الاتصال callback
الاختيارية بمجرد حدوث الحدث 'close'
. على عكس هذا الحدث ستستدعى مع Error
كوسيط وحيد إذا كان الخادم غير مفتوح عند إغلاقه.
server.connections
(مُهمَل)
أُضيف مع الإصدار: v0.2.0، وأُهمِل مع الإصدار: v0.9.7.
مؤشر الاستقرار: 0 - مُهمل: يُستخدم server.getConnections()
بدلاً منه.
عدد الاتصالات المتزامنة مع الخادم.
ويصبح null
عند إرسال مقبس لأحد الأبناء بواسطة التابع child_process.fork()
. لاستطلاع التفرعات والحصول على العدد الحالي من الاتصالات النشطة يستخدم التابع server.getConnections()
غير المتزامن بدلاً من ذلك.
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.log('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>
: وهو معامل شائع لدوالserver.listen()
.
- القيمة المُعادة: من النوع
<net.Server>
.
بدء تشغيل خادم للاستماع للاتصالات على handle
سبق ربطه مع منفذ، أو مقبس نطاق UNIX، أو أنبوب ويندوز المسمى.
يمكن أن يكون الكائن handle أما خادم أو مقبس (أي شيء مع عضو _handle
أساسي) أو كائن مع عضو fd
يكون واصف ملف صالح.
ولا يدعم ويندوز الاستماع إلى واصف ملف.
server.listen(options[, callback])
أُضيفت مع الإصدار: 0.11.14.
options
من النوع<Object>
: ويجب إدخاله. وهو يدعم الخصائص التالية:port
من النوع<number>
.host
من النوع<string>
.path
من النوع<string>
: سيُتجاهل إذا حُدِد port. راجع تحديد مسارات اتصالات IPC.backlog
من النوع<number>
: وهو معامل شائع لدوالserver.listen()
.exclusive
من النوع<boolean>
. وتكون القيمة الافتراضية:false
.readableAll
من النوع<boolean>
: وهو يجعل الأنابيب مقروءة لجميع المستخدمين في خوادم IPC. وتكون القيمة الافتراضية: false.writableAll
من النوع<boolean>
: وهو يجعل الأنابيب قابلة للكتابة لجميع المستخدمين في خوادم IPC. وتكون القيمة الافتراضية:false
.
callback
من النوع<Function>
وهو معامل شائع لدوالserver.listen()
.- القيمة المُعادة: من النوع
<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
});
قد يتسبب بدء تشغيل خادم IPC كجذر في أن يكون مسار الخادم غير قابل للوصول للمستخدمين غير المتمتعين بامتيازات. سيؤدي استخدام readableAll
و writableAll
إلى أن يكون الخادم في متناول جميع المستخدمين.
server.listen(path[, backlog][, callback])
أُضيف مع الإصدار: v0.1.90.
path
من النوع<string>
: وهو المسار الذي يجب على الخادم الاستماع إليه. راجع تحديد مسارات اتصالات IPC.backlog
من النوع<number>
: وهو معامل شائع لدوالserver.listen()
.callback
من النوع<Function>
: وهو معامل شائع لدوالserver.listen()
.- القيمة المُعادة: من النوع
<net.Server>
.
بدء تشغيل خادم IPC للاستماع للاتصالات على path
معين.
server.listen([port[, host[, backlog]]][, callback])
أُضيف مع الإصدار: v0.1.90.
port
من النوع<number>
.host
من النوع<string>
.backlog
من النوع<number>
وهو معامل شائع لدوالserver.listen()
.callback
من النوع<Function>
: وهو معامل شائع لدوالserver.listen()
.- القيمة المُعادة: من النوع
<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
أضيفت مع الإصدار: v0.2.0.
تُضبط هذه الخاصية لرفض الاتصالات عندما يكون عدد الاتصالات بالخادم كبيرًا.
من غير المستحسن استخدام هذا الخيار عند إرسال مقبس إلى أحد الأبناء خلال child_process.fork()
.
server.ref()
أُضيف مع الإصدار: v0.9.1.
- القيمة المُعادة: من النوع
<net.Server>
.
على عكس unref()
، استدعاء ref()
على خادم سبق إجراء unref
عليه لن يسمح للبرنامج بالانتهاء إذا كان هو الخادم الوحيد المتبقي (السلوك الافتراضي). أما استدعاء ref()
مرة أخرى على خادم سبق إجراء ref
عليه فلن يكون له أي تأثير.
server.unref()
أُضيف مع الإصدار: v0.9.1.
- القيمة المُعادة: من النوع
<net.Server>
.
يسمح استدعاء unref()
على خادم للبرنامج بالإنهاء إذا كان هو الخادم النشط الوحيد في نظام الأحداث. أما استدعاء unref()
مرة أخرى على خادم سبق إجراء unref
عليه فلن يكون له أي تأثير.
الصنف net.Socket
أُضيف مع الإصدار: v0.3.4.
يعد هذا الصنف تجريد لمقبس TCP أو لنقطة نهاية دفق IPC (يستخدم الأنابيب المسماة في ويندوز، ومقابس مجال UNIX خلاف ذلك). وتعد net.Socket
أيضا تيارًا مزدوجًا (duplex stream)، حيث يمكن أن تكون قابلة للقراءة والكتابة على حد سواء، وهي أيضا EventEmitter
.
ويمكن للمستخدم إنشاء net.Socket
واستخدامها مباشرة في التفاعل مع الخادم. على سبيل المثال، تُعاد من قِبل net.createConnection()
، بحيث يمكن للمستخدم استخدامها للتحدث إلى الخادم.
ويمكن أيضا إنشاؤها بواسطة Node.js وتمريرها إلى المستخدم عند تلقي اتصال. على سبيل المثال، تُمرر إلى مستمعي الحدث 'connection'
المُصدر على net.Server
بحيث يمكن للمستخدم استخدامها للتفاعل مع العميل.
new net.Socket([options])
أُضيف مع الإصدار: v0.3.4.
إنشاء كائن مقبس جديد.
options
من النوع<Object>
: .الخيارات المتاحة هي:fd
من النوع<number>
: وهو يغلف حول مقبس موجود مع واصف ملف معين، خلاف ذلك سيُنشَأ مقبس جديد.allowHalfOpen
من النوع<boolean>
: وهو يشير إلى ما إذا كان مسموح باتصالات TCP مفتوحة نصفيا. راجعnet.createServer()
والحدث'end'
لمزيد من التفاصيل. القيمة الافتراضية:false
.readable
من النوع<boolean>
: وهو يسمح بالقراءة على المقبس عند تمريرfd
، ويُتجاهل بخلاف ذلك. القيمة الافتراضية:false
.writable
من النوع<boolean>
: ويسمح بالكتابة على المقبس عند تمريرfd
، ويُتجاهل بخلاف ذلك. القيمة الافتراضية:false
.
- القيمة المُعادة: من النوع
<net.Socket>
.
يمكن أن يكون مأخذ التوصيل المُنشأ حديثا أما مقبس توصيل TCP أو نقطة نهاية IPC، اعتماداً على ما تتصل به من خلال connect()
.
الحدث 'close'
أُضيف مع الإصدار: v0.1.90.
hadError
من النوع<boolean>
: وتكون قيمتهاtrue
إذا حدث للمقبس خطأ في النقل.
يُطلٓق حالما يغلق المقبس بالكامل. ويشير الوسيط hadError
وهو قيمة منطقية إذا كان المقبس مغلقا بسبب خطأ في النقل.
الحدث 'connect'
أُضيف مع الإصدار: v0.1.90.
يطلق عند إتمام اتصال المقبس بنجاح. راجع net.createConnection()
.
الحدث 'data'
أُضيف مع الإصدار: v0.1.90.
- من النوع
<Buffer>
|<string>
يُطلق عند استلام البيانات. وسيكون الوسيط data
من النوع Buffer
أو String
. ويُضبط ترميز البيانات بواسطة socket.setEncoding()
.
علما بأن data
ستُفقَد إذا لم يكن هناك أي مستمع عندما يُطلِق Socket
الحدث 'data'
.
الحدث 'drain'
أُضيف مع الإصدار: v0.1.90.
يُطلق عندما يصبح مخزن الكتابة المؤقت فارغا. يمكن أن يستخدم لخنق التحميلات.
انظر أيضًا: القيم المعادة من socket.write()
.
الحدث 'end'
أُضيف مع الإصدار: v0.1.90.
يطلق عندما يرسل الطرف الآخر من المقبس حزمة FIN، منهيًا بذلك الجانب المقروء من المقبس.
افتراضيًا (allowHalfOpen
قيمتها false
) سيرسل المقبس حزمة FIN مرة أخرى ويهدم واصف الملف تو كتابته أثناء وجوده في قائمة انتظار الكتابة. ومع ذلك، إذا ضُبطت allowHalfOpen
بالقيمة true
، لن ينهي المقبس تلقائيا جانب الكتابة الخاص به بواسطة التابعend()
، مما يتيح للمستخدم كتابة كميات عشوائية من البيانات. يجب على المستخدم استدعاء end()
صراحةً لإغلاق الاتصال (أي إرسال حزمة FIN مرة أخرى).
الحدث 'error'
أُضيف مع الإصدار: v0.1.90.
- من النوع
<Error>
.
يُطلَق عند حدوث خطأ ما. سيُستدعى الحدث 'close' مباشرة بعد هذا الحدث.
الحدث 'lookup'
سجل التغييرات
الإصدار | التغييرات |
---|---|
v5.10.0 | أصبح المعامل host مدعومًا الآن.
|
v0.11.3 | أضيف مع الإصدار: v0.11.3. |
يُطلَق بعد حل اسم المضيف ولكن قبل الاتصال. لا ينطبق على مقابس UNIX.
err
من النوع <Error>
|<null>
وهو كائن الخطأ. انظرdns.lookup()
.address
من النوع<string>
: وهو عنوان IP.family
من النوع <string>
|<null>
وهو نوع العنوان. انظرdns.lookup()
.host
من النوع<string>
: اسم المضيف.
الحدث 'ready'
أُضيف مع الإصدار: v9.11.0.
يُطلَق عندما يكون مقبس ما على استعداد لاستخدامه.
ويُطلَق فورًا بعد الحدث 'connect'
.
الحدث 'timeout'
أُضيف مع الإصدار: v0.1.90.
يُطلَق إذا انتهت مهلة المقبس نتيجة الخمول. و الغرض منه أن يخطر فقط أن المقبس خامل. يجب على المستخدم إغلاق الاتصال يدويًا.
انظر أيضًا: socket.setTimeout()
.
socket.address()
أُضيف مع الإصدار: v0.1.90.
- القيمة المُعادة: من النوع
<Object>
.
يعيد العنوان address
المنضم واسم عائلة العنوان family
ومنفذ الخادم port
كما يذكره نظام التشغيل. { port: 12346, family: 'IPv4', address: '127.0.0.1' }
socket.bufferSize
أُضيفت مع الإصدار: v0.3.8.
من خواص net.Socket
أن التابع socket.write()
دائما ما يعمل. وهذا لمساعدة المستخدمين للبدء والانطلاق بسرعة. لا يمكن لجهاز الكمبيوتر مواكبة كمية البيانات المكتوبة على المقبس دائماً، فقد يؤدي ببساطة إلى بطء شديد بشبكة الاتصال. وستصُف Node.js البيانات المكتوبة إلى المقبس داخليًا وترسلها عبر الأسلاك عندما يكون ذلك ممكناً. (فهي تختار واصف ملف المقبس داخليا لكونه قابل للكتابة).
وقد تتزايد الذاكرة نتيجة لهذا التخزين الداخلي المؤقت. وتبين هذه الخاصية عدد الأحرف المخزنة حاليا بغرض كتابتها. (عدد الأحرف مساو تقريبا للعدد البايتات المراد كتابتها، ولكن قد يحتوي المخزن المؤقت على سلاسل، والتي ترمَّز ببطء، لذلك لا يمكن معرفة عدد البايتات بالضبط).
يجب أن يحاول المستخدمون الذين يعانون من كِبر أو تزايد bufferSize
"خنق" تدفق البيانات في برامجهم باستخدام socket.pause()
و socket.resume()
.
socket.bytesRead
أضيفت مع الإصدار: v0.5.3.
مقدار وحدات البايت المُتلقاة.
socket.bytesWritten
أضيفت مع الإصدار: v0.5.3.
مقدار وحدات البايت المُرسَلة.
socket.connect()
بدء اتصال مقبس معين.
الأشكال الممكنة:
socket.connect(options[, connectListener])
socket.connect(path[, connectListener])
لاتصالات IPC.socket.connect(port[, host][, connectListener])
لاتصالات TCP.- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
هذه الدالة غير متزامنة. سيطلق الحدث 'connect'
عند تأسيس الاتصال. إذا كان هناك مشكلة في الاتصال سيُطلق الحدث 'error'
بدلا من الحدث 'connect'
ويُمرر مع الخطأ إلى مستمع 'error
'. سيضاف المعامل الأخير connectListener
، إذا توفَّر، كمستمع للحدث 'connect'
مرة واحدة.
socket.connect(options[, connectListener])
سجل التغييرات
الإصدار | التغييرات |
---|---|
v6.0.0 | أصبحت قيمة الخيار hints الافتراضية 0 في كافة الحالات الآن. في السابق، كانت قيمته الافتراضية DNS.ADDRCONFIG | dns.V4MAPPED . في حالة عدم وجود خيار family .
|
v5.11.0 | أصبح الخيار hints مدعومًا الآن.
|
v0.1.90 | أضيف مع الإصدار : v0.1.90. |
options
من النوع<Object>
.connectListener
من النوع<Function>
: وهو معامل شائع لتوابعsocket.connect()
. سيضاف كمستمع للحدث'connect'
مرة واحدة.- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
بدء الاتصال على مقبس معين. لا يستخدم هذا التابع عادةً، وينبغي إنشاء المقبس و فتحه باستخدام net.createConnection()
. وينصح باستخدامه فقط عند تنفيذ مقبس مخصص.
الخيارات المتاحة لاتصالات TCP هي:
port
من النوع<number>
: وهو قيمة يجب إدخالها. وهو المنفذ الذي يجب على المقبس الاتصال به.host
من النوع<string>
: وهو المضيف الذي يجب على المقبس الاتصال به. القيمة الافتراضية:'localhost'
.localAddress
من النوع<string>
: وهو العنوان المحلي الذي يجب على المقبس الاتصال منه.localPort
من النوع<number>
: وهو المنفذ محلي الذي يجب على المقبس الاتصال منه.family
من النوع<number>
: نسخة من مُكدِّس IP، ويمكن أن تكون إما 4 أو 6. القيمة الافتراضية: 4.hints
من النوع<number>
: وهي تلميحات اختيارية حولdns.lookup()
.lookup
من النوع<Function>
وهي دالة البحث المخصص. القيمة الافتراضية:dns.lookup()
.
الخيارات المتاحة لاتصالات IPC هي:
path
من النوع<string>
: وهي قيمة يجب إدخالها. وهو المسار الذي يجب على العميل الاتصال به. راجع تحديد مسارات اتصالات IPC. وإذا توفرت، تُتَجاهَل خيارات TCP الخاصة المذكورة أعلاه.
socket.connect(path[, connectListener])
path
من النوع <string>
: وهو المسار الذي يجب على العميل الاتصال به. راجع تحديد مسارات اتصالات IPC.
connectListener
من النوع <Function>
: وهو معامل شائع لتوابع socket.connect()
. سيضاف كمستمع للحدث 'connect'
مرة واحدة.
- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
بدء اتصال IPC على المقبس المعطى.
اسم مستعار يشير إلى socket.connect(options[, connectListener])
ويستدعى مع الخيار options
بالقيمة { path: path }
.
socket.connect(port[, host][, connectListener])
أُضيف مع الإصدار: v0.1.90.
port
من النوع<string>
: وهو المنفذ الذي يجب على العميل الاتصال به.host
من النوع<string>
: وهو المضيف الذي يجب على العميل الاتصال به.connectListener
من النوع<Function>
وهو معامل شائع لتوابعsocket.connect()
. سيضاف كمستمع للحدث'connect'
مرة واحدة.- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
الشروع في اتصال TCP على المقبس المُعطى.
اسم مستعار يشير إلى socket.connect(options[, connectListener])
ويستدعى مع الخيار options
بالقيمة {port: port, host: host}
.
socket.connecting
أضيفت في: v6.1.0
إذا كان قيمتها true
فهذا يعني استدعاء socket.connect(options[, connectListener])
وأنه لم ينته بعد. وتصبح قيمتها false
قبل انبعاث الحدث 'connect'
و/أو استدعاء دالة رد الاتصال socket.connect(options[, connectListener])
.
socket.destroy([exception])
أُضيف مع الإصدار: v0.1.90.
exception
من النوع <Object>.- القيمة المُعادة: من النوع
<net.Socket>
.
وهو يضمن عدم حدوث أي نشاط إدخال/إخراج على هذا المقبس. ويُعد ضروريا فقط في حالة الأخطاء (خطأ تحليل أو نحو ذلك).
إذا حُدِّد استثناءً exception
، سيُطلق حدث 'error'
وسيتلقى أي مستمع لهذا الحدث exception
كوسيط.
socket.destroyed
من النوع <boolean>
: ويشير إلى ما إذا كان الاتصال قد هُدِم أم لا. بمجرد هدم اتصال لا تُنقل أي بيانات باستخدامه.
socket.end([data][, encoding])
أُضيف مع الإصدار: v0.1.90.
- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
تغلق المُقبس نصفيًا. أي أنه يرسل حزمة FIN. ومن الممكن أن يستمر الخادم في إرسال بعض البيانات.
إذا كانت data
مُحددة، فإن ذلك يكافئ استدعاء socket.write(data, encoding)
يتبعه socket.end()
.
socket.localAddress
أضيفت مع الإصدار: v0.9.6.
وهو التمثيل النصي لعنوان IP المحلي الذي يتصل به العميل البعيد. على سبيل المثال، في خادم الاستماع إلى '0.0.0.0'
، إذا اتصل عميل على '192.168.1.1'
، ستتخذ socket.localAddress
القيمة '192.168.1.1'
.
socket.localPort
أضيفت مع الإصدار: v0.9.6.
التمثيل الرقمي للمنفذ المحلي. على سبيل المثال، 80
أو 21
.
socket.pause()
- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
إيقاف مؤقت لقراءة البيانات. بمعنى عدم إطلاق الأحداث 'data'
. وهو يفيد في خنق التحميل.
socket.ref()
أُضيف مع الإصدار: v0.9.1.
القيمة المُعادة: <net.Socket>
وهو المقبس نفسه.
على عكس unref()
، استدعاء ref()
على خادم سبق إجراء unref
عليه لن يسمح للبرنامج بالانتهاء إذا كان هو الخادم الوحيد المتبقي (السلوك الافتراضي). استدعاء ref()
مرة أخرى على مقبس سبق إجراء ref
عليه لن يكون له أي تأثير.
socket.remoteAddress
أُضيف مع الإصدار: v0.5.10.
التمثيل النصي لعنوان IP البعيد. على سبيل المثال، '74.125.127.100'
أو '2001:4860:a005::68'
. قد تكون القيمة غير معرفة undefined
إذا هُدِم المقبس (على سبيل المثال، إذا قُطع اتصال العميل).
socket.remoteFamily
أُضيفت مع الإصدار: v0.11.14.
التمثيل النصي لعائلة IP البعيد. وتكون إما 'IPv4'
أو 'IPv6'
.
socket.remotePort
أُضيف مع الإصدار: v0.5.10.
التمثيل الرقمي للمنفذ البعيد. على سبيل المثال، 80
أو 21
.
socket.resume()
- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
استئناف القراءة بعد استدعاء socket.pause()
.
socket.setEncoding([encoding])
أُضيف مع الإصدار: v0.1.90.
- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
تعيين ترميز المقبس كدفق مقروء Readable Stream. راجع readable.setEncoding()
لمزيد من المعلومات.
socket.setKeepAlive([enable][, initialDelay])
أضيف مع الإصدار: v0.1.92.
enable
من النوع<boolean>
. القيمة الافتراضية:false
.initialDelay
من النوع<number>
. القيمة الافتراضية:0
.- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
تمكين أو تعطيل وظيفة المحافظة على الحياة، وتعيين التأخير المبدئي قبل إرسال أول تحقق من المحافظة على الحياة (keepalive probe) على مقبس خامل.
ضبط initialDelay
(بالمللي ثانية) لتعيين التأخير بين آخر حزمة بيانات واردة وأول تحقق من المحافظة على الحياة. وسيؤدي ضبط initialDelay
بالقيمة 0
إلى ترك القيمة دون تغيير عن القيمة الافتراضية (أو القيمة السابقة).
socket.setNoDelay([noDelay])
أُضيف مع الإصدار: v0.1.90.
noDelay
من النوع<boolean>
. القيمة الافتراضية:true
.- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
تعطيل خوارزمية Nagle التي تستخدمها اتصالات TCP بشكل افتراضي، فتخزن البيانات مؤقتًا قبل إرسالها. ضبط noDelay
بالقيمة true
يُطلق البيانات فور استدعاء socket.write()
.
socket.setTimeout(timeout[, callback])
أُضيف مع الإصدار: v0.1.90.
- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
ضبط المقبس للانقضاء بعد مهلة timeout
من الخمول على المقبس محسوبًا بالمللي ثانية. بشكل افتراضي لا تملك net.Socket
مهلة للانقضاء.
عند إطلاق مهلة خمول، يتلقى المقبس حدث 'timeout'
ولكن لن ينقطع الاتصال. يجب على المستخدم استدعاء socket.end()
أو socket.destroy()
يدوياً لإنهاء الاتصال.
socket.setTimeout(3000);
socket.on('timeout', () => {
console.log('socket timeout');
socket.end();
});
إذا كانت timeout
تساوي 0
، تتعطل مهلة الخمول الحالية.
يضاف المعامل callback
الاختياري كمستمع لمرة واحدة لحدث 'timeout'
.
socket.unref()
أُضيف مع الإصدار: v0.9.1.
- القيمة المُعادة:
<net.Socket>
وهو المقبس نفسه.
يسمح استدعاء unref()
على مقبسٍ ما للبرنامج بالإنهاء إذا كان هو المقبس النشط الوحيد في نظام الأحداث. استدعاء unref()
مرة أخرى على مقبس سبق إجراء unref
عليه لن يكون له أي تأثير.
socket.write(data[, encoding][, callback])
أُضيف مع الإصدار: v0.1.90.
data
من النوع <string>
|<Buffer>
|<Uint8Array>
.encoding
من النوع<string>
: وتستخدم فقط عندما تكونdata
من النوعstring
. القيمة الافتراضية:utf8
.callback
من النوع<Function>
.- القيمة المُعادة: من النوع
<boolean>
.
إرسال البيانات على مقبس. ويحدد المعامل الثاني الترميز في حالة أن تكون البيانات سلسلة — ويكون الترميز UTF8 في الوضع الافتراضي.
ويعيد true
إذا انتقلت البيانات بالكامل بنجاح إلى مخزن النواة المؤقت (kernel buffer). ويعيد false
إذا كان كل أو جزء من البيانات في قائمة الانتظار في ذاكرة المستخدم. ويُطلق الحدث 'drain' عندما يكون المحزن المؤقت متاحًا مرة أخرى.
وسينفذ معامل رد الاتصال callback
الاختياري عند الانتهاء من كتابة البيانات خارجًا--وقد لا حدث هذا فورًا.
راجع التابع write()
وهو تابع التيار القابل للكتابة Writable
Stream للحصول على مزيد من المعلومات.
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.
الاسم المستعار للتابع net.createConnection(options[, connectListener])
.
net.connect(path[, connectListener])
أُضيف مع الإصدار: v0.1.90.
الاسم المستعار للتابع net.createConnection(path[, connectListener])
.
net.connect(port[, host][, connectListener])
أُضيف مع الإصدار: v0.1.90.
الاسم المستعار للتابع 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)
بعد إنشاء مقبس، ولكن قبل أن يبدأ الاتصال.
فيما يلي مثال لعميل خادم صدى (echo server) الموصوف في قسم ()net.createServer
:
const net = require('net');
const client = net.createConnection({ port: 8124 }, () => {
// 'connect' مستمع
console.log('التوصيل مع الخادم!');
client.write('أيها العالم!\r\n');
});
client.on('data', (data) => {
console.log(data.toString());
client.end();
});
client.on('end', () => {
console.log('قطع الإتصال مع الخادم');
});
للاتصال على المقبس /tmp/echo.sock
يجب تغيير السطر الثاني فقط إلى:
const client = net.createConnection({ path: '/tmp/echo.sock' });
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(path[, connectListener])
.- القيمة المُعادة:
<net.Socket>
وهو المقبس المُنشأ حديثا والمستخدم لبدء الاتصال.
يبدأ اتصال TCP.
تُنشئ هذه الدالة net.Socket
مع جميع الخيارات مضبوطة بالقيم الافتراضية، وتبدأ الاتصال مع socket.connect(port[, host][, connectListener])
على الفور، ثم تعيد net.Socket
والذي يبدأ الاتصال.
net.createServer([options][, connectionListener])
أُضيف مع الإصدار: v0.5.0.
إنشاء خادم TCP أو IPC جديد.
options
من النوع<Object>
.allowHalfOpen
من النوع<boolean>
: وهو يشير إلى ما إذا كان مسموح باتصالات TCP مفتوحة نصفيا. القيمة الافتراضية:false
.pauseOnConnect
من النوع<boolean>
: وهو يحدد ما إذا كان يجب إيقاف المقبس مؤقتا عن الاتصالات الواردة .القيمة الافتراضية:false
.connectionListener
من النوع<Function>
: وهو يضبط مستمع للحدث'connection'
تلقائيا.- القيمة المُعادة: من النوع
<net.Server>
.
إذا ضُبط allowHalfOpen
بالقيمة true
عندما يرسل الطرف الآخر من المقبس حزمة FIN، يرسل الخادم حزمة FIN فقط عند استدعاء socket.end()
صراحة وحتى هذا الحين يكون الاتصال مغلقًا نصفيًا (غير مقروء ولكن لا يزال قابل للكتابة). انظر الحدث 'end'
و RFC 1122 (القسم 4.2.2.13) لمزيد من المعلومات.
إذا ضُبط pauseOnConnect
بالقيمة true
، سيتوقف المقبس المرتبط مع كل اتصال وارد مؤقتا، ولن تُقرأ أي بيانات من معالجها. ويسمح هذا للاتصالات بالمرور بين العمليات دون قراءة أي بيانات من قِبَل العملية الأصلية. للبدء في قراءة البيانات من مقبس متوقف مؤقتاً، يجب استدعاء socket.resume()
.
يمكن أن يكون الخادم TCP أو IPC اعتماداً على ما يستمع إليه بواسطة listen()
.
إليك مثال على صدى خادم TCP والذي يستمع للاتصالات على المنفذ 8124:
const net = require('net');
const server = net.createServer((c) => {
// 'connection' مستمع
console.log('إتصال العميل');
c.on('end', () => {
console.log('قطع إتصال العميل');
});
c.write('مرحبًا\r\n');
c.pipe(c);
});
server.on('error', (err) => {
throw err;
});
server.listen(8124, () => {
console.log('الخادم مرتبط');
});
اختبر هذا باستخدام telnet:
$ telnet localhost 8124
للاستماع على المقبس /tmp/echo.sock
يجب تغيير السطر الثالث من النهاية فقط إلى:
server.listen('/tmp/echo.sock', () => {
console.log('الخادم مرتبط');
});
ويستخدم nc
للاتصال بخادم مقبس مجال UNIX:
$ nc -U /tmp/echo.sock
net.isIP(input)
أُضيف مع الإصدار: v0.3.0.
- القيمة المُعادة: من النوع
<integer>
.
تُعيد الاختبارات إذا كان المُدخَل عنوان IP القيمة 0
للسلاسل النصية غير الصالحة، و 4
لعناوين IP من الإصدار 4 و 6
لعناوين IP من الإصدار 6.
net.isIPv4(input)
أُضيف مع الإصدار: v0.3.0.
- القيمة المُعادة: من النوع
<boolean>
تُعيد true
في حالة إدخال عنوان IP من الإصدار 4، وإلا سيُعيد false
.
net.isIPv6(input)
أُضيف مع الإصدار: v0.3.0.
- القيمة المُعادة: من النوع
<boolean>
.
تُعيد true
في حالة إدخال عنوان IP من الإصدار 6، وإلا سيُعيد false
.