chrome.sockets.udp

תיאור

משתמשים ב-chrome.sockets.udp API כדי לשלוח ולקבל נתונים ברשת באמצעות חיבורי UDP. ה-API הזה מחליף את הפונקציונליות של UDP שהייתה קיימת בעבר ב-API של socket.

מניפסט

כדי להשתמש ב-API הזה, צריך להצהיר על המפתחות הבאים במניפסט.

"sockets"

סוגים

CreateInfo

מאפיינים

  • socketId

    number

    המזהה של שקע ה-Socket שנוצר. שימו לב שמזהי socket שנוצרו מ-API הזה לא תואמים למזהי socket שנוצרו מ-API אחרים, כמו [socket](../socket/) API שיצא משימוש.

DnsQueryType

‫Chrome 103 ואילך

העדפות של פענוח DNS. ברירת המחדל היא any והיא משתמשת בהגדרת מערכת ההפעלה הנוכחית, שיכולה להחזיר IPv4 או IPv6. ‫ipv4 מאלץ IPv4, ו-ipv6 מאלץ IPv6.

ספירה

‫"any"

‫"ipv4"

‪"ipv6"

ReceiveErrorInfo

מאפיינים

  • resultCode

    number

    קוד התוצאה שמוחזר מהקריאה הבסיסית recvfrom().

  • socketId

    number

    מזהה השקע.

ReceiveInfo

מאפיינים

  • נתונים

    ArrayBuffer

    תוכן מנות ה-UDP (חלק מהתוכן מוצג בהתאם לגודל המאגר הנוכחי).

  • remoteAddress

    מחרוזת

    הכתובת של המארח שממנו מגיעה חבילת הנתונים.

  • remotePort

    number

    היציאה של המארח שממנו מגיע החבילה.

  • socketId

    number

    מזהה השקע.

SendInfo

מאפיינים

  • bytesSent

    מספר אופציונלי

    מספר הבייטים שנשלחו (אם התוצאה היא 0)

  • resultCode

    number

    קוד התוצאה שמוחזר מקריאת הרשת הבסיסית. ערך שלילי מציין שגיאה.

SocketInfo

מאפיינים

  • bufferSize

    מספר אופציונלי

    גודל המאגר שמשמש לקבלת נתונים. אם לא צוין גודל מאגר באופן מפורש, הערך לא יסופק.

  • localAddress

    מחרוזת אופציונלי

    אם השקע הבסיסי מאוגד, הוא מכיל את כתובת ה-IPv4/6 המקומית שלו.

  • localPort

    מספר אופציונלי

    אם השקע הבסיסי מאוגד, הערך מכיל את היציאה המקומית שלו.

  • שם

    מחרוזת אופציונלי

    מחרוזת שהוגדרה על ידי האפליקציה ומשויכת לשקע.

  • מושהה

    בוליאני

    סימון שמציין אם השקע חסום מהפעלת אירועי onReceive.

  • קבוע

    בוליאני

    דגל שמציין אם השקע נשאר פתוח כשהאפליקציה מושהית (ראו SocketProperties.persistent).

  • socketId

    number

    מזהה השקע.

SocketProperties

מאפיינים

  • bufferSize

    מספר אופציונלי

    גודל המאגר שמשמש לקבלת נתונים. אם המאגר קטן מדי בשביל לקבל את מנת ה-UDP, הנתונים יאבדו. ערך ברירת המחדל הוא 4096.

  • שם

    מחרוזת אופציונלי

    מחרוזת שמוגדרת על ידי האפליקציה ומשויכת לשקע.

  • קבוע

    ‫boolean אופציונלי

    דגל שמציין אם השקע נשאר פתוח כשדף האירוע של האפליקציה מבוטל (ראו ניהול מחזור החיים של האפליקציה). ערך ברירת המחדל הוא false. כשהאפליקציה נטענת, אפשר לאחזר שקעים שנפתחו קודם עם persistent=true באמצעות getSockets.

Methods

bind()

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

קושר את הכתובת המקומית ואת היציאה לשקע. במקרה של שקע לקוח, מומלץ להשתמש ביציאה 0 כדי לאפשר לפלטפורמה לבחור יציאה פנויה.

אחרי שהפעולה bind מסתיימת בהצלחה, אירועים מסוג onReceive מופעלים כשחבילות UDP מגיעות לכתובת או ליציאה שצוינו – אלא אם השקע מושהה.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • כתובת

    מחרוזת

    הכתובת של המכונה המקומית. יש תמיכה בפורמטים של שם DNS, ‏ IPv4 ו-IPv6. אפשר להשתמש בכתובת 0.0.0.0 כדי לקבל מנות מכל ממשקי הרשת המקומיים הזמינים.

  • ניוד

    number

    היציאה של המכונה המקומית. כדי לבצע איגוד ליציאה פנויה, משתמשים בערך '0'.

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (result: number) => void

    • תוצאה

      number

      קוד התוצאה שמוחזר מקריאת הרשת הבסיסית. ערך שלילי מציין שגיאה.

close()

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

סוגר את השקע ומשחרר את הכתובת או היציאה שהשקע קשור אליהן. צריך לסגור כל שקע שנוצר אחרי השימוש בו. מזהה השקע כבר לא תקף ברגע שהפונקציה מופעלת. עם זאת, מובטח שהסוקט ייסגר רק כשהקריאה החוזרת תופעל.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    ‫Chrome 121 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

create()

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

יוצר שקע UDP עם המאפיינים שצוינו.

פרמטרים

  • נכסים

    ‫SocketProperties אופציונלי

    מאפייני השקע (אופציונלי).

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      התוצאה של יצירת השקע.

החזרות

  • Promise<CreateInfo>

    ‫Chrome 121 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getInfo()

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

מאחזרת את המצב של שקע נתון.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      אובייקט שמכיל את פרטי השקע.

החזרות

  • Promise<SocketInfo>

    ‫Chrome 121 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getJoinedGroups()

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

הפונקציה מחזירה את כתובות הקבוצה של שידור מרובה משתתפים שאליהן מצורף כרגע השקע.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (groups: string[]) => void

    • קבוצות

      string[]

      מערך של קבוצות שהסוקט הצטרף אליהן.

החזרות

  • Promise<string[]>

    ‫Chrome 121 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getSockets()

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

מאחזר את רשימת השקעים הפתוחים כרגע שבבעלות האפליקציה.

פרמטרים

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

      מערך של אובייקטים שמכילים פרטים על שקע.

החזרות

  • Promise<SocketInfo[]>

    ‫Chrome 121 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

joinGroup()

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

המשתמש מצטרף לקבוצת ה-Multicast ומתחיל לקבל חבילות מהקבוצה הזו. לפני שמפעילים את ה-method הזו, צריך לקשור את ה-socket ליציאה מקומית.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • כתובת

    מחרוזת

    כתובת הקבוצה שאליה רוצים להצטרף. אין תמיכה בשמות דומיין.

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (result: number) => void

    • תוצאה

      number

      קוד התוצאה שמוחזר מקריאת הרשת הבסיסית. ערך שלילי מציין שגיאה.

leaveGroup()

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

יוצא מקבוצת ה-Multicast שהצטרף אליה קודם באמצעות joinGroup. הפעולה הזו נדרשת רק אם מתכננים להמשיך להשתמש בסוקט לאחר מכן, כי מערכת ההפעלה תבצע אותה באופן אוטומטי כשהסוקט ייסגר.

אם תעזבו את הקבוצה, הנתב לא ישלח יותר חבילות נתונים של שידור מרובה משתתפים למארח המקומי, בהנחה שאין תהליך אחר במארח שמחובר עדיין לקבוצה.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • כתובת

    מחרוזת

    כתובת הקבוצה שרוצים לעזוב. אין תמיכה בשמות דומיין.

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (result: number) => void

    • תוצאה

      number

      קוד התוצאה שמוחזר מקריאת הרשת הבסיסית. ערך שלילי מציין שגיאה.

send()

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

שולחת נתונים בשקע הנתון לכתובת ולפורט הנתונים. לפני שמפעילים את ה-method הזו, צריך לקשור את ה-socket ליציאה מקומית.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • נתונים

    ArrayBuffer

    הנתונים שרוצים לשלוח.

  • כתובת

    מחרוזת

    הכתובת של המכונה המרוחקת.

  • ניוד

    number

    היציאה של המחשב המרוחק.

  • dnsQueryType

    DnsQueryType optional

    ‫Chrome 103 ואילך

    העדפת המרת כתובת.

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      התוצאה של השיטה send.

setBroadcast()

‫Chrome 44 ואילך 
chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
): void

הפעלה או השבתה של חבילות שידור בשקע הזה.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • פעיל

    בוליאני

    ‫true כדי להפעיל חבילות שידור, false כדי להשבית אותן.

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (result: number) => void

    • תוצאה

      number

      קוד התוצאה שמוחזר מקריאת הרשת הבסיסית.

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

הקריאה ל-method הזה לא דורשת הרשאות מרובות משתתפים.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • פעיל

    בוליאני

    מציינת אם להפעיל את מצב הלולאה החוזרת.

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (result: number) => void

    • תוצאה

      number

      קוד התוצאה שמוחזר מקריאת הרשת הבסיסית. ערך שלילי מציין שגיאה.

setMulticastTimeToLive()

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

מגדיר את משך החיים של חבילות נתונים של שידור מרובה משתתפים שנשלחות לקבוצת השידור המרובה.

כדי לקרוא ל-method הזה לא נדרשות הרשאות לשידור מרובה משתתפים.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • ttl

    number

    ערך הזמן לחיים.

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (result: number) => void

    • תוצאה

      number

      קוד התוצאה שמוחזר מקריאת הרשת הבסיסית. ערך שלילי מציין שגיאה.

setPaused()

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

משהה או מבטל את ההשהיה של שקע. שקע מושהה לא יכול להפעיל אירועי onReceive.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • מושהה

    בוליאני

    סימון שמציין אם להשהות או לבטל את ההשהיה.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    ‫Chrome 121 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

update()

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

עדכון מאפייני השקע.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • נכסים

    SocketProperties

    המאפיינים לעדכון.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    ‫Chrome 121 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש בפונקציות קריאה חוזרת (callback).

אירועים

onReceive

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

האירוע מופעל כשמתקבל חבילת UDP עבור השקע הנתון.

פרמטרים

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

    (info: ReceiveInfo) => void

onReceiveError

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

האירוע מופעל כשהתרחשה שגיאת רשת בזמן שהסביבה העסקית המשותפת המתינה לנתונים בכתובת ובפורט של שקע התקשורת. אחרי שהאירוע הזה מופעל, השקע מושהה ולא יופעלו עוד אירועי onReceive בשקע הזה עד שהשקע יופעל מחדש.

פרמטרים