chrome.sockets.tcp

الوصف

استخدِم واجهة برمجة التطبيقات chrome.sockets.tcp لإرسال البيانات وتلقّيها عبر الشبكة باستخدام اتصالات TCP. تحلّ واجهة برمجة التطبيقات هذه محلّ وظيفة TCP التي كانت متوفّرة سابقًا في واجهة برمجة التطبيقات chrome.socket.

البيان

يجب الإعلان عن المفاتيح التالية في ملف البيان لاستخدام واجهة برمجة التطبيقات هذه.

"sockets"

الأنواع

CreateInfo

الخصائص

  • socketId

    الرقم

    رقم تعريف المقبس الذي تم إنشاؤه حديثًا يُرجى العِلم أنّ أرقام تعريف المقابس التي تم إنشاؤها من واجهة برمجة التطبيقات هذه غير متوافقة مع أرقام تعريف المقابس التي تم إنشاؤها من واجهات برمجة تطبيقات أخرى، مثل واجهة برمجة التطبيقات [socket](../socket/) المتوقفة نهائيًا.

DnsQueryType

الإصدار 103 من Chrome أو الإصدارات الأحدث

تفضيلات التحويل باستخدام نظام أسماء النطاقات (DNS) الإعداد التلقائي هو any ويستخدم إعدادات نظام التشغيل الحالية التي قد تعرض IPv4 أو IPv6. يفرض ipv4 استخدام IPv4، بينما يفرض ipv6 استخدام IPv6.

Enum

"any"

"ipv4"

"ipv6"

ReceiveErrorInfo

الخصائص

  • resultCode

    الرقم

    رمز النتيجة الذي تم إرجاعه من طلب الشبكة الأساسي

  • socketId

    الرقم

    معرّف المقبس

ReceiveInfo

الخصائص

  • البيانات

    ArrayBuffer

    البيانات التي تم تلقّيها، بحد أقصى يبلغ bufferSize.

  • socketId

    الرقم

    معرّف المقبس

SecureOptions

الخصائص

SendInfo

الخصائص

  • bytesSent

    number اختيارية

    عدد وحدات البايت المُرسَلة (إذا كانت النتيجة == 0)

  • resultCode

    الرقم

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

SocketInfo

الخصائص

  • bufferSize

    number اختيارية

    حجم المخزن المؤقت المستخدَم لتلقّي البيانات إذا لم يتم تحديد حجم ذاكرة التخزين المؤقت بشكل صريح، لن يتم توفير القيمة.

  • تم الربط

    قيمة منطقية

    علامة تشير إلى ما إذا كان المقبس متصلاً بنظير عن بُعد

  • localAddress

    string اختياري

    إذا كان المقبس الأساسي متصلاً، يحتوي على عنوان IPv4/6 المحلي.

  • localPort

    number اختيارية

    إذا كان المقبس الأساسي متصلاً، يحتوي على المنفذ المحلي.

  • الاسم

    string اختياري

    سلسلة يحدّدها التطبيق مرتبطة بالمقبس.

  • متوقفة مؤقتًا

    قيمة منطقية

    علامة تشير إلى ما إذا كان المقبس المتصل يمنع نظيره من إرسال المزيد من البيانات (راجِع setPaused).

  • peerAddress

    string اختياري

    إذا كان المقبس الأساسي متصلاً، يحتوي على عنوان IPv4/6/النظير.

  • peerPort

    number اختيارية

    إذا كان المقبس الأساسي متصلاً، يحتوي على منفذ النظير.

  • ثابتة

    قيمة منطقية

    علامة تشير إلى ما إذا كان المقبس سيُترك مفتوحًا عند تعليق التطبيق (يُرجى الاطّلاع على SocketProperties.persistent).

  • socketId

    الرقم

    معرّف المقبس

SocketProperties

الخصائص

  • bufferSize

    number اختيارية

    حجم المخزن المؤقت المستخدَم لتلقّي البيانات القيمة التلقائية هي 4096.

  • الاسم

    string اختياري

    سلسلة يحدّدها التطبيق ومرتبطة بالمقبس.

  • ثابتة

    قيمة منطقية اختيارية

    علامة تشير إلى ما إذا كان المقبس مفتوحًا عند إلغاء تحميل صفحة الحدث في التطبيق (راجِع إدارة مراحل نشاط التطبيق). القيمة التلقائية هي "false". عند تحميل التطبيق، يمكن جلب أي مآخذ تم فتحها سابقًا باستخدام persistent=true من خلال getSockets.

TLSVersionConstraints

الخصائص

  • الحد الأقصى

    string اختياري

  • دقيقة

    string اختياري

    الحدّ الأدنى والحدّ الأقصى لإصدارات بروتوكول أمان طبقة النقل (TLS) المقبولة والقيمتان المسموح بإدراجهما هما tls1.2 أو tls1.3.

    لم تعُد القيمتان tls1 وtls1.1 متاحتَين. إذا تم ضبط min على إحدى هذه القيم، سيتم تقريبها تلقائيًا إلى tls1.2. إذا تم ضبط max على إحدى هذه القيم أو أي قيمة أخرى غير معروفة، سيتم تجاهلها بدون إشعار.

الطُرق

close()

Promise 
chrome.sockets.tcp.close(
  socketId: number,
  callback?: function,
): Promise<void>

يغلق المقبس ويحرر العنوان/المنفذ الذي يرتبط به المقبس. يجب إغلاق كل مقبس تم إنشاؤه بعد الاستخدام. لم يعُد معرّف المقبس صالحًا فور استدعاء الدالة. ومع ذلك، نضمن إغلاق المقبس فقط عند استدعاء دالة الاستدعاء.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعد<فراغ>

    الإصدار 121 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

connect()

chrome.sockets.tcp.connect(
  socketId: number,
  peerAddress: string,
  peerPort: number,
  dnsQueryType?: DnsQueryType,
  callback: function,
): void

لربط المقبس بجهاز بعيد عند اكتمال عملية connect بنجاح، يتم إنشاء أحداث onReceive عند تلقّي البيانات من النظير. في حال حدوث خطأ في الشبكة أثناء تلقّي وقت التشغيل للحزم، يتم إنشاء حدث onReceiveError، وعند هذه النقطة لن يتم إنشاء أي حدث onReceive آخر لهذا المقبس إلى أن يتم استدعاء طريقة resume.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • peerAddress

    سلسلة

    عنوان الجهاز البعيد تتوفّر تنسيقات اسم نظام أسماء النطاقات وIPv4 وIPv6.

  • peerPort

    الرقم

    منفذ الجهاز البعيد

  • dnsQueryType

    DnsQueryType اختياري

    الإصدار 103 من Chrome أو الإصدارات الأحدث

    الإعداد المفضّل لدقة العناوين

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (result: number) => void

    • نتيجة

      الرقم

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

create()

Promise 
chrome.sockets.tcp.create(
  properties?: SocketProperties,
  callback?: function,
): Promise<CreateInfo>

لإنشاء مقبس توصيل TCP

المعلمات

  • أماكن الإقامة

    SocketProperties اختيارية

    سمات المقبس (اختيارية)

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      نتيجة إنشاء المقبس

المرتجعات

  • Promise<CreateInfo>

    الإصدار 121 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

disconnect()

Promise 
chrome.sockets.tcp.disconnect(
  socketId: number,
  callback?: function,
): Promise<void>

لإلغاء ربط المقبس

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعد<فراغ>

    الإصدار 121 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getInfo()

Promise 
chrome.sockets.tcp.getInfo(
  socketId: number,
  callback?: function,
): Promise<SocketInfo>

تسترد هذه الدالة حالة المقبس المحدّد.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      عنصر يحتوي على معلومات المقبس

المرتجعات

  • Promise<SocketInfo>

    الإصدار 121 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getSockets()

Promise 
chrome.sockets.tcp.getSockets(
  callback?: function,
): Promise<SocketInfo[]>

يتم استرداد قائمة بمقابس الاتصال المفتوحة حاليًا والتي يملكها التطبيق.

المعلمات

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

      مصفوفة من العناصر التي تحتوي على معلومات المقبس

المرتجعات

  • Promise<SocketInfo[]>

    الإصدار 121 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

secure()

chrome.sockets.tcp.secure(
  socketId: number,
  options?: SecureOptions,
  callback: function,
): void

ابدأ اتصال عميل بروتوكول أمان طبقة النقل (TLS) عبر مقبس جهاز عميل بروتوكول التحكّم بالنقل (TCP) المتصل.

المعلمات

  • socketId

    الرقم

    المقبس الحالي المتصل المطلوب استخدامه

  • الخيارات

    SecureOptions اختياري

    القيود والمعلَمات الخاصة باتصال بروتوكول أمان طبقة النقل (TLS)

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (result: number) => void

    • نتيجة

      الرقم

send()

chrome.sockets.tcp.send(
  socketId: number,
  data: ArrayBuffer,
  callback: function,
): void

يرسل البيانات على مقبس TCP المحدّد.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • البيانات

    ArrayBuffer

    البيانات المطلوب إرسالها

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      نتيجة طريقة send

setKeepAlive()

chrome.sockets.tcp.setKeepAlive(
  socketId: number,
  enable: boolean,
  delay?: number,
  callback: function,
): void

تتيح هذه السياسة تفعيل وظيفة الإبقاء على الاتصال أو إيقافها لاتصال TCP.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • تفعيل

    قيمة منطقية

    في حال ضبطها على "صحيح"، يتم تفعيل وظيفة "إبقاء الاتصال نشطًا".

  • تأخير

    number اختيارية

    يمكنك ضبط ثواني التأخير بين آخر حزمة بيانات تم استلامها وأول فحص للحفاظ على الاتصال. القيمة التلقائية هي 0.

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (result: number) => void

    • نتيجة

      الرقم

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

setNoDelay()

chrome.sockets.tcp.setNoDelay(
  socketId: number,
  noDelay: boolean,
  callback: function,
): void

لضبط TCP_NODELAY أو محوه لاتصال TCP. سيتم إيقاف خوارزمية Nagle عند ضبط السياسة TCP_NODELAY.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • noDelay

    قيمة منطقية

    إذا كانت القيمة "صحيح"، يتم إيقاف خوارزمية Nagle.

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (result: number) => void

    • نتيجة

      الرقم

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

setPaused()

Promise 
chrome.sockets.tcp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
): Promise<void>

يتيح هذا الإعداد للتطبيق تلقّي الرسائل من التطبيق النظير أو يمنعه من ذلك. القيمة التلقائية هي "false". يستخدم التطبيق عادةً ميزة إيقاف المقبس مؤقتًا لتقييد البيانات التي يرسلها الطرف الآخر. عند إيقاف مأخذ مؤقتًا، لا يتم إنشاء أي حدث onReceive. عندما يكون المقبس متصلاً وغير متوقف مؤقتًا، يتم رفع أحداث onReceive مرة أخرى عند تلقّي الرسائل.

المعلمات

  • socketId

    الرقم

  • متوقفة مؤقتًا

    قيمة منطقية

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعد<فراغ>

    الإصدار 121 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

update()

Promise 
chrome.sockets.tcp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
): Promise<void>

يتيح هذا الإذن تعديل خصائص المقبس.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • أماكن الإقامة

    SocketProperties

    السمات المطلوب تعديلها

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعد<فراغ>

    الإصدار 121 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

الفعاليات

onReceive

chrome.sockets.tcp.onReceive.addListener(
  callback: function,
)

يتم إنشاء الحدث عند تلقّي بيانات لمقبس معيّن.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (info: ReceiveInfo) => void

onReceiveError

chrome.sockets.tcp.onReceiveError.addListener(
  callback: function,
)

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

المعلمات