chrome.usb

תיאור

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

הרשאות

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, ראו שם.

  • length

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

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

  • מקבל המתנה

    נמען

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

  • בקשה

    number

    השדה bRequest, ראה Universal Series Specification גרסה 1.1 § 9.3.

  • requestType

    RequestType

    סוג הבקשה.

  • פסק זמן

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

    Chrome 43 ואילך

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

  • ערך

    number

    השדה wValue, ראו שם.

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

כיוונים, נמען, RequestType ו-TransferType ממופים כולם לשמות שלהם במפרט ה-USB.

Enum

"in"

"לא"

EndpointDescriptor

מאפיינים

  • כתובת

    number

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

  • direction

    כיוון

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

  • extra_data

    ArrayBuffer

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

  • maximumPacketSize

    number

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

  • pollingInterval

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

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

  • סנכרון

    SynchronizationType אופציונלי

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

  • סוג

    TransferType

    סוג ההעברה.

  • שימוש

    UsageType אופציונלי

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

EnumerateDevicesAndRequestAccessOptions

מאפיינים

  • interfaceId

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

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

  • productId

    number

    מזהה המוצר

  • vendorId

    number

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

EnumerateDevicesOptions

מאפיינים

  • מסננים

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

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

  • productId

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

    הוצא משימוש

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

  • vendorId

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

    הוצא משימוש

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

GenericTransferInfo

מאפיינים

  • נתונים

    ArrayBuffer אופציונלי

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

  • direction

    כיוון

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

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

    number

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

  • 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

"מכשיר"

"interface"

"נקודת קצה"

"אחר"

RequestType

Enum

"רגילה"

"class"

"ספק"

"שמור"

SynchronizationType

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

Enum

"אסינכרוני"

'מותאם'

"סינכרוני"

TransferResultInfo

מאפיינים

  • נתונים

    ArrayBuffer אופציונלי

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

  • resultCode

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

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

TransferType

Enum

"control"

"הפרעה"

"איזוכרון"

"כמות גדולה"

UsageType

Enum

"data"

"משוב"

"explicitFeedback"

"תקופתי"

"התראה"

שיטות

bulkTransfer()

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

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

פרמטרים

החזרות

  • Promise<TransferResultInfo>

    Chrome 116 ואילך

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

claimInterface()

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

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • interfaceNumber

    number

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 116 ואילך

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

closeDevice()

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

    ConnectionHandle לסגירה.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 116 ואילך

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

controlTransfer()

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

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

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

פרמטרים

החזרות

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 ואילך

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

findDevices()

הבטחה 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
)

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

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

השיטה הזו מקבילה להפעלה של getDevices ואחריה openDevice לכל מכשיר.

פרמטרים

החזרות

  • Promise&lt;ConnectionHandle[]&gt;

    Chrome 116 ואילך

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

getConfiguration()

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

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

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

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

    (config: ConfigDescriptor) => void

החזרות

  • Promise&lt;ConfigDescriptor&gt;

    Chrome 116 ואילך

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

getConfigurations()

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

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

פרמטרים

  • מכשיר

    מכשיר

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

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

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

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

    (configs: ConfigDescriptor[]) => void

החזרות

  • Promise&lt;ConfigDescriptor[]&gt;

    Chrome 116 ואילך

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

getDevices()

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

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

פרמטרים

  • אפשרויות

    EnumerateDevicesOptions

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

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

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

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

    (devices: Device[]) => void

החזרות

  • התחייבות<מכשיר[]>

    Chrome 116 ואילך

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

getUserSelectedDevices()

הבטחה 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    DevicePromptOptions

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

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

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

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

    (devices: Device[]) => void

החזרות

  • התחייבות<מכשיר[]>

    Chrome 116 ואילך

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

interruptTransfer()

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

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

פרמטרים

החזרות

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 ואילך

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

isochronousTransfer()

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

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

פרמטרים

החזרות

  • Promise&lt;TransferResultInfo&gt;

    Chrome 116 ואילך

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

listInterfaces()

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

בתיבת הדו-שיח הזו מפורטים כל הממשקים בהתקן USB.

פרמטרים

החזרות

  • Promise&lt;InterfaceDescriptor[]&gt;

    Chrome 116 ואילך

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

openDevice()

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

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

פרמטרים

החזרות

  • Promise&lt;ConnectionHandle&gt;

    Chrome 116 ואילך

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

releaseInterface()

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • interfaceNumber

    number

    הממשק להשקה.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 116 ואילך

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

requestAccess()

הבטחה הוצא משימוש
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

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

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

פרמטרים

  • מכשיר

    מכשיר

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

  • interfaceId

    number

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

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

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

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

    (success: boolean) => void

    • הצלחה

      בוליאני

החזרות

  • Promise&lt;boolean&gt;

    Chrome 116 ואילך

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

resetDevice()

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

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

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

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

    (success: boolean) => void

    • הצלחה

      בוליאני

החזרות

  • Promise&lt;boolean&gt;

    Chrome 116 ואילך

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

setConfiguration()

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

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • configurationValue

    number

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 116 ואילך

    הבטחות נתמכות רק במניפסט מגרסה 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