chrome.usb

תיאור

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

הרשאות

usb

זמינות

ChromeOS בלבד

סוגים

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").

  • אינדקס

    number

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

  • length

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

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

  • מקבל המתנה

    נמען

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

  • בקשה

    number

    השדה bRequest, ראו מפרט של אפיק טורי אוניברסלי (USB), גרסה 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 ואילך

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

  • 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

    כתובת נקודת הקצה (endpoint).

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

    thought EndpointDescriptor[]‎

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

  • extra_data

    ArrayBuffer

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

  • interfaceClass

    number

    ממשק ה-USB.

  • interfaceNumber

    number

    מספר הממשק.

  • interfaceProtocol

    number

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

  • interfaceSubclass

    number

    ממשק המשנה של ממשק ה-USB.

IsochronousTransferInfo

מאפיינים

  • packetLength

    number

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

  • מנות

    number

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

  • transferInfo

    GenericTransferInfo

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

Recipient

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

"device"

"interface"

"endpoint"

"other"

RequestType

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

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

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

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

"asynchronous"

"adaptive"

"synchronous"

TransferResultInfo

מאפיינים

  • נתונים

    ‫ArrayBuffer אופציונלי

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

  • resultCode

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

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

TransferType

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

"control"

"interrupt"

"isochronous"

"bulk"

UsageType

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

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

Methods

bulkTransfer()

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

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

פרמטרים

החזרות

  • thought Promise<TransferResultInfo>

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

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

claimInterface()

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

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • interfaceNumber

    number

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

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

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

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

closeDevice()

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

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

פרמטרים

החזרות

  • Promise<void>

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

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

controlTransfer()

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

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

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

פרמטרים

החזרות

  • thought Promise<TransferResultInfo>

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

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

findDevices()

Promise 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
): Promise<ConnectionHandle[]>

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

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

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

פרמטרים

החזרות

  • Promise<ConnectionHandle[]>

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

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

getConfiguration()

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

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

פרמטרים

החזרות

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

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

getConfigurations()

Promise Chrome 47+‎ 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
): Promise<ConfigDescriptor[]>

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

פרמטרים

החזרות

  • Promise<ConfigDescriptor[]>

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

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

getDevices()

Promise 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
): Promise<Device[]>

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

פרמטרים

  • אפשרויות

    EnumerateDevicesOptions

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

  • callback

    function optional

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

    (devices: Device[]) => void

החזרות

  • Promise<Device[]>

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

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

getUserSelectedDevices()

Promise 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
): Promise<Device[]>

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

פרמטרים

  • אפשרויות

    DevicePromptOptions

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

  • callback

    function optional

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

    (devices: Device[]) => void

החזרות

  • Promise<Device[]>

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

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

interruptTransfer()

Promise 
chrome.usb.interruptTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

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

פרמטרים

החזרות

  • thought Promise<TransferResultInfo>

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

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

isochronousTransfer()

Promise 
chrome.usb.isochronousTransfer(
  handle: ConnectionHandle,
  transferInfo: IsochronousTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

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

פרמטרים

החזרות

  • thought Promise<TransferResultInfo>

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

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

listInterfaces()

Promise 
chrome.usb.listInterfaces(
  handle: ConnectionHandle,
  callback?: function,
): Promise<InterfaceDescriptor[]>

מציגה את כל הממשקים בהתקן USB.

פרמטרים

החזרות

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

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

openDevice()

Promise 
chrome.usb.openDevice(
  device: Device,
  callback?: function,
): Promise<ConnectionHandle>

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

פרמטרים

החזרות

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

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

releaseInterface()

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

משחרר ממשק שנתפס.

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • interfaceNumber

    number

    הממשק שצריך לשחרר.

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

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

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

requestAccess()

Promise הוצא משימוש
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
): Promise<boolean>

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

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

פרמטרים

  • מכשיר

    מכשיר

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

  • interfaceId

    number

    הממשק הספציפי שנכלל בבקשה.

  • callback

    function optional

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

    (success: boolean) => void

    • הצלחה

      בוליאני

החזרות

  • Promise<boolean>

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

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

resetDevice()

Promise 
chrome.usb.resetDevice(
  handle: ConnectionHandle,
  callback?: function,
): Promise<boolean>

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

    מזהה חיבור לאיפוס.

  • callback

    function optional

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

    (success: boolean) => void

    • הצלחה

      בוליאני

החזרות

  • Promise<boolean>

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

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

setConfiguration()

Promise 
chrome.usb.setConfiguration(
  handle: ConnectionHandle,
  configurationValue: number,
  callback?: function,
): Promise<void>

בוחרים תצורת מכשיר.

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • configurationValue

    number

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

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

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

setInterfaceAlternateSetting()

Promise 
chrome.usb.setInterfaceAlternateSetting(
  handle: ConnectionHandle,
  interfaceNumber: number,
  alternateSetting: number,
  callback?: function,
): Promise<void>

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • interfaceNumber

    number

    הממשק שצריך להגדיר.

  • alternateSetting

    number

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

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

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

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

אירועים

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