chrome.sockets.udp

תיאור

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

מניפסט

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

"sockets"

סוגים

CreateInfo

מאפיינים

  • socketId

    number

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

DnsQueryType

‫Chrome מגרסה 103 ואילך

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

טיפוסים בני מנייה (enum)

"any"

"ipv4"

"ipv6"

ReceiveErrorInfo

מאפיינים

  • resultCode

    number

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

  • socketId

    number

    מזהה השקע.

ReceiveInfo

מאפיינים

  • נתונים

    ArrayBuffer

    תוכן חבילת ה-UDP (נחתך לגודל הנוכחי של שטח האחסון הזמני).

  • remoteAddress

    מחרוזת

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

  • remotePort

    number

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

  • socketId

    number

    מזהה השקע.

SendInfo

מאפיינים

  • bytesSent

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

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

  • resultCode

    number

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

SocketInfo

מאפיינים

  • bufferSize

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

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

  • localAddress

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

    אם ה-socket הבסיסי מקושר, הוא מכיל את כתובת ה-IPv4/6 המקומית שלו.

  • localPort

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

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

  • שם

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

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

  • מושהה

    בוליאני

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

  • קבוע

    בוליאני

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

  • socketId

    number

    מזהה השקע.

SocketProperties

מאפיינים

  • bufferSize

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

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

  • שם

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

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

  • קבוע

    בוליאני אופציונלי

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

Methods

bind()

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

מקשר את הכתובת המקומית והיציאה של השקע. בשקע לקוח (client socket), מומלץ להשתמש ביציאה 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>

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 121 ואילך

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

create()

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

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

פרמטרים

  • נכסים

    ‫SocketProperties אופציונלי

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

  • callback

    function optional

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

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

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

החזרות

  • Promise<CreateInfo>

    ‫Chrome מגרסה 121 ואילך

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

getInfo()

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

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

    function optional

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

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

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

החזרות

  • Promise<SocketInfo>

    ‫Chrome מגרסה 121 ואילך

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

getJoinedGroups()

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

מקבלת את כתובות קבוצת ה-multicast שהשקע מחובר אליהן כרגע.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

    function optional

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

    (groups: string[]) => void

    • קבוצות

      string[]‎

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

החזרות

  • Promise<string[]>

    ‫Chrome מגרסה 121 ואילך

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

getSockets()

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

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

פרמטרים

  • callback

    function optional

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

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

החזרות

  • Promise<SocketInfo[]>

    ‫Chrome מגרסה 121 ואילך

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

joinGroup()

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

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • כתובת

    מחרוזת

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

  • callback

    פונקציה

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

    (result: number) => void

    • תוצאה

      number

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

leaveGroup()

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

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

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

פרמטרים

  • 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 הזו.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • נתונים

    ArrayBuffer

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

  • כתובת

    מחרוזת

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

  • יציאה

    number

    היציאה של המכונה המרוחקת.

  • dnsQueryType

    DnsQueryType אופציונלי

    ‫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

ההגדרה הזו קובעת אם חבילות multicast שנשלחות מהמארח לקבוצת ה-multicast יוחזרו למארח.

הערה: ההתנהגות של setMulticastLoopbackMode שונה קצת בין מערכות Windows למערכות דמויות Unix. חוסר העקביות קורה רק כשיש יותר מאפליקציה אחת באותו מארח שמצטרפת לאותה קבוצת multicast, כשיש להן הגדרות שונות במצב multicast loopback. ב-Windows, אפליקציות שהלולאה החוזרת שלהן מושבתת לא יקבלו את חבילות הלולאה החוזרת. במערכות כמו Unix, אפליקציות שהלולאה החוזרת שלהן מושבתת לא ישלחו את חבילות הלולאה החוזרת לאפליקציות אחרות באותו מארח. אפשר לעיין ב-MSDN: ‏https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

כדי להפעיל את ה-method הזה לא נדרשות הרשאות multicast.

פרמטרים

  • socketId

    number

    מזהה השקע.

  • פעיל

    בוליאני

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

  • callback

    פונקציה

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

    (result: number) => void

    • תוצאה

      number

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

setMulticastTimeToLive()

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

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

כדי להפעיל את ה-method הזה לא נדרשות הרשאות multicast.

פרמטרים

  • 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

    function optional

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 121 ואילך

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

update()

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

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • נכסים

    SocketProperties

    המאפיינים שצריך לעדכן.

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 121 ואילך

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

אירועים

onReceive

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

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

פרמטרים

  • callback

    פונקציה

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

    (info: ReceiveInfo) => void

onReceiveError

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

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

פרמטרים