chrome.sockets.udp

الوصف

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

البيان

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

"sockets"

الأنواع

CreateInfo

الخصائص

  • socketId

    الرقم

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

DnsQueryType

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

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

Enum

"any"

"ipv4"

"ipv6"

ReceiveErrorInfo

الخصائص

  • resultCode

    الرقم

    رمز النتيجة الذي تم إرجاعه من طلب recvfrom() الأساسي

  • socketId

    الرقم

    معرّف المقبس

ReceiveInfo

الخصائص

  • البيانات

    ArrayBuffer

    محتوى حزمة UDP (يتم اقتطاعه ليصل إلى حجم ذاكرة التخزين المؤقت الحالية).

  • remoteAddress

    سلسلة

    عنوان المضيف الذي تأتي منه الحزمة

  • remotePort

    الرقم

    منفذ المضيف الذي تأتي منه الحزمة

  • socketId

    الرقم

    معرّف المقبس

SendInfo

الخصائص

  • bytesSent

    رقم اختياري

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

  • resultCode

    الرقم

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

SocketInfo

الخصائص

  • bufferSize

    رقم اختياري

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

  • localAddress

    سلسلة اختيارية

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

  • localPort

    رقم اختياري

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

  • الاسم

    سلسلة اختيارية

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

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

    قيمة منطقية

    علامة تشير إلى ما إذا كان قد تم حظر المقبس من تنشيط أحداث onReceive

  • دائمة

    قيمة منطقية

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

  • socketId

    الرقم

    معرّف المقبس

SocketProperties

الخصائص

  • bufferSize

    رقم اختياري

    حجم المخزن المؤقت المستخدَم لتلقّي البيانات إذا كان المخزن المؤقت صغيرًا جدًا لتلقّي حزمة بروتوكول حزم بيانات المستخدم (UDP)، يتم فقدان البيانات. القيمة التلقائية هي 4096.

  • الاسم

    سلسلة اختيارية

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

  • دائمة

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

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

الطُرق

bind()

chrome.sockets.udp.bind(
  socketId: number,
  address: string,
  port: number,
  callback: function,
)

ربط العنوان المحلي والمنفذ بالمقبس بالنسبة إلى مقبس العميل، يُنصح باستخدام المنفذ 0 للسماح للمنصة باختيار منفذ مجاني.

بعد اكتمال عملية bind بنجاح، يتمّ رفع أحداث onReceive عند وصول حزم UDP إلى العنوان/المنفذ المحدّد، ما لم يتمّ إيقاف المقبس مؤقتًا.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • معالجة

    سلسلة

    عنوان الجهاز المحلي تتوفّر تنسيقات أسماء نظام أسماء النطاقات وIPv4 وIPv6. استخدِم "0.0.0.0" لقبول الحِزم من جميع واجهات الشبكة المحلية المتاحة.

  • المنفذ

    الرقم

    منفذ الجهاز المحلي استخدِم "0" للربط بمنفذ مجاني.

  • ردّ الاتصال

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

close()

الوعد 
chrome.sockets.udp.close(
  socketId: number,
  callback?: function,
)

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • ردّ الاتصال

    دالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

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

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

create()

الوعد 
chrome.sockets.udp.create(
  properties?: SocketProperties,
  callback?: function,
)

تُنشئ مقبس UDP بالخصائص المحدّدة.

المعلمات

  • المواقع

    SocketProperties اختيارية

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

  • ردّ الاتصال

    دالة اختيارية

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

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

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

المرتجعات

  • Promise<CreateInfo>

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

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

getInfo()

الوعد 
chrome.sockets.udp.getInfo(
  socketId: number,
  callback?: function,
)

تسترجع حالة المقبس المحدّد.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • ردّ الاتصال

    دالة اختيارية

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

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

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

المرتجعات

  • Promise<SocketInfo>

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

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

getJoinedGroups()

الوعد 
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
)

تحصل على عناوين مجموعة البث المتعدد التي انضم إليها المقبس حاليًا.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • ردّ الاتصال

    دالة اختيارية

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

    (groups: string[]) => void

    • مجموعات

      string[]

      صفيف من المجموعات التي انضم إليها المقبس

المرتجعات

  • Promise<string[]>

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

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

getSockets()

الوعد 
chrome.sockets.udp.getSockets(
  callback?: function,
)

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

المعلمات

  • ردّ الاتصال

    دالة اختيارية

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

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

المرتجعات

  • Promise<SocketInfo[]>

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

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

joinGroup()

chrome.sockets.udp.joinGroup(
  socketId: number,
  address: string,
  callback: function,
)

ينضم إلى مجموعة البث المتعدد ويبدأ في تلقّي الحِزم من تلك المجموعة. يجب ربط المقبس بمنفذ محلي قبل استدعاء هذه الطريقة.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • معالجة

    سلسلة

    عنوان المجموعة المطلوب الانضمام إليها. لا تتوفّر أسماء النطاقات.

  • ردّ الاتصال

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

leaveGroup()

chrome.sockets.udp.leaveGroup(
  socketId: number,
  address: string,
  callback: function,
)

يغادر مجموعة البث المتعدد التي انضم إليها سابقًا باستخدام joinGroup. لا يلزم الاتصال بهذه الوظيفة إلا إذا كنت تخطّط لمواصلة استخدام المقبس بعد ذلك، لأنّ نظام التشغيل سيتولى إغلاق المقبس تلقائيًا.

سيؤدي مغادرة المجموعة إلى منع جهاز التوجيه من إرسال حزم بيانات البث المتعدد إلى المضيف المحلي، بافتراض أنّه لم تعد هناك عملية أخرى على المضيف لا تزال مرتبطة بالمجموعة.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • معالجة

    سلسلة

    عنوان المجموعة المطلوب مغادرتها لا تتوفّر أسماء النطاقات.

  • ردّ الاتصال

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

send()

chrome.sockets.udp.send(
  socketId: number,
  data: ArrayBuffer,
  address: string,
  port: number,
  dnsQueryType?: DnsQueryType,
  callback: function,
)

تُرسِل البيانات في المقبس المحدّد إلى العنوان والمنفذ المحدّدَين. يجب ربط المقبس بمنفذ محلي قبل استدعاء هذه الطريقة.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • البيانات

    ArrayBuffer

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

  • معالجة

    سلسلة

    عنوان الجهاز البعيد

  • المنفذ

    الرقم

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

  • dnsQueryType

    ‫DnsQueryType اختياري

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

    الإعداد المفضّل لتحليل العنوان

  • ردّ الاتصال

    دالة

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

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      نتيجة الطريقة send

setBroadcast()

Chrome 44 والإصدارات الأحدث 
chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
)

تفعيل حزم البث أو إيقافها على هذا المقبس

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • مفعّلة

    قيمة منطقية

    true لتفعيل حزم البث، false لإيقافها.

  • ردّ الاتصال

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

setMulticastLoopbackMode()

chrome.sockets.udp.setMulticastLoopbackMode(
  socketId: number,
  enabled: boolean,
  callback: function,
)

لضبط ما إذا كان سيتم تكرار حزم البث المتعدد المُرسَلة من المضيف إلى مجموعة البث المتعدد مرة أخرى إلى المضيف.

ملاحظة: يختلف سلوك setMulticastLoopbackMode قليلاً بين نظامَي التشغيل Windows وUnix. ولا يحدث هذا التناقض إلا عندما يكون هناك أكثر من تطبيق واحد على المضيف نفسه ينضم إلى مجموعة البث المتعدد نفسها مع ضبط إعدادات مختلفة في وضع إعادة توجيه البث المتعدد. في نظام التشغيل Windows، لن تتلقّى التطبيقات التي تم إيقاف ميزة "الحلقة المغلقة" فيها حزم "الحلقة المغلقة"، بينما في الأنظمة المشابهة لنظام التشغيل Unix، لن ترسل التطبيقات التي تم إيقاف ميزة "الحلقة المغلقة" فيها حزم "الحلقة المغلقة" إلى التطبيقات الأخرى على المضيف نفسه. راجِع MSDN: http://goo.gl/6vqbj.

لا يتطلب استدعاء هذه الطريقة أذونات البث المتعدد.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • مفعّلة

    قيمة منطقية

    حدِّد ما إذا كنت تريد تفعيل وضع "الحلقة المغلقة".

  • ردّ الاتصال

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

setMulticastTimeToLive()

chrome.sockets.udp.setMulticastTimeToLive(
  socketId: number,
  ttl: number,
  callback: function,
)

لضبط وقت انتهاء صلاحية حِزم البث المتعدّد المُرسَلة إلى مجموعة البث المتعدّد.

لا يتطلب استدعاء هذه الطريقة أذونات البث المتعدد.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • ttl

    الرقم

    قيمة مدة البقاء

  • ردّ الاتصال

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

setPaused()

الوعد 
chrome.sockets.udp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
)

يوقف مقبسًا مؤقتًا أو يُلغي إيقافه المؤقت. يتم حظر مقبس متوقّف مؤقتًا من بدء أحداث onReceive.

المعلمات

  • socketId

    الرقم

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

    قيمة منطقية

    علامة للإشارة إلى ما إذا كان سيتم إيقاف المحتوى مؤقتًا أو إلغاء الإيقاف المؤقت

  • ردّ الاتصال

    دالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

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

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

update()

الوعد 
chrome.sockets.udp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
)

تعديل خصائص المقبس

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • المواقع

    SocketProperties

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

  • ردّ الاتصال

    دالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

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

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

الفعاليات

onReceive

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

يتمّ رفع هذا الحدث عند استلام حزمة UDP للمقبس المحدّد.

المعلمات

  • ردّ الاتصال

    دالة

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

    (info: ReceiveInfo) => void

onReceiveError

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

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

المعلمات

  • ردّ الاتصال

    دالة

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

    (info: ReceiveErrorInfo) => void