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.

تعداد

"any"

"ipv4"

"ipv6"

ReceiveErrorInfo

الخصائص

  • resultCode

    الرقم

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

  • socketId

    الرقم

    معرّف المقبس

ReceiveInfo

الخصائص

  • البيانات

    ArrayBuffer

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

  • remoteAddress

    سلسلة

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

  • remotePort

    الرقم

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

  • socketId

    الرقم

    معرّف المقبس

SendInfo

الخصائص

  • bytesSent

    number اختياري

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

  • resultCode

    الرقم

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

SocketInfo

الخصائص

  • bufferSize

    number اختياري

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

  • localAddress

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

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

  • localPort

    number اختياري

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

  • الاسم

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

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

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

    قيمة منطقية

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

  • مستمر

    قيمة منطقية

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

  • socketId

    الرقم

    معرّف المقبس

SocketProperties

الخصائص

  • bufferSize

    number اختياري

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

  • الاسم

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

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

  • مستمر

    boolean اختياري

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

الطُرق

bind()

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

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • معالجة

    سلسلة

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

  • المنفذ

    الرقم

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

  • callback

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

close()

وعد 
chrome.sockets.udp.close(
  socketId: number,
  callback?: function,
): Promise<void>

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

create()

وعد 
chrome.sockets.udp.create(
  properties?: SocketProperties,
  callback?: function,
): Promise<CreateInfo>

تُنشئ هذه الطريقة مقبس UDP بالخصائص المحدّدة.

المعلمات

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

    SocketProperties اختيارية

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

  • callback

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

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

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

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

المرتجعات

  • Promise<CreateInfo>

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

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

getInfo()

وعد 
chrome.sockets.udp.getInfo(
  socketId: number,
  callback?: function,
): Promise<SocketInfo>

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • callback

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

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

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

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

المرتجعات

  • Promise<SocketInfo>

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

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

getJoinedGroups()

وعد 
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
): Promise<string[]>

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • callback

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

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

    (groups: string[]) => void

    • مجموعات

      string[]

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

المرتجعات

  • Promise<string[]>

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

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

getSockets()

وعد 
chrome.sockets.udp.getSockets(
  callback?: function,
): Promise<SocketInfo[]>

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

المعلمات

  • callback

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

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

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

المرتجعات

  • Promise<SocketInfo[]>

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

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

joinGroup()

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • معالجة

    سلسلة

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

  • callback

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

leaveGroup()

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

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • معالجة

    سلسلة

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

  • callback

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

send()

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • البيانات

    ArrayBuffer

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

  • معالجة

    سلسلة

    تمثّل هذه السمة عنوان الجهاز البعيد.

  • المنفذ

    الرقم

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

  • dnsQueryType

    DnsQueryType اختياري

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

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

  • callback

    دالة

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

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

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

setBroadcast()

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • مفعّلة

    قيمة منطقية

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

  • callback

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

setMulticastLoopbackMode()

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

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

ملاحظة: يختلف سلوك setMulticastLoopbackMode قليلاً بين أنظمة التشغيل Windows والأنظمة المشابهة لنظام التشغيل Unix. لا يحدث عدم الاتساق إلا عندما يكون هناك أكثر من تطبيق واحد على المضيف نفسه منضمًا إلى مجموعة البث المتعدد نفسها مع إعدادات مختلفة في وضع إعادة توجيه البث المتعدد. في نظام التشغيل Windows، لن تتلقّى التطبيقات التي تم إيقاف تشغيل ميزة "التوجيه الحلقي" فيها حِزم التوجيه الحلقي، بينما في الأنظمة الشبيهة بنظام التشغيل Unix، لن تُرسِل التطبيقات التي تم إيقاف تشغيل ميزة "التوجيه الحلقي" فيها حِزم التوجيه الحلقي إلى تطبيقات أخرى على المضيف نفسه. يُرجى الاطّلاع على MSDN: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

لا يتطلّب استدعاء هذا الإجراء أذونات البث المتعدد.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • مفعّلة

    قيمة منطقية

    تحديد ما إذا كان سيتم تفعيل وضع إعادة التوجيه.

  • callback

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

setMulticastTimeToLive()

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

تضبط هذه السمة مدة البقاء (TTL) لحِزم البث المتعدد المُرسَلة إلى مجموعة البث المتعدد.

لا يتطلّب استدعاء هذا الإجراء أذونات البث المتعدد.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • ttl

    الرقم

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

  • callback

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

setPaused()

وعد 
chrome.sockets.udp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
): Promise<void>

توقِف مؤقتًا أو تستأنِف مقبسًا. يتم حظر المقبس المتوقّف مؤقتًا من إطلاق أحداث onReceive.

المعلمات

  • socketId

    الرقم

    معرّف المقبس

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

    قيمة منطقية

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

update()

وعد 
chrome.sockets.udp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
): Promise<void>

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

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

    SocketProperties

    الخصائص المطلوب تعديلها

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

الفعاليات

onReceive

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

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

المعلمات

  • callback

    دالة

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

    (info: ReceiveInfo) => void

onReceiveError

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

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

المعلمات