תיאור
שימוש ב-API chrome.usb
לאינטראקציה עם התקני USB מחוברים. ה-API הזה מספק גישה לפעולות USB מתוך הקשר של אפליקציה. באמצעות ה-API הזה, אפליקציות יכולות לתפקד כמנהלי התקנים עבור מכשירי חומרה. שגיאות שנוצרות על ידי ה-API הזה מדווחות על ידי הגדרה של runtime.lastError
וביצוע הקריאה החוזרת הרגילה של הפונקציה. במקרה הזה, הפרמטרים הרגילים של הקריאה החוזרת לא יהיו מוגדרים.
הרשאות
usb
סוגים
ConfigDescriptor
תכונות
-
פעיל
boolean
Chrome מגרסה 47 ואילךהאם זו ההגדרה הפעילה?
-
configurationValue
מספר
מספר ההגדרה האישית.
-
תיאור
מחרוזת אופציונלי
תיאור התצורה.
-
extra_data
ArrayBuffer
נתוני מתאר נוספים המשויכים לתצורה הזו.
-
ממשקים
ממשקים זמינים.
-
maxPower
מספר
ההספק המקסימלי שנדרש למכשיר הזה באלפיות השנייה (mA).
-
remoteWakeup
boolean
המכשיר תומך ביציאה ממצב שינה מרחוק.
-
selfPowered
boolean
המכשיר פועל באופן עצמאי.
ConnectionHandle
תכונות
-
כינוי
מספר
נקודת אחיזה אטומה שמייצגת את החיבור הזה להתקן ה-USB ולכל הממשקים המשויכים שנתבעו עליהם והעברות בהמתנה. בכל פעם שפותחים את המכשיר נוצר מזהה חדש. הכינוי של החיבור שונה מהכתובת
Device.device
. -
productId
מספר
מזהה המוצר
-
vendorId
מספר
המזהה של ספק המכשיר.
ControlTransferInfo
תכונות
-
נתונים
ArrayBuffer אופציונלי
הנתונים שיש לשדר (נדרשים רק לצורך העברות פלט).
-
direction
כיוון ההעברה (
"in"
או"out"
). -
index
מספר
השדה
wIndex
, ראה שם. -
length
מספר אופציונלי
המספר המקסימלי של בייטים לקבל (נדרש רק לצורך העברת קלט).
-
מקבל המתנה
יעד ההעברה. יש לתבוע בעלות על היעד שצוין על ידי
index
אם"interface"
או"endpoint"
. -
בקשה
מספר
השדה
bRequest
, ראה עדכון למפרט של אפיק טורי אוניברסלי 1.1 סעיף 9.3. -
requestType
סוג הבקשה.
-
פסק זמן
מספר אופציונלי
Chrome מגרסה 43 ואילךהזמן הקצוב לתפוגה של הבקשה (באלפיות השנייה). ערך ברירת המחדל
0
מציין שאין זמן קצוב לתפוגה. -
value
מספר
השדה
wValue
, ראה שם.
Device
תכונות
-
מכשיר
מספר
מזהה אטום של התקן ה-USB. הוא יישאר ללא שינוי עד לניתוק המכשיר.
-
manufacturerName
מחרוזת
Chrome 46 ואילךהמחרוזת של iManufacturer שנקראה מהמכשיר, אם היא זמינה.
-
productId
מספר
מזהה המוצר
-
productName
מחרוזת
Chrome 46 ואילךמחרוזת iProduct קוראת מהמכשיר, אם היא זמינה.
-
serialNumber
מחרוזת
Chrome 46 ואילךמחרוזת iSerialNumber קוראת מהמכשיר, אם היא זמינה.
-
vendorId
מספר
המזהה של ספק המכשיר.
-
גרסה
מספר
Chrome 51 ומעלהגרסת המכשיר (שדה bcdDevice).
DeviceFilter
תכונות
-
interfaceClass
מספר אופציונלי
סיווג ממשק USB, תואם לכל ממשק במכשיר.
-
interfaceProtocol
מספר אופציונלי
פרוטוקול ממשק USB, מסומן רק אם מחלקת המשנה של הממשק תואמת.
-
interfaceSubclass
מספר אופציונלי
מחלקה משנית של ממשק USB, מסומנת רק אם המחלקה של הממשק תואמת.
-
productId
מספר אופציונלי
מזהה המוצר של המכשיר, מסומן רק אם מזהה הספק תואם.
-
vendorId
מספר אופציונלי
מזהה ספק המכשיר.
DevicePromptOptions
תכונות
-
מסננים
DeviceFilter[] אופציונלי
לסנן את רשימת המכשירים המוצגים למשתמש. אם סופקו מסננים מרובים, יוצגו מכשירים שתואמים למסנן כלשהו.
-
מרובים
בוליאני אופציונלי
המשתמש יכול לבחור מספר מכשירים.
Direction
הכיוון, הנמען, RequestType ו-TransferType כולם ממופים לשמות שלהם במפרט של USB.
טיפוסים בני מנייה (enum)
EndpointDescriptor
תכונות
-
כתובת
מספר
כתובת נקודת הקצה.
-
direction
כיוון ההעברה.
-
extra_data
ArrayBuffer
נתוני תיאור נוספים המשויכים לנקודת הקצה הזו.
-
maximumPacketSize
מספר
גודל החבילה המקסימלי.
-
pollingInterval
מספר אופציונלי
מרווח תשאול (הפרעות ואי-איזוכרוניות בלבד).
-
סנכרון
SynchronizationType אופציונלי
מצב סנכרון העברה (איזוכרוני בלבד).
-
סוג
סוג ההעברה.
-
שימוש
UsageType אופציונלי
רמז לשימוש בנקודת קצה.
EnumerateDevicesAndRequestAccessOptions
תכונות
-
interfaceId
מספר אופציונלי
מזהה הממשק שצריך לבקש גישה אליו. התכונה הזו זמינה רק ב-ChromeOS. אין לה השפעה על פלטפורמות אחרות.
-
productId
מספר
מזהה המוצר
-
vendorId
מספר
המזהה של ספק המכשיר.
EnumerateDevicesOptions
תכונות
-
מסננים
DeviceFilter[] אופציונלי
יוחזר מכשיר שתואם לכל מסנן נתון. רשימת מסננים ריקה תחזיר את כל המכשירים שעבורם יש לאפליקציה הרשאה.
-
productId
מספר אופציונלי
הוצא משימושזהה להגדרה
DeviceFilter.productId
. -
vendorId
מספר אופציונלי
הוצא משימושזהה להגדרה
DeviceFilter.vendorId
.
GenericTransferInfo
תכונות
-
נתונים
ArrayBuffer אופציונלי
הנתונים שיש לשדר (נדרשים רק לצורך העברות פלט).
-
direction
כיוון ההעברה (
"in"
או"out"
). -
נקודת קצה (endpoint)
מספר
כתובת היעד של נקודת הקצה. יש להצהיר בעלות על הממשק שמכיל את נקודת הקצה הזו.
-
length
מספר אופציונלי
המספר המקסימלי של בייטים לקבל (נדרש רק לצורך העברת קלט).
-
פסק זמן
מספר אופציונלי
Chrome מגרסה 43 ואילךהזמן הקצוב לתפוגה של הבקשה (באלפיות השנייה). ערך ברירת המחדל
0
מציין שאין זמן קצוב לתפוגה.
InterfaceDescriptor
תכונות
-
alternateSetting
מספר
מספר ההגדרה החלופי של הממשק (ברירת המחדל היא
0
-
תיאור
מחרוזת אופציונלי
תיאור הממשק.
-
נקודות קצה
נקודות הקצה (endpoints) הזמינות.
-
extra_data
ArrayBuffer
נתוני תיאור נוספים המשויכים לממשק הזה.
-
interfaceClass
מספר
הסיווג של ממשק ה-USB.
-
interfaceNumber
מספר
מספר הממשק.
-
interfaceProtocol
מספר
פרוטוקול ממשק ה-USB.
-
interfaceSubclass
מספר
מחלקת המשנה של ממשק ה-USB.
IsochronousTransferInfo
תכונות
-
packetLength
מספר
האורך של כל אחת מהחבילות בהעברה הזו.
-
חבילות
מספר
המספר הכולל של החבילות בהעברה הזו.
-
transferInfo
פרמטרים של העברה. אורך ההעברה או מאגר הנתונים הזמני שצוינו בבלוק הפרמטרים הזה פוצל לאורך הגבולות
packetLength
כדי ליצור את החבילות הנפרדות של ההעברה.
Recipient
טיפוסים בני מנייה (enum)
"interface"
RequestType
טיפוסים בני מנייה (enum)
SynchronizationType
למצבי הפרעה ואיזוכרוניים, SynchronizationType ו-UsageType ממופים לשמות השמות שלהם במפרט ה-USB.
טיפוסים בני מנייה (enum)
TransferResultInfo
תכונות
-
נתונים
ArrayBuffer אופציונלי
הנתונים שמוחזרים באמצעות העברת קלט.
undefined
להעברות פלט. -
resultCode
מספר אופציונלי
הערך
0
מצביע על כך שההעברה הצליחה. ערכים אחרים מציינים כישלון.
TransferType
טיפוסים בני מנייה (enum)
UsageType
טיפוסים בני מנייה (enum)
שיטות
bulkTransfer()
chrome.usb.bulkTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
מבצע העברה בכמות גדולה במכשיר שצוין.
פרמטרים
-
כינוי
חיבור פתוח למכשיר.
-
transferInfo
הפרמטרים של ההעברה.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(info: TransferResultInfo) => void
-
מידע
-
החזרות
-
Promise<TransferResultInfo>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
claimInterface()
chrome.usb.claimInterface(
handle: ConnectionHandle,
interfaceNumber: number,
callback?: function,
)
הצהרת בעלות על ממשק במכשיר USB. כדי שניתן יהיה להעביר נתונים לממשק או לנקודות קצה משויכות, יש להצהיר בעלות בממשק. רק כינוי אחד לחיבור יכול להצהיר בעלות על ממשק בכל רגע נתון. אם כבר נתבעה בעלות על הממשק, השיחה תיכשל.
יש להפעיל את releaseInterface
כשלא יהיה יותר צורך בממשק.
פרמטרים
-
כינוי
חיבור פתוח למכשיר.
-
interfaceNumber
מספר
הממשק שלגביו הוגשה תלונה על הפרת זכויות יוצרים.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
closeDevice()
chrome.usb.closeDevice(
handle: ConnectionHandle,
callback?: function,
)
סוגר נקודת אחיזה לחיבור. הפעלת פעולות על כינוי אחרי שהוא נסגר היא פעולה בטוחה, אבל היא לא גורמת לביצוע פעולה כלשהי.
פרמטרים
-
כינוי
ConnectionHandle
שצריך לסגור. -
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
controlTransfer()
chrome.usb.controlTransfer(
handle: ConnectionHandle,
transferInfo: ControlTransferInfo,
callback?: function,
)
מבצע העברת בקרה במכשיר שצוין.
העברות בקרה מתייחס למכשיר, לממשק או לנקודת קצה. העברות לממשק או לנקודת קצה (endpoint) מחייבות להצהיר בעלות על הממשק.
פרמטרים
-
כינוי
חיבור פתוח למכשיר.
-
transferInfo
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(info: TransferResultInfo) => void
-
מידע
-
החזרות
-
Promise<TransferResultInfo>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
findDevices()
chrome.usb.findDevices(
options: EnumerateDevicesAndRequestAccessOptions,
callback?: function,
)
הפונקציה מחפשת התקני USB שצוינו על ידי הספק, המוצר ומזהי הממשק (אופציונלי), ואם ההרשאות מאפשרות לפתוח אותם לשימוש.
אם בקשת הגישה תידחה או שלא ניתן לפתוח את המכשיר, לא תיווצר או תוחזר כינוי לחיבור.
קריאה לשיטה הזו זהה להפעלה של getDevices
ולאחר מכן לחיצה על openDevice
בכל מכשיר.
פרמטרים
-
הנכסים שצריך לחפש במכשירי היעד.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(handles: ConnectionHandle[]) => void
-
כינויים
-
החזרות
-
Promise<ConnectionHandle[]>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
getConfiguration()
chrome.usb.getConfiguration(
handle: ConnectionHandle,
callback?: function,
)
הפונקציה מקבלת את מתאר ההגדרות האישיות שבחרת.
פרמטרים
-
כינוי
חיבור פתוח למכשיר.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(config: ConfigDescriptor) => void
-
config
-
החזרות
-
Promise<ConfigDescriptor>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
getConfigurations()
chrome.usb.getConfigurations(
device: Device,
callback?: function,
)
מחזירה את כל התיאורים של הגדרות המכשיר.
פרמטרים
-
מכשיר
ה-
Device
שממנו יש לאחזר תיאורים. -
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(configs: ConfigDescriptor[]) => void
-
הגדרות
-
החזרות
-
Promise<ConfigDescriptor[]>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
getDevices()
chrome.usb.getDevices(
options: EnumerateDevicesOptions,
callback?: function,
)
מונה את התקני ה-USB המחוברים.
פרמטרים
החזרות
-
הבטחה<מכשיר[]>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
getUserSelectedDevices()
chrome.usb.getUserSelectedDevices(
options: DevicePromptOptions,
callback?: function,
)
הצגה של בורר מכשירים למשתמש והחזרת הערכים של Device
שנבחרו. אם המשתמש יבטל, המכשירים בבורר יהיו ריקים. יש צורך בתנועה של המשתמש כדי שתיבת הדו-שיח תוצג. ללא תנועה מצד המשתמש, הקריאה החוזרת תפעל כאילו המשתמש ביטל.
פרמטרים
החזרות
-
הבטחה<מכשיר[]>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
interruptTransfer()
chrome.usb.interruptTransfer(
handle: ConnectionHandle,
transferInfo: GenericTransferInfo,
callback?: function,
)
מבצע העברת הפרעות במכשיר שצוין.
פרמטרים
-
כינוי
חיבור פתוח למכשיר.
-
transferInfo
הפרמטרים של ההעברה.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(info: TransferResultInfo) => void
-
מידע
-
החזרות
-
Promise<TransferResultInfo>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
isochronousTransfer()
chrome.usb.isochronousTransfer(
handle: ConnectionHandle,
transferInfo: IsochronousTransferInfo,
callback?: function,
)
מבצע העברה איזוכרונית במכשיר הספציפי.
פרמטרים
-
כינוי
חיבור פתוח למכשיר.
-
transferInfo
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(info: TransferResultInfo) => void
-
מידע
-
החזרות
-
Promise<TransferResultInfo>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
listInterfaces()
chrome.usb.listInterfaces(
handle: ConnectionHandle,
callback?: function,
)
רשימה של כל הממשקים בהתקן USB.
פרמטרים
-
כינוי
חיבור פתוח למכשיר.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(descriptors: InterfaceDescriptor[]) => void
-
descriptors
-
החזרות
-
Promise<InterfaceDescriptor[]>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
openDevice()
chrome.usb.openDevice(
device: Device,
callback?: function,
)
פתיחת התקן USB שהוחזר על ידי getDevices
.
פרמטרים
-
מכשיר
Device
שצריך לפתוח. -
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(handle: ConnectionHandle) => void
-
כינוי
-
החזרות
-
Promise<ConnectionHandle>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
releaseInterface()
chrome.usb.releaseInterface(
handle: ConnectionHandle,
interfaceNumber: number,
callback?: function,
)
משחרר ממשק שהוגשה לגביו תלונה.
פרמטרים
-
כינוי
חיבור פתוח למכשיר.
-
interfaceNumber
מספר
הממשק שמיועד להפצה.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
requestAccess()
chrome.usb.requestAccess(
device: Device,
interfaceId: number,
callback?: function,
)
הפונקציה הזו הייתה ספציפית למערכת ההפעלה של Chrome והקריאה אליה בפלטפורמות אחרות תיכשל. הפעולה הזו מתבצעת עכשיו באופן לא מפורש כחלק מ-openDevice
, והפונקציה הזו תחזיר true
בכל הפלטפורמות.
מבקש גישה מסוכן ההרשאות למכשיר שנתבע על ידי מערכת ההפעלה של Chrome אם לא נתבעה בעלות על הממשק הנתון במכשיר.
פרמטרים
-
מכשיר
Device
שאליהם צריך לבקש גישה. -
interfaceId
מספר
הממשק הספציפי המבוקש.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(success: boolean) => void
-
הצלחה
boolean
-
החזרות
-
Promise<boolean>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
resetDevice()
chrome.usb.resetDevice(
handle: ConnectionHandle,
callback?: function,
)
מנסה לאפס את התקן ה-USB. אם האיפוס ייכשל, נקודת האחיזה הנתונה תיסגר, ונראה שהתקן ה-USB מנותק ולאחר מכן מחובר מחדש. במקרה כזה, כדי לקבל את המכשיר צריך להפעיל את getDevices
או את findDevices
שוב.
פרמטרים
-
כינוי
נקודת אחיזה לאיפוס החיבור.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(success: boolean) => void
-
הצלחה
boolean
-
החזרות
-
Promise<boolean>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
setConfiguration()
chrome.usb.setConfiguration(
handle: ConnectionHandle,
configurationValue: number,
callback?: function,
)
בוחרים הגדרת מכשיר.
הפונקציה הזו מאפסת את המכשיר ביעילות על ידי בחירה באחת מההגדרות הזמינות למכשיר. רק ערכי תצורה גדולים מ-0
חוקיים. עם זאת, במכשירים מסוימים עם באגים יש הגדרות פעילות 0
, ולכן הערך הזה מותר.
פרמטרים
-
כינוי
חיבור פתוח למכשיר.
-
configurationValue
מספר
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
setInterfaceAlternateSetting()
chrome.usb.setInterfaceAlternateSetting(
handle: ConnectionHandle,
interfaceNumber: number,
alternateSetting: number,
callback?: function,
)
בוחרת הגדרה חלופית בממשק שכבר נתבעה עליו בעלות בעבר.
פרמטרים
-
כינוי
חיבור פתוח למכשיר שבו נתבעה בעלות על הממשק הזה.
-
interfaceNumber
מספר
הממשק שצריך להגדיר.
-
alternateSetting
מספר
ההגדרה החלופית שצריך להגדיר.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
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
.