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

    number اختيارية

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

  • resultCode

    الرقم

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

SocketInfo

الخصائص

  • bufferSize

    number اختيارية

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

  • localAddress

    string اختياري

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

  • localPort

    number اختيارية

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

  • الاسم

    string اختياري

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

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

    قيمة منطقية

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

  • ثابتة

    قيمة منطقية

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

  • socketId

    الرقم

    معرّف المقبس

SocketProperties

الخصائص

  • bufferSize

    number اختيارية

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

  • الاسم

    string اختياري

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

  • ثابتة

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

    علامة تشير إلى ما إذا كان المقبس مفتوحًا عند إلغاء تحميل صفحة الحدث في التطبيق (راجِع إدارة مراحل نشاط التطبيق). القيمة التلقائية هي "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()

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

create()

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

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

المعلمات

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

    SocketProperties اختيارية

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

  • callback

    function اختياري

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

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

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

المرتجعات

  • Promise<CreateInfo>

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

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

getInfo()

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • callback

    function اختياري

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

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

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

المرتجعات

  • Promise<SocketInfo>

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

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

getJoinedGroups()

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • callback

    function اختياري

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

    (groups: string[]) => void

    • مجموعات

      string[]

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

المرتجعات

  • وعد<سلسلة نصية[]>

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

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

getSockets()

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

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

المعلمات

  • callback

    function اختياري

    تظهر المَعلمة 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()

الإصدار 44 من Chrome أو الإصدارات الأحدث 
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

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

  • ttl

    الرقم

    قيمة مدة الصلاحية

  • callback

    دالة

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

    (result: number) => void

    • نتيجة

      الرقم

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

setPaused()

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

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

    قيمة منطقية

    علامة تشير إلى ما إذا كان يجب إيقاف الإعلان مؤقتًا أو استئنافه

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

update()

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

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

المعلمات

  • socketId

    الرقم

    معرّف المقبس

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

    SocketProperties

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

  • callback

    function اختياري

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

    () => 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 أخرى لهذا المقبس إلى أن يتم استئنافه.

المعلمات