chrome.usb

תיאור

שימוש ב-API של chrome.usb לאינטראקציה עם התקני USB מחוברים. ה-API הזה מספק גישה לפעולות USB מהקשר של אפליקציה. באמצעות ה-API הזה, אפליקציות יכולות לפעול כמנהלי התקנים למכשירי חומרה. כדי לדווח על שגיאות שנוצרו על ידי ה-API הזה, מגדירים את runtime.lastError ומפעילים את פונקציית ה-callback הרגילה של הפונקציה. במקרה כזה, הפרמטרים הרגילים של קריאת החזרה (callback) לא יוגדרו.

הרשאות

usb

סוגים

ConfigDescriptor

מאפיינים

  • פעיל

    בוליאני

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

    האם זו ההגדרה הפעילה?

  • configurationValue

    number

    מספר ההגדרה.

  • תיאור

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

    תיאור ההגדרה.

  • extra_data

    ArrayBuffer

    נתוני מתאר נוספים שמשויכים להגדרה הזו.

  • ממשקים

    InterfaceDescriptor[]

    ממשקים זמינים.

  • maxPower

    number

    ההספק המקסימלי הנדרש למכשיר הזה במיליאמפר (mA).

  • remoteWakeup

    בוליאני

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

  • selfPowered

    בוליאני

    המכשיר מופעל באופן עצמאי.

ConnectionHandle

מאפיינים

  • נקודת אחיזה

    number

    נקודת אחיזה אטומה שמייצגת את החיבור הזה להתקן ה-USB ולכל הממשקים המשויכים אליהם והעברות בהמתנה. הכינוי החדש נוצר בכל פעם שפותחים את המכשיר. הכינוי של החיבור שונה מ-Device.device.

  • productId

    number

    מזהה המוצר

  • vendorId

    number

    המזהה של ספק המכשיר

ControlTransferInfo

מאפיינים

  • נתונים

    ArrayBuffer אופציונלי

    הנתונים להעברה (נדרש רק להעברות פלט).

  • direction

    כיוון

    כיוון ההעברה ("in" או "out").

  • index

    number

    השדה wIndex, ראו Ibid.

  • length

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

    המספר המקסימלי של בייטים לקבל (נדרש רק על ידי העברת קלט).

  • מקבל המתנה

    נמען

    יעד ההעברה. צריך לטעון בעלות על היעד שצוין ב-index אם "interface" או "endpoint".

  • בקשה

    number

    השדה bRequest, ראו Universal Serial Bus Specification Revision 1.1 § 9.3.

  • requestType

    RequestType

    סוג הבקשה.

  • פסק זמן

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

    Chrome 43 ואילך

    הזמן הקצוב לתפוגה של הבקשה (באלפיות השנייה). ערך ברירת המחדל 0 מציין שאין זמן קצוב לתפוגה.

  • ערך

    number

    השדה wValue, ראו Ibid.

Device

מאפיינים

  • מכשיר

    number

    מזהה אטום להתקן ה-USB. הכרטיס נשאר ללא שינוי עד שהמכשיר מנותק מהחשמל.

  • manufacturerName

    מחרוזת

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

    מחרוזת iManufacturer שנקראה מהמכשיר, אם היא זמינה.

  • productId

    number

    מזהה המוצר

  • productName

    מחרוזת

    Chrome 46 ואילך

    מחרוזת iProduct שנקראה מהמכשיר, אם היא זמינה.

  • serialNumber

    מחרוזת

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

    מחרוזת ה-iSeriesNumber שנקראה מהמכשיר, אם היא זמינה.

  • vendorId

    number

    המזהה של ספק המכשיר

  • גרסה

    number

    Chrome 51 ואילך

    גרסת המכשיר (השדה bcdDevice).

DeviceFilter

מאפיינים

  • interfaceClass

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

    סיווג ממשק USB, תואם לכל ממשק במכשיר.

  • interfaceProtocol

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

    פרוטוקול ממשק USB, מסומן רק אם רמת המשנה של הממשק תואמת.

  • interfaceSubclass

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

    מחלקה משנית של ממשק USB, נבדקת רק אם רמת הממשק תואמת.

  • productId

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

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

  • vendorId

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

    המזהה של ספק המכשיר.

DevicePromptOptions

מאפיינים

  • מסננים

    DeviceFilter[] אופציונלי

    סינון רשימת המכשירים שמוצגת למשתמש. אם תספקו כמה מסננים, יוצגו מכשירים שתואמים לאחד המסננים.

  • מרובות

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

    המשתמש יכול לבחור מספר מכשירים.

Direction

השדות Direction,‏ Recipient,‏ RequestType ו-TransferType ממופים לשמות המקבילים שלהם במפרט USB.

Enum

"in"

"out"

EndpointDescriptor

מאפיינים

  • כתובת

    number

    כתובת נקודת הקצה.

  • direction

    כיוון

    כיוון ההעברה.

  • extra_data

    ArrayBuffer

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

  • maximumPacketSize

    number

    גודל החבילה המקסימלי.

  • pollingInterval

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

    מרווח תשאול (מרווח ואיזוכרוני בלבד).

  • סנכרון

    SynchronizationType אופציונלי

    מצב סנכרון העברה (איזוכרוני בלבד).

  • סוג

    TransferType

    סוג ההעברה.

  • שימוש

    UsageType אופציונלי

    רמז לשימוש בנקודת קצה.

EnumerateDevicesAndRequestAccessOptions

מאפיינים

  • interfaceId

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

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

  • productId

    number

    מזהה המוצר

  • vendorId

    number

    המזהה של ספק המכשיר

EnumerateDevicesOptions

מאפיינים

  • מסננים

    DeviceFilter[] אופציונלי

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

  • productId

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

    הוצא משימוש

    זהה להגדרה DeviceFilter.productId.

  • vendorId

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

    הוצא משימוש

    זהה להגדרה DeviceFilter.vendorId.

GenericTransferInfo

מאפיינים

  • נתונים

    ArrayBuffer אופציונלי

    הנתונים להעברה (נדרש רק להעברות פלט).

  • direction

    כיוון

    כיוון ההעברה ("in" או "out").

  • נקודת קצה (endpoint)

    number

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

  • length

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

    המספר המקסימלי של בייטים לקבל (נדרש רק על ידי העברת קלט).

  • פסק זמן

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

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

    הזמן הקצוב לתפוגה של בקשה (באלפיות השנייה). ערך ברירת המחדל 0 מציין שאין זמן קצוב לתפוגה.

InterfaceDescriptor

מאפיינים

  • alternateSetting

    number

    מספר ההגדרה החלופית של הממשק (ברירת המחדל היא 0

  • תיאור

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

    תיאור הממשק.

  • נקודות קצה (endpoints)

    EndpointDescriptor[]

    נקודות קצה זמינות.

  • extra_data

    ArrayBuffer

    נתוני מתאר נוספים שמשויכים לממשק הזה.

  • interfaceClass

    number

    סיווג ממשק ה-USB.

  • interfaceNumber

    number

    מספר הממשק.

  • interfaceProtocol

    number

    פרוטוקול הממשק של USB.

  • interfaceSubclass

    number

    מחלקה משנית של ממשק USB.

IsochronousTransferInfo

מאפיינים

  • packetLength

    number

    האורך של כל אחד מהחבילות בהעברה הזו.

  • חבילות

    number

    המספר הכולל של החבילות בהעברה הזו.

  • transferInfo

    GenericTransferInfo

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

Recipient

Enum

"other"

RequestType

Enum

"standard"

"reserved"

SynchronizationType

במצבים של השהיה ושל איסוכרוניות, השדות SynchronizationType ו-UsageType ממפים לשדות בעלי השמות התואמים במפרט USB.

Enum

"adaptive"

TransferResultInfo

מאפיינים

  • נתונים

    ArrayBuffer אופציונלי

    הנתונים שמוחזרים על ידי העברת קלט. undefined להעברות של פלט.

  • resultCode

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

    הערך 0 מציין שההעברה בוצעה בהצלחה. ערכים אחרים מצביעים על כשל.

TransferType

Enum

"control"

"interrupt"

"isochronous"

"bulk"

UsageType

Enum

"data"

"explicitFeedback"

"notification"

שיטות

bulkTransfer()

Promise 
chrome.usb.bulkTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

ביצוע העברה בכמות גדולה במכשיר שצוין.

פרמטרים

החזרות

  • Chrome מגרסה 116 ואילך

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

claimInterface()

Promise 
chrome.usb.claimInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

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

צריך לקרוא לפונקציה releaseInterface כשאין יותר צורך בממשק.

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

    חיבור פתוח למכשיר.

  • interfaceNumber

    number

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

closeDevice()

Promise 
chrome.usb.closeDevice(
  handle: ConnectionHandle,
  callback?: function,
)

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

    ConnectionHandle לסגירה.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 116 ואילך

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

controlTransfer()

Promise 
chrome.usb.controlTransfer(
  handle: ConnectionHandle,
  transferInfo: ControlTransferInfo,
  callback?: function,
)

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

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

פרמטרים

החזרות

  • Chrome מגרסה 116 ואילך

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

findDevices()

Promise 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
)

הפונקציה מאתרת מכשירי USB שצוינו לפי מזהי הספק, המוצר (אופציונלי) והממשק, ואם ההרשאות מאפשרות, פותחת אותם לשימוש.

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

קריאה ל-method הזה שקולה לקריאה ל-getDevices ואז ל-openDevice לכל מכשיר.

פרמטרים

החזרות

  • Promise<ConnectionHandle[]>

    Chrome 116 ואילך

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

getConfiguration()

Promise 
chrome.usb.getConfiguration(
  handle: ConnectionHandle,
  callback?: function,
)

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

    חיבור פתוח למכשיר.

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

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

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

    (config: ConfigDescriptor) => void

החזרות

  • Promise&lt;ConfigDescriptor&gt;

    Chrome 116 ואילך

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

getConfigurations()

הבטחה Chrome מגרסה 47 ואילך 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
)

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

פרמטרים

  • מכשיר

    מכשיר

    Device שממנו יש לאחזר תיאורים.

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

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

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

    (configs: ConfigDescriptor[]) => void

החזרות

  • Promise<ConfigDescriptor[]>

    Chrome 116 ואילך

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

getDevices()

הבטחה 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
)

מציגה את רשימת התקני ה-USB המחוברים.

פרמטרים

  • אפשרויות

    EnumerateDevicesOptions

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

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

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

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

    (devices: Device[]) => void

החזרות

  • Promise<Device[]>

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

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

getUserSelectedDevices()

Promise 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    DevicePromptOptions

    הגדרת תיבת הדו-שיח של בורר המכשירים.

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

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

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

    (devices: Device[]) => void

החזרות

  • Promise<Device[]>

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

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

interruptTransfer()

הבטחה 
chrome.usb.interruptTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

מבצע העברת הפרעות במכשיר שצוין.

פרמטרים

החזרות

  • Promise&lt;TransferResultInfo&gt;

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

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

isochronousTransfer()

הבטחה 
chrome.usb.isochronousTransfer(
  handle: ConnectionHandle,
  transferInfo: IsochronousTransferInfo,
  callback?: function,
)

ביצוע העברה איסוכרונית במכשיר הספציפי.

פרמטרים

החזרות

  • Chrome מגרסה 116 ואילך

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

listInterfaces()

הבטחה 
chrome.usb.listInterfaces(
  handle: ConnectionHandle,
  callback?: function,
)

רשימה של כל הממשקים במכשיר USB.

פרמטרים

החזרות

  • Chrome 116 ואילך

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

openDevice()

הבטחה 
chrome.usb.openDevice(
  device: Device,
  callback?: function,
)

פתיחת התקן USB שהוחזר על ידי getDevices.

פרמטרים

החזרות

  • Chrome 116 ואילך

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

releaseInterface()

Promise 
chrome.usb.releaseInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

    חיבור פתוח למכשיר.

  • interfaceNumber

    number

    הממשק להשקה.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 116 ואילך

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

requestAccess()

Promise Deprecated
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

הפונקציה הזו הייתה ספציפית ל-Chrome OS ולכן הפעלתה בפלטפורמות אחרות תיכשל. הפעולה הזו מתבצעת עכשיו באופן משתמע כחלק מ-openDevice, והפונקציה הזו תחזיר את הערך true בכל הפלטפורמות.

מבקש מברוקר ההרשאות גישה למכשיר ש-Chrome OS תבע עליו בעלות, אם לא נתבעה בעלות על הממשק הנתון במכשיר.

פרמטרים

  • מכשיר

    מכשיר

    Device שאליו צריך לבקש גישה.

  • interfaceId

    number

    הממשק הספציפי המבוקש.

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

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

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

    (success: boolean) => void

    • הצלחה

      בוליאני

החזרות

  • Promise<boolean>

    Chrome 116 ואילך

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

resetDevice()

הבטחה 
chrome.usb.resetDevice(
  handle: ConnectionHandle,
  callback?: function,
)

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

    נקודת אחיזה לחיבור לאיפוס.

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

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

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

    (success: boolean) => void

    • הצלחה

      בוליאני

החזרות

  • Promise<boolean>

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

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

setConfiguration()

הבטחה 
chrome.usb.setConfiguration(
  handle: ConnectionHandle,
  configurationValue: number,
  callback?: function,
)

בוחרים הגדרת מכשיר.

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

    חיבור פתוח למכשיר.

  • configurationValue

    number

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

setInterfaceAlternateSetting()

הבטחה 
chrome.usb.setInterfaceAlternateSetting(
  handle: ConnectionHandle,
  interfaceNumber: number,
  alternateSetting: number,
  callback?: function,
)

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • interfaceNumber

    number

    הממשק שרוצים להגדיר.

  • alternateSetting

    number

    ההגדרה החלופית שצריך להגדיר.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 116 ואילך

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

אירועים

onDeviceAdded

chrome.usb.onDeviceAdded.addListener(
  callback: function,
)

אירוע שנוצר כשמכשיר נוסף למערכת. אירועים משודרים רק לאפליקציות ולתוספים שיש להם הרשאת גישה למכשיר. יכול להיות שההרשאה ניתנה בזמן ההתקנה, כשהמשתמש אישר הרשאה אופציונלית (ראו permissions.request), או דרך getUserSelectedDevices.

פרמטרים

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

    פונקציה

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

    (device: Device) => void

onDeviceRemoved

chrome.usb.onDeviceRemoved.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    (device: Device) => void