chrome.sockets.udp

תיאור

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

מניפסט

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

"sockets"

סוגים

CreateInfo

מאפיינים

  • socketId

    number

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

DnsQueryType

גרסה 103 ואילך של Chrome

העדפות רזולוציית 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

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

    אם השקע הבסיסי קשור, הוא מכיל את כתובת ה-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,
)

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

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    גרסה 121 ואילך של Chrome

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

create()

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

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

פרמטרים

  • נכסים

    SocketProperties אופציונלי

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

  • callback

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

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

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

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

החזרות

  • Promise<CreateInfo>

    גרסה 121 ואילך של Chrome

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

getInfo()

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

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

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

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

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

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

החזרות

  • Promise<SocketInfo>

    גרסה 121 ואילך של Chrome

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

getJoinedGroups()

Promise 
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
)

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

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

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

    (groups: string[]) => void

    • קבוצות

      string[]

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

החזרות

  • Promise<string[]>

    גרסה 121 ואילך של Chrome

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

getSockets()

Promise 
chrome.sockets.udp.getSockets(
  callback?: function,
)

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

פרמטרים

  • callback

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

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

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

החזרות

  • Promise<SocketInfo[]>

    גרסה 121 ואילך של Chrome

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

joinGroup()

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

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • כתובת

    מחרוזת

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

  • callback

    פונקציה

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

    (result: number) => void

    • תוצאה

      number

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

leaveGroup()

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

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

עזיבת הקבוצה תמנע מהנתב לשלוח חבילות נתונים של 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,
)

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • נתונים

    ArrayBuffer

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

  • כתובת

    מחרוזת

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

  • יציאה

    number

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

  • 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,
)

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • פעיל

    בוליאני

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

  • callback

    פונקציה

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

    (result: number) => void

    • תוצאה

      number

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

setMulticastLoopbackMode()

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

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

הערה: ההתנהגות של setMulticastLoopbackMode שונה במקצת בין מערכות Windows למערכות דמויות-Unix. חוסר העקביות מתרחש רק כשיש יותר מאפליקציה אחת באותו מארח שמצטרפת לאותה קבוצת Multicast, עם הגדרות שונות במצב loopback של Multicast. ב-Windows, האפליקציות עם loopback מושבת לא יקבלו את חבילות ה-loopback. לעומת זאת, במערכות כמו Unix, האפליקציות עם loopback מושבת לא ישלחו את חבילות ה-loopback לאפליקציות אחרות באותו מארח. מידע נוסף זמין ב-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,
)

הגדרת משך החיים של חבילות ה-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,
)

השהיה או ביטול השהיה של שקע. שקע מושהה חסום מפני הפעלת אירועי onReceive.

פרמטרים

  • socketId

    number

  • מושהה

    בוליאני

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    גרסה 121 ואילך של Chrome

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

update()

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

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • נכסים

    SocketProperties

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    גרסה 121 ואילך של Chrome

    יש תמיכה ב-Promises רק ב-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,
)

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

פרמטרים