chrome.sockets.udp

תיאור

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

מניפסט

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

"sockets"

סוגים

CreateInfo

מאפיינים

  • socketId

    number

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

DnsQueryType

Chrome 103 ואילך

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

Enum

"כלשהו"

"ipv4"

"ipv6"

ReceiveErrorInfo

מאפיינים

  • resultCode

    number

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

  • socketId

    number

    מזהה ה-socket.

ReceiveInfo

מאפיינים

  • נתונים

    ArrayBuffer

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

  • remoteAddress

    מחרוזת

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

  • remotePort

    number

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

  • socketId

    number

    מזהה ה-socket.

SendInfo

מאפיינים

  • bytesSent

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

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

  • resultCode

    number

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

SocketInfo

מאפיינים

  • bufferSize

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

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

  • localAddress

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

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

  • localPort

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

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

  • שם

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

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

  • מושהה

    בוליאני

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

  • מתמיד

    בוליאני

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

  • socketId

    number

    מזהה ה-socket.

SocketProperties

מאפיינים

  • bufferSize

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

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

  • שם

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

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

  • מתמיד

    ערך בוליאני אופציונלי

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

שיטות

bind()

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

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

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

פרמטרים

  • socketId

    number

    מזהה ה-socket.

  • כתובת

    מחרוזת

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

  • יציאה

    number

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

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

    פונקציה

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

    (result: number) => void

    • תוצאה

      number

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

close()

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

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

פרמטרים

  • socketId

    number

    מזהה ה-socket.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 121 ואילך

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

create()

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

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

פרמטרים

  • נכסים

    SocketProperties אופציונלי

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

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

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

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

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

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

החזרות

  • Promise&lt;CreateInfo&gt;

    Chrome 121 ואילך

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

getInfo()

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

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

פרמטרים

  • socketId

    number

    מזהה ה-socket.

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

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

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

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

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

החזרות

  • Promise&lt;SocketInfo&gt;

    Chrome 121 ואילך

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

getJoinedGroups()

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

קבלת כתובות הקבוצה של Multicast שאליה מצורף ה-socket.

פרמטרים

  • socketId

    number

    מזהה ה-socket.

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

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

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

    (groups: string[]) => void

    • קבוצות

      String[]

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

החזרות

  • Promise&lt;string[]&gt;

    Chrome 121 ואילך

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

getSockets()

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

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

פרמטרים

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

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

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

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

החזרות

  • Promise&lt;SocketInfo[]&gt;

    Chrome 121 ואילך

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

joinGroup()

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

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

פרמטרים

  • socketId

    number

    מזהה ה-socket.

  • כתובת

    מחרוזת

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

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

    פונקציה

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

    (result: number) => void

    • תוצאה

      number

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

leaveGroup()

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

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

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

פרמטרים

  • socketId

    number

    מזהה ה-socket.

  • כתובת

    מחרוזת

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

  • קריאה חוזרת (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

    מזהה ה-socket.

  • נתונים

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

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

פרמטרים

  • socketId

    number

    מזהה ה-socket.

  • פעיל

    בוליאני

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

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

    פונקציה

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

    (result: number) => void

    • תוצאה

      number

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

setMulticastLoopbackMode()

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

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

הערה: יש הבדלים קלים בהתנהגות של setMulticastLoopbackMode בין מערכות כמו Windows ו-Unix. חוסר העקביות מתרחש רק כאשר יותר מאפליקציה אחת באותו מארח שמחוברת לאותה קבוצת Multicast, כשיש לה הגדרות שונות במצב Multicast לולאה חוזרת. ב-Windows, אפליקציות שההפעלה שלהן מושבתת לא יקבלו את חבילות הלולאה החוזרת; במערכות כמו Unix, האפליקציות שמותקנות בהן לולאה חוזרת לא ישלחו את חבילות הלולאה החוזרת לאפליקציות אחרות באותו מארח. פרטים נוספים זמינים ב-MSDN: http://goo.gl/6vqbj

קריאה לשיטה הזו אינה דורשת הרשאות Multicast.

פרמטרים

  • socketId

    number

    מזהה ה-socket.

  • פעיל

    בוליאני

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

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

    פונקציה

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

    (result: number) => void

    • תוצאה

      number

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

setMulticastTimeToLive()

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

מגדיר את ה-Time to Live של חבילות Multicast שנשלחות לקבוצה ב-Multicast.

קריאה לשיטה הזו אינה דורשת הרשאות Multicast.

פרמטרים

  • socketId

    number

    מזהה ה-socket.

  • ttl

    number

    הערך של אורך החיים.

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

    פונקציה

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

    (result: number) => void

    • תוצאה

      number

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

setPaused()

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

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

פרמטרים

  • socketId

    number

  • מושהה

    בוליאני

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 121 ואילך

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

update()

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

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

פרמטרים

  • socketId

    number

    מזהה ה-socket.

  • נכסים

    SocketProperties

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

פרמטרים