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.

Enum

‫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

    המזהה של שקע ה-socket.

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getJoinedGroups()

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

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

פרמטרים

  • socketId

    number

    מזהה השקע.

  • callback

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

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

    (groups: string[]) => void

    • קבוצות

      string[]

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

החזרות

  • Promise<string[]>

    ‫Chrome 121 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getSockets()

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

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

פרמטרים

  • callback

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

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

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

החזרות

  • Promise<SocketInfo[]>

    ‫Chrome 121 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

joinGroup()

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

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

פרמטרים

  • 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

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

פרמטרים

  • 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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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 בשקע הזה עד שהשקע יופעל מחדש.

פרמטרים