chrome.sockets.udp

الوصف

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

البيان

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

"sockets"

الأنواع

CreateInfo

أماكن إقامة

  • socketId

    الرقم

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

DnsQueryType

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

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

التعداد

"ipv4"

"ipv6"

ReceiveErrorInfo

أماكن إقامة

  • resultCode

    الرقم

    رمز النتيجة الذي يتم عرضه من استدعاء recvfrom() الأساسي.

  • socketId

    الرقم

    معرّف المقبس.

ReceiveInfo

أماكن إقامة

  • البيانات

    ArrayBuffer

    محتوى حزمة UDP (تم اقتطاعه حسب حجم المخزن المؤقت الحالي)

  • remoteAddress

    سلسلة

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

  • remotePort

    الرقم

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

  • socketId

    الرقم

    معرّف المقبس.

SendInfo

أماكن إقامة

  • bytesSent

    الرقم اختياري

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

  • resultCode

    الرقم

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

SocketInfo

أماكن إقامة

  • bufferSize

    الرقم اختياري

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

  • localAddress

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

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

  • localPort

    الرقم اختياري

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

  • اسم

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

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

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

    boolean

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

  • ثابت

    boolean

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

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

create()

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

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

المَعلمات

  • المواقع

    SocketProperties اختيارية

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (createInfo: CreateInfo)=>void

    • createInfo

      CreateInfo

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

المرتجعات

  • Promise<CreateInfo>

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

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

getInfo()

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

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

المَعلمات

  • socketId

    الرقم

    معرّف المقبس.

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (socketInfo: SocketInfo)=>void

    • socketInfo

      SocketInfo

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

المرتجعات

  • Promise<SocketInfo>

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

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

getJoinedGroups()

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

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

المَعلمات

  • socketId

    الرقم

    معرّف المقبس.

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (groups: string[])=>void

    • مجموعات

      سلسلة[]

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

المرتجعات

  • وعد<string[]>

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

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

getSockets()

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

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (socketInfos: SocketInfo[])=>void

    • socketInfos

      SocketInfo[]

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

المرتجعات

  • Promise<SocketInfo[]>

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

    لا تتوفّر الوعود إلا في الإصدار 3 من 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 اختيارية

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

    تفضيل دقة العنوان

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (sendInfo: SendInfo)=>void

    • sendInfo

      SendInfo

      نتيجة طريقة send.

setBroadcast()

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

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

المَعلمات

  • socketId

    الرقم

    معرّف المقبس.

  • مفعّلة

    boolean

    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

    الرقم

    معرّف المقبس.

  • مفعّلة

    boolean

    حدِّد ما إذا كنت تريد تفعيل وضع الاسترجاع أم لا.

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة 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

    الرقم

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

    boolean

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

update()

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

لتحديث خصائص المقبس.

المَعلمات

  • socketId

    الرقم

    معرّف المقبس.

  • المواقع

    SocketProperties

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

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

    لا تتوفّر الوعود إلا في الإصدار 3 من 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