chrome.sockets.udp

תיאור

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

מניפסט

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

"sockets"

סוגים

CreateInfo

תכונות

  • socketId

    מספר

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

DnsQueryType

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

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

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

"ipv4"

"ipv6"

ReceiveErrorInfo

תכונות

  • resultCode

    מספר

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

  • socketId

    מספר

    מזהה השקע.

ReceiveInfo

תכונות

  • נתונים

    ArrayBuffer

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

  • remoteAddress

    מחרוזת

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

  • remotePort

    מספר

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

  • socketId

    מספר

    מזהה השקע.

SendInfo

תכונות

  • bytesSent

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

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

  • resultCode

    מספר

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

SocketInfo

תכונות

  • bufferSize

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

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

  • localAddress

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

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

  • localPort

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

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

  • name

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

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

  • מושהה

    boolean

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

  • מתמיד

    boolean

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

  • socketId

    מספר

    מזהה השקע.

SocketProperties

תכונות

  • bufferSize

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

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

  • name

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

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

  • מתמיד

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

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

שיטות

bind()

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

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

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

פרמטרים

  • socketId

    מספר

    מזהה השקע.

  • כתובת

    מחרוזת

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

  • יציאה

    מספר

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

  • קריאה חוזרת (callback)

    פונקציה

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

    (result: number)=>void

    • תוצאה אחת

      מספר

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

close()

הבטחה 
chrome.sockets.udp.close(
  socketId: number,
  callback?: function,
)

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

פרמטרים

  • socketId

    מספר

    מזהה השקע.

  • קריאה חוזרת (callback)

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 121 ומעלה

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

create()

הבטחה 
chrome.sockets.udp.create(
  properties?: SocketProperties,
  callback?: function,
)

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

פרמטרים

  • נכסים

    SocketProperties אופציונלי

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

  • קריאה חוזרת (callback)

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

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

    (createInfo: CreateInfo)=>void

    • createInfo

      CreateInfo

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

החזרות

  • Promise<CreateInfo>

    Chrome 121 ומעלה

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

getInfo()

הבטחה 
chrome.sockets.udp.getInfo(
  socketId: number,
  callback?: function,
)

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

פרמטרים

  • socketId

    מספר

    מזהה השקע.

  • קריאה חוזרת (callback)

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

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

    (socketInfo: SocketInfo)=>void

    • socketInfo

      SocketInfo

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

החזרות

  • Promise<SocketInfo>

    Chrome 121 ומעלה

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

getJoinedGroups()

הבטחה 
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
)

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

פרמטרים

  • socketId

    מספר

    מזהה השקע.

  • קריאה חוזרת (callback)

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

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

    (groups: string[])=>void

    • קבוצות

      מחרוזת[]

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

החזרות

  • הבטחה<string[]>

    Chrome 121 ומעלה

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

getSockets()

הבטחה 
chrome.sockets.udp.getSockets(
  callback?: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

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

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

    (socketInfos: SocketInfo[])=>void

    • socketInfos

      SocketInfo[]

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

החזרות

  • Promise<SocketInfo[]>

    Chrome 121 ומעלה

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

joinGroup()

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

מצטרף לקבוצה של שידורים מרובים (multicast) ומתחיל לקבל חבילות מהקבוצה. לפני הקריאה לשיטה הזו, השקע חייב להיות מקושר ליציאה מקומית.

פרמטרים

  • socketId

    מספר

    מזהה השקע.

  • כתובת

    מחרוזת

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

  • קריאה חוזרת (callback)

    פונקציה

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

    (result: number)=>void

    • תוצאה אחת

      מספר

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

leaveGroup()

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

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

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

פרמטרים

  • socketId

    מספר

    מזהה השקע.

  • כתובת

    מחרוזת

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

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר 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)

    פונקציה

    הפרמטר 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)

    פונקציה

    הפרמטר 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)

    פונקציה

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

    (result: number)=>void

    • תוצאה אחת

      מספר

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

setMulticastTimeToLive()

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

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

כדי להפעיל את השיטה הזו, לא נדרשת הרשאות להעברת שידורים מרובים.

פרמטרים

  • socketId

    מספר

    מזהה השקע.

  • ttl

    מספר

    הערך של משך החיים.

  • קריאה חוזרת (callback)

    פונקציה

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

    (result: number)=>void

    • תוצאה אחת

      מספר

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

setPaused()

הבטחה 
chrome.sockets.udp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
)

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

פרמטרים

  • socketId

    מספר

  • מושהה

    boolean

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

  • קריאה חוזרת (callback)

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 121 ומעלה

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

update()

הבטחה 
chrome.sockets.udp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
)

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

פרמטרים

  • socketId

    מספר

    מזהה השקע.

  • נכסים

    SocketProperties

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

  • קריאה חוזרת (callback)

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 121 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה 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 עבור השקע הזה עד לחידוש השקע.

פרמטרים