chrome.usb

תיאור

אפשר להשתמש ב-chrome.usb API כדי לתקשר עם מכשירי 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").

  • אינדקס

    number

    השדה wIndex, ראו Ibid.

  • length

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

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

  • מקבל המתנה

    נמען

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

  • בקשה

    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 ואילך

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

  • serialNumber

    מחרוזת

    ‫Chrome 46 ואילך

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

  • vendorId

    number

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

  • גרסה

    number

    ‫Chrome 51+‎

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

DeviceFilter

מאפיינים

  • interfaceClass

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

    מחלקה של ממשק USB, תואמת לכל ממשק במכשיר.

  • interfaceProtocol

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

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

  • interfaceSubclass

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

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

  • productId

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

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

  • vendorId

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

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

DevicePromptOptions

מאפיינים

  • מסננים

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

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

  • כמה

    ‫boolean אופציונלי

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

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

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

  • length

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

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

  • פסק זמן

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

    ‫Chrome 43 ואילך

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

InterfaceDescriptor

מאפיינים

  • alternateSetting

    number

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

  • תיאור

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

    תיאור הממשק.

  • נקודות קצה

    ‫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>

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

פרמטרים

החזרות

  • ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

claimInterface()

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

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • interfaceNumber

    number

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

closeDevice()

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

    על ConnectionHandle כדי לסגור.

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

controlTransfer()

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

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

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

פרמטרים

החזרות

  • ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

findDevices()

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

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

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

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

פרמטרים

החזרות

  • Promise<ConnectionHandle[]>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getConfiguration()

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

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

פרמטרים

החזרות

  • ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getConfigurations()

Promise Chrome 47 ואילך 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
): Promise<ConfigDescriptor[]>

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

פרמטרים

החזרות

  • Promise<ConfigDescriptor[]>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getDevices()

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

מפרט את התקני ה-USB המחוברים.

פרמטרים

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

  • callback

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

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

    (devices: Device[]) => void

החזרות

  • Promise<Device[]>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getUserSelectedDevices()

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

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

פרמטרים

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

  • callback

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

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

    (devices: Device[]) => void

החזרות

  • Promise<Device[]>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

interruptTransfer()

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

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

פרמטרים

החזרות

  • ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

isochronousTransfer()

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

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

פרמטרים

החזרות

  • ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

listInterfaces()

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

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

פרמטרים

החזרות

  • ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

openDevice()

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

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

פרמטרים

החזרות

  • ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

releaseInterface()

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • interfaceNumber

    number

    הממשק שיושק.

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

requestAccess()

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

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

מבקש גישה מ-permission broker למכשיר שנתבע על ידי ChromeOS אם הממשק שצוין במכשיר לא נתבע.

פרמטרים

  • מכשיר

    מכשיר

    Device כדי לבקש גישה.

  • interfaceId

    number

    הממשק הספציפי שנדרש.

  • callback

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

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

    (success: boolean) => void

    • הצלחה

      בוליאני

החזרות

  • Promise<boolean>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

resetDevice()

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • callback

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

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

    (success: boolean) => void

    • הצלחה

      בוליאני

החזרות

  • Promise<boolean>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

setConfiguration()

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

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • configurationValue

    number

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

setInterfaceAlternateSetting()

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

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

פרמטרים

  • נקודת אחיזה

    ConnectionHandle

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

  • interfaceNumber

    number

    הממשק להגדרה.

  • alternateSetting

    number

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 116 ואילך

    ההבטחות נתמכות רק ב-Manifest 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