chrome.socket

תיאור

אפשר להשתמש ב-API של chrome.socket כדי לשלוח ולקבל נתונים דרך הרשת באמצעות חיבורי TCP ו-UDP. הערה: החל מגרסה 33 של Chrome, ה-API הזה הוצא משימוש והוחלף בממשקי ה-API‏ sockets.udp,‏ sockets.tcp ו-sockets.tcpServer.

הרשאות

socket

סוגים

AcceptInfo

מאפיינים

• resultCode

  number

• socketId

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

  המזהה של השקע שאושר.

CreateInfo

מאפיינים

• socketId

  number

  המזהה של השקע החדש שנוצר.

CreateOptions

NetworkInterface

מאפיינים

• כתובת

  מחרוזת

  כתובת IPv4/6 זמינה.

• שם

  מחרוזת

  השם הבסיסי של המתאם. ב-‎ *nix, בדרך כלל זה יהיה "eth0",‏ "lo" וכו'.

• prefixLength

  number

  אורך הקידומת

ReadInfo

מאפיינים

• נתונים

  ArrayBuffer

• resultCode

  number

  ה-resultCode שמוחזר מהקריאה הבסיסית ל-()read.

RecvFromInfo

מאפיינים

• כתובת

  מחרוזת

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

• נתונים

  ArrayBuffer

• יציאה

  number

• resultCode

  number

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

SecureOptions

מאפיינים

• tlsVersion

  TLSVersionConstraints אופציונלי

SocketInfo

מאפיינים

• מחובר

  בוליאני

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

  בשקעי tcp, זה יישאר נכון גם אם המחשב המרוחק נותק. קריאה או כתיבה ל-socket עלולה לגרום לשגיאה, שמרמזת שצריך לנתק את ה-socket הזה באמצעות disconnect().

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

• localAddress

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

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

• localPort

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

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

• peerAddress

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

  אם ה-socket הבסיסי מחובר, השדה מכיל את כתובת ה-IPv4/6 של נקודת הקצה (peer).

• peerPort

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

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

• socketType

  SocketType

  סוג השקע שהועבר. הערך יהיה tcp או udp.

SocketType

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

"tcp"

"udp"

TLSVersionConstraints

מאפיינים

• מקסימלי

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

• דק'

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

  הגרסאות המינימליות והמקסימליות הקבילות של TLS. הערכים הנתמכים הם tls1.2 או tls1.3.

  הערכים tls1 ו-tls1.1 כבר לא נתמכים. אם המדיניות min מוגדרת לאחד מהערכים האלה, היא תוגבל ל-tls1.2 בלי להציג הודעה. אם המדיניות max מוגדרת לאחד מהערכים האלה, או לכל ערך לא מזוהה אחר, המערכת תתעלם ממנה בלי להציג הודעה.

WriteInfo

מאפיינים

• bytesWritten

  number

  מספר הבייטים שנשלחו, או קוד שגיאה שלילי.

Methods

accept()

chrome.socket.accept(
  socketId: number,
  callback: function,
): void

השיטה הזו רלוונטית רק לשקעי TCP. רושמת פונקציית קריאה חוזרת (callback) שתיקרא כשחיבור יתקבל בשקע השרת (server socket) הזה להאזנה. צריך קודם להפעיל את Listen. אם כבר יש קריאה חוזרת (callback) פעילה לאישור, הקריאה החוזרת הזו תופעל באופן מיידי עם שגיאה בתור resultCode.

פרמטרים

• socketId

  number

  ה-socketId.

• callback

  פונקציה

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

  (acceptInfo: AcceptInfo) => void

  • acceptInfo

    AcceptInfo

bind()

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

מקשר את הכתובת המקומית לשקע. כרגע אין תמיכה בשקע TCP.

פרמטרים

• socketId

  number

  ה-socketId.

• כתובת

  מחרוזת

  הכתובת של המכונה המקומית.

• יציאה

  number

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

• callback

  פונקציה

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

  (result: number) => void

  • תוצאה

    number

connect()

chrome.socket.connect(
  socketId: number,
  hostname: string,
  port: number,
  callback: function,
): void

חיבור השקע למכונה המרוחקת (לשקע tcp). בשקע udp, הפעולה הזו מגדירה את כתובת ברירת המחדל שאליה נשלחות חבילות וממנה הן נקראות, עבור קריאות read() ו-write().

פרמטרים

• socketId

  number

  ה-socketId.

• hostname

  מחרוזת

  שם המארח או כתובת ה-IP של המכונה המרוחקת.

• יציאה

  number

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

• callback

  פונקציה

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

  (result: number) => void

  • תוצאה

    number

create()

Promise

chrome.socket.create(
  type: SocketType,
  options?: CreateOptions,
  callback?: function,
): Promise<CreateInfo>

יוצרת שקע מהסוג שצוין שיתחבר למכונה המרוחקת שצוינה.

פרמטרים

• סוג

  SocketType

  סוג השקע שרוצים ליצור. הערך חייב להיות tcp או udp.

• אפשרויות

  ‫CreateOptions אופציונלי

  אפשרויות השקע.

• callback

  function optional

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

  (createInfo: CreateInfo) => void

  • createInfo

    CreateInfo

החזרות

• Promise<CreateInfo>

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

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

destroy()

chrome.socket.destroy(
  socketId: number,
): void

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

פרמטרים

• socketId

  number

  ה-socketId.

disconnect()

chrome.socket.disconnect(
  socketId: number,
): void

מנתק את השקע. בשקעי UDP, הפונקציה disconnect לא מבצעת פעולה אבל אפשר להפעיל אותה באופן בטוח.

פרמטרים

• socketId

  number

  ה-socketId.

getInfo()

Promise

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

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

פרמטרים

• socketId

  number

  ה-socketId.

• callback

  function optional

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

  (result: SocketInfo) => void

  • תוצאה

    SocketInfo

החזרות

• Promise<SocketInfo>

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

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

getJoinedGroups()

chrome.socket.getJoinedGroups(
  socketId: number,
  callback: function,
): void

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

פרמטרים

• socketId

  number

  ה-socketId.

• callback

  פונקציה

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

  (groups: string[]) => void

  • קבוצות

    string[]‎

getNetworkList()

Promise

chrome.socket.getNetworkList(
  callback?: function,
): Promise<NetworkInterface[]>

אחזור מידע על מתאמים מקומיים במערכת הזו.

פרמטרים

• callback

  function optional

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

  (result: NetworkInterface[]) => void

  • תוצאה

    NetworkInterface[]

החזרות

• Promise<NetworkInterface[]>

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

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

joinGroup()

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

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

פרמטרים

• socketId

  number

  ה-socketId.

• כתובת

  מחרוזת

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

• callback

  פונקציה

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

  (result: number) => void

  • תוצאה

    number

leaveGroup()

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

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

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

פרמטרים

• socketId

  number

  ה-socketId.

• כתובת

  מחרוזת

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

• callback

  פונקציה

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

  (result: number) => void

  • תוצאה

    number

listen()

chrome.socket.listen(
  socketId: number,
  address: string,
  port: number,
  backlog?: number,
  callback: function,
): void

השיטה הזו רלוונטית רק לשקעי TCP. האזנה לחיבורים ביציאה ובכתובת שצוינו. הפעולה הזו הופכת את השקע לשקע שרת (server socket), ואי אפשר יותר להשתמש בפונקציות של שקע לקוח (client socket) (חיבור, קריאה, כתיבה) בשקע הזה.

פרמטרים

• socketId

  number

  ה-socketId.

• כתובת

  מחרוזת

  הכתובת של המכונה המקומית.

• יציאה

  number

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

• צבר משימות

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

  אורך תור ההאזנה של השקע.

• callback

  פונקציה

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

  (result: number) => void

  • תוצאה

    number

read()

chrome.socket.read(
  socketId: number,
  bufferSize?: number,
  callback: function,
): void

קריאת נתונים מהשקע המחובר שצוין.

פרמטרים

• socketId

  number

  ה-socketId.

• bufferSize

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

  גודל שטח האחסון הזמני לקריאה.

• callback

  פונקציה

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

  (readInfo: ReadInfo) => void

  • readInfo

    ReadInfo

recvFrom()

chrome.socket.recvFrom(
  socketId: number,
  bufferSize?: number,
  callback: function,
): void

מקבל נתונים משקע ה-UDP הנתון.

פרמטרים

• socketId

  number

  ה-socketId.

• bufferSize

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

  גודל שטח האחסון הזמני של הקבלה.

• callback

  פונקציה

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

  (recvFromInfo: RecvFromInfo) => void

  • recvFromInfo

    RecvFromInfo

secure()

chrome.socket.secure(
  socketId: number,
  options?: SecureOptions,
  callback: function,
): void

התחלת חיבור של לקוח TLS דרך שקע לקוח (client socket) מחובר של TCP.

פרמטרים

• socketId

  number

  השקע המחובר שבו רוצים להשתמש.

• אפשרויות

  SecureOptions אופציונלי

  אילוצים ופרמטרים לחיבור TLS.

• callback

  פונקציה

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

  (result: number) => void

  • תוצאה

    number

sendTo()

chrome.socket.sendTo(
  socketId: number,
  data: ArrayBuffer,
  address: string,
  port: number,
  callback: function,
): void

שליחת נתונים בשקע ה-UDP שצוין לכתובת וליציאה שצוינו.

פרמטרים

• socketId

  number

  ה-socketId.

• נתונים

  ArrayBuffer

  הנתונים שרוצים לכתוב.

• כתובת

  מחרוזת

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

• יציאה

  number

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

• callback

  פונקציה

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

  (writeInfo: WriteInfo) => void

  • writeInfo

    WriteInfo

setKeepAlive()

chrome.socket.setKeepAlive(
  socketId: number,
  enable: boolean,
  delay?: number,
  callback: function,
): void

הפעלה או השבתה של פונקציונליות ה-keep-alive בחיבור TCP.

פרמטרים

• socketId

  number

  ה-socketId.

• enable

  בוליאני

  אם הערך הוא True, הפונקציונליות של keep-alive מופעלת.

• עיכוב

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

  הגדרת השהיה בשניות בין חבילת הנתונים האחרונה שהתקבלה לבין בדיקת ה-keepalive הראשונה. ברירת המחדל היא 0.

• callback

  פונקציה

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

  (result: boolean) => void

  • תוצאה

    בוליאני

setMulticastLoopbackMode()

chrome.socket.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

  ה-socketId.

• פעיל

  בוליאני

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

• callback

  פונקציה

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

  (result: number) => void

  • תוצאה

    number

setMulticastTimeToLive()

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

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

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

פרמטרים

• socketId

  number

  ה-socketId.

• ttl

  number

  ערך זמן החיים.

• callback

  פונקציה

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

  (result: number) => void

  • תוצאה

    number

setNoDelay()

chrome.socket.setNoDelay(
  socketId: number,
  noDelay: boolean,
  callback: function,
): void

מגדירה או מנקה את TCP_NODELAY לחיבור TCP. האלגוריתם של נייגל יושבת כשמגדירים את TCP_NODELAY.

פרמטרים

• socketId

  number

  ה-socketId.

• noDelay

  בוליאני

  אם הערך הוא True, האלגוריתם של נייגל מושבת.

• callback

  פונקציה

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

  (result: boolean) => void

  • תוצאה

    בוליאני

write()

chrome.socket.write(
  socketId: number,
  data: ArrayBuffer,
  callback: function,
): void

כתיבת נתונים בשקע המחובר שצוין.

פרמטרים

• socketId

  number

  ה-socketId.

• נתונים

  ArrayBuffer

  הנתונים שרוצים לכתוב.

• callback

  פונקציה

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

  (writeInfo: WriteInfo) => void

  • writeInfo

    WriteInfo