chrome.usb

תיאור

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

הרשאות

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, ראו Universal Serial Bus Specification Revision 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[] אופציונלי

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

  • כמה

    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 שצוינו לפי מזהי הספק, המוצר והממשק (אופציונלי), ואם ההרשאות מאפשרות זאת, היא פותחת אותם לשימוש.

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

הפעלת ה-method הזו שקולה להפעלת 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