בונים מכשיר כדי להפיק את המקסימום מ-WebUSB API.
מאמר זה מסביר איך לפתח מכשיר כדי להפיק את המרב WebUSB API. מבוא קצר ל-API עצמו ראו גישה להתקני USB באינטרנט.
רקע
האפיק הטורי האוניברסלי (USB) הפך לממשק הפיזי הנפוץ ביותר עבור חיבור של ציוד היקפי למחשבים ולמכשירים ניידים. נוסף ל- שמגדירים את המאפיינים החשמליים של האוטובוס ומודל כללי תקשורת עם מכשיר, מפרטי USB כוללים קבוצה של סיווג מכשיר מפרט. אלה מודלים כלליים לסוגים מסוימים של מכשירים, כמו אחסון, אודיו, וידאו, רשתות וכו' שיצרני מכשירים יכולים להטמיע. היתרון של המפרטים של קטגוריות המכשירים האלה הוא ספק של מערכת הפעלה יכול להטמיע מנהל התקן יחיד בהתאם לקטגוריה מפרט ("מנהל התקן של הכיתה") וכל מכשיר שמיישם את הסיווג הזה, נתמך. זה היה שיפור גדול לעומת כל היצרן שהיה צריך לכתוב מנהלי התקנים של עצמם.
עם זאת, חלק מהמכשירים לא מתאימים לאחד מסוגי המכשירים הסטנדרטיים האלה. א' היצרן יכול במקום זאת לבחור לתייג את המכשיר שלו כמטמיע סיווג ספציפי לספק. במקרה כזה מערכת ההפעלה בוחרת באיזה מכשיר טעינה בהתאם למידע שסופק בחבילת מנהל ההתקן של הספק, בדרך כלל קבוצה של מזהי ספקים ומזהי מוצרים שידועים כמטמיעים פרוטוקול ספציפי לספק מסוים.
תכונה נוספת של ה-USB היא שמכשירים עשויים לספק מספר ממשקים כדי המארח שאליו הם מחוברים. בכל ממשק יש אפשרות להטמיע במחלקה סטנדרטית או ספציפי לספק. כאשר מערכת הפעלה בוחרת את מנהלי ההתקנים הנכונים לטיפול במכשיר, כל ממשק יכול לתבוע בעלות על ידי לנהג. לדוגמה, מצלמת אינטרנט בחיבור USB בדרך כלל מספקת שני ממשקים, הטמעת סיווג וידאו USB (למצלמה) וסיווג אחד שמטמיע את ה-USB סיווג האודיו (במיקרופון). מערכת ההפעלה לא טוענת "מנהל מצלמת אינטרנט" אך במקום זאת טוען מנהלי התקנים עצמאיים של וידאו ואודיו שאחראים על הפונקציות הנפרדות של המכשיר. הזה של סיווגי ממשק מאפשרים גמישות רבה יותר.
עקרונות בסיסיים של API
רבים ממחלקות ה-USB הרגילות כוללות ממשקי API מתאימים לאינטרנט. לדוגמה,
הדף יכול לצלם סרטון ממכשיר של שיעור וידאו באמצעות getUserMedia()
או לקבל אירועי קלט ממכשיר ברמה של ממשק אנושי (HID) באמצעות האזנה
עבור KeyboardEvents או PointerEvents, או באמצעות Gamepad או
API של WebHID.
בדיוק כמו שלא כל המכשירים מתבססים על הגדרת סיווג סטנדרטית, לא כל המכשירים
מכשירים מטמיעים תכונות שמתאימות לממשקי ה-API הקיימים של פלטפורמת האינטרנט. מתי
במקרה כזה, ה-WebUSB API יכול למלא את הפער הזה על ידי מתן דרך לאתרים
כדי לתבוע בעלות על ממשק ספציפי לספק וליישם תמיכה בו ישירות
בדף שלהם.
הדרישות הספציפיות למכשיר כדי להיות נגיש באמצעות WebUSB משתנות מעט מפלטפורמות שונות בגלל הבדלים באופן שבו מערכות הפעלה מנהלות את חיבור ה-USB אבל הדרישה הבסיסית היא שבמכשיר לא צריכה להיות כבר של מנהל התקן שטוען בממשק שהדף רוצה לשלוט בו. הפריט יכול להיות מנהל התקן מחלקה גנרי שסופק על ידי ספק מערכת ההפעלה או מנהל התקן של מכשיר שסופק על ידי הספק. התקני USB יכולים לספק ממשקים מרובים, ולכל אחד מהם יש מנהל התקן משלו, אפשר לפתח מכשיר שעבורו מחויבים על ידי נהג, ואחרים נשארים נגישים לדפדפן.
לדוגמה, מקלדת USB מתקדמת עשויה לספק ממשק ברמה HID אשר ידרוש בעלות על ידי מערכת המשנה לקלט של מערכת ההפעלה, ממשק שנשאר זמין ל-WebUSB לשימוש על ידי כלי תצורה. הזה יכול להיות מוצג באתר היצרן ומאפשר למשתמש לשנות בתפקוד של המכשיר, כמו מקשי מאקרו ואפקטי תאורה או להתקין תוכנה ספציפית לפלטפורמה. מתאר תצורה של מכשיר כזה ייראה בערך כך:
ערך | שדה | תיאור |
---|---|---|
מתאר ההגדרות | ||
0x09 |
bLength | גודל התיאור הזה |
0x02 |
bDescriptorType | מתאר ההגדרות |
0x0039 |
wTotalLength | האורך הכולל של סדרת התיאורים הזו |
0x02 |
bNumInterfaces | מספר הממשקים |
0x01 |
bConfigurationValue | הגדרה 1 |
0x00 |
iConfiguration | שם ההגדרה האישית (ללא) |
0b1010000 |
bmAttributes | מכשיר שפועל באופן עצמאי עם יציאה ממצב שינה מרחוק |
0x32 |
bMaxPower | ההספק המקסימלי מבוטא במרווחים של 2 מיליאמפר לשעה |
מתאר ממשק | ||
0x09 |
bLength | גודל התיאור הזה |
0x04 |
bDescriptorType | מתאר ממשק |
0x00 |
bInterfaceNumber | ממשק 0 |
0x00 |
bAlternateSetting | הגדרה חלופית 0 (ברירת מחדל) |
0x01 |
bNumEndpoints | נקודת קצה אחת |
0x03 |
bInterfaceClass | סיווג ממשק HID |
0x01 |
bInterfaceSubClass | מחלקה משנית של ממשק ההפעלה |
0x01 |
bInterfaceProtocol | מקלדת |
0x00 |
iInterface | שם הממשק (ללא) |
מתאר HID | ||
0x09 |
bLength | גודל התיאור הזה |
0x21 |
bDescriptorType | מתאר HID |
0x0101 |
bcdHID | ממשק אנושי (HID) גרסה 1.1 |
0x00 |
bCountryCode | מדינת היעד של החומרה |
0x01 |
bNumDescriptors | מספר מתארי סיווג HID שיש לעקוב אחריהם |
0x22 |
bDescriptorType | סוג מתאר הדוח |
0x003F |
wDescriptorLength | האורך הכולל של מתאר הדוח |
מתאר של נקודת קצה | ||
0x07 |
bLength | גודל התיאור הזה |
0x05 |
bDescriptorType | מתאר של נקודת קצה |
0b10000001 |
bEndpointAddress | נקודת קצה 1 (IN) |
0b00000011 |
bmAttributes | הפרעה |
0x0008 |
wMaxPacketSize | חבילות בנפח 8 בייטים |
0x0A |
bInterval | מרווח של 10 אלפיות השנייה |
מתאר ממשק | ||
0x09 |
bLength | גודל התיאור הזה |
0x04 |
bDescriptorType | מתאר ממשק |
0x01 |
bInterfaceNumber | ממשק 1 |
0x00 |
bAlternateSetting | הגדרה חלופית 0 (ברירת מחדל) |
0x02 |
bNumEndpoints | 2 נקודות קצה |
0xFF |
bInterfaceClass | סיווג ממשק ספציפי לספק |
0x00 |
bInterfaceSubClass | |
0x00 |
bInterfaceProtocol | |
0x00 |
iInterface | שם הממשק (ללא) |
מתאר של נקודת קצה | ||
0x07 |
bLength | גודל התיאור הזה |
0x05 |
bDescriptorType | מתאר של נקודת קצה |
0b10000010 |
bEndpointAddress | נקודת קצה 1 (IN) |
0b00000010 |
bmAttributes | קבוצתי |
0x0040 |
wMaxPacketSize | חבילות בנפח 64 בייטים |
0x00 |
bInterval | לא רלוונטי לנקודות קצה בכמות גדולה |
מתאר של נקודת קצה | ||
0x07 |
bLength | גודל התיאור הזה |
0x05 |
bDescriptorType | מתאר של נקודת קצה |
0b00000011 |
bEndpointAddress | נקודת קצה 3 (פלט) |
0b00000010 |
bmAttributes | קבוצתי |
0x0040 |
wMaxPacketSize | חבילות בנפח 64 בייטים |
0x00 |
bInterval | לא רלוונטי לנקודות קצה בכמות גדולה |
מתאר התצורה מורכב מכמה תיאורים מחוברים בשרשור
את כל החלקים. כל אחד מהם מתחיל בשדות bLength
ו-bDescriptorType
, כך
. הממשק הראשון הוא ממשק ממשק אנושי (HID) עם
מתאר HID ונקודת קצה (endpoint) אחת שמשמשים להעברת אירועי קלט
מערכת ההפעלה. הממשק השני הוא ממשק ספציפי לספק שכולל
נקודות קצה שאפשר להשתמש בהן כדי לשלוח פקודות למכשיר ולקבל תשובות
בתמורה.
מתארי WebUSB
WebUSB יכול לפעול עם מכשירים רבים ללא שינויים בקושחה, אבל פונקציונליות נוספת מופעלת על ידי סימון המכשיר באמצעות שמתארים תמיכה ב-WebUSB. לדוגמה, ניתן לציין לכתובת דף הנחיתה שאליה הדפדפן יכול להפנות את המשתמש כשהמכשיר שמחוברת לחשמל.
![צילום מסך של התראת WebUSB ב-Chrome](https://developer.chrome.com/static/docs/capabilities/build-for-webusb/image/screenshot-the-webusb-no-531009ef49311.png?authuser=5&hl=he)
Binary device Object Store (BOS) הוא קונספט שהושק ב-USB 3.0, אבל גם הועברו לאחור למכשירי USB 2.0 כחלק מגרסה 2.1. מצהיר התמיכה ב-WebUSB מתחילה ולכלול את יכולות הפלטפורמה הבאות מתאר במתאר BOS:
ערך | שדה | תיאור |
---|---|---|
מתאר של מאגר אובייקטים בינאריים של מכשירים | ||
0x05 |
bLength | גודל התיאור הזה |
0x0F |
bDescriptorType | מתאר של מאגר אובייקטים בינאריים של מכשירים |
0x001D |
wTotalLength | האורך הכולל של סדרת התיאורים הזו |
0x01 |
bNumDeviceCaps | מספר התיאורים של יכולת המכשיר ב-BOS |
מתאר יכולת של פלטפורמת WebUSB | ||
0x18 |
bLength | גודל התיאור הזה |
0x10 |
bDescriptorType | מתאר של יכולת המכשיר |
0x05 |
bDevCapabilityType | מתאר של יכולת הפלטפורמה |
0x00 |
bReserved | |
{0x38, 0xB6, 0x08, 0x34, 0xA9, 0x09, 0xA0, 0x47, 0x8B, 0xFD, 0xA0, 0x76, 0x88, 0x15, 0xB6, 0x65} |
PlatformCapablityUUID | GUID של מתאר יכולת של פלטפורמת WebUSB בפורמט קטן |
0x0100 |
bcdVersion | גרסה 1.0 של מתאר WebUSB |
0x01 |
bVendorCode | ערך bRequest בשביל WebUSB |
0x01 |
iLandingPage | כתובת ה-URL של דף הנחיתה |
ה-UUID של יכולת הפלטפורמה מזהה זאת כיכולת של פלטפורמת WebUSB
descriptor, שמספק מידע בסיסי על המכשיר. לדפדפן
כדי לאחזר מידע נוסף על המכשיר שבו הוא משתמש בערך bVendorCode
להנפיק בקשות נוספות למכשיר. הבקשה היחידה שצוינה כרגע היא
הפונקציה GET_URL
מחזירה מתאר כתובת URL. הן דומות למחרוזת
שמתארים כתובות URL, אבל הן נועדו לקודד כתובות URL עם הכי פחות בייטים. כתובת URL
מתאר של "https://google.com"
ייראה כך:
ערך | שדה | תיאור |
---|---|---|
מתאר כתובת URL | ||
0x0D |
bLength | גודל התיאור הזה |
0x03 |
bDescriptorType | מתאר כתובת URL |
0x01 |
bScheme | https:// |
"google.com" |
כתובת URL | תוכן כתובת URL בקידוד UTF-8 |
כשהמכשיר מחובר בפעם הראשונה לדפדפן, הוא יקרא את מתאר BOS באמצעות
הנפקת העברת בקרה רגילה של GET_DESCRIPTOR
:
bmRequestType | bRequest | wValue | wIndex | wLength | נתונים (תגובה) |
---|---|---|---|---|---|
0b10000000 |
0x06 |
0x0F00 |
0x0000 |
* | מתאר BOS |
הבקשה הזו נשלחת בדרך כלל פעמיים, בפעם הראשונה עם ערך wLength
גדול מספיק
כך שהמארח מוצא את הערך של השדה wTotalLength
ללא
התחייבות להעברה גדולה ואז שוב כשאורך התיאור המלא
ידוע.
אם במתאר של יכולת הפלטפורמה WebUSB השדה iLandingPage
מוגדר להיות
ערך שאינו אפס, הדפדפן מבצע בקשת GET_URL
ספציפית ל-WebUSB
על ידי ביצוע העברת בקרה כאשר bRequest
מוגדר לערך bVendorCode
ממתאר היכולת של הפלטפורמה ו-wValue
מוגדרים לערך iLandingPage
עם ערך מסוים. קוד הבקשה עבור GET_URL
(0x02
) נכנס ב-wIndex
:
bmRequestType | bRequest | wValue | wIndex | wLength | נתונים (תגובה) |
---|---|---|---|---|---|
0b11000000 |
0x01 |
0x0001 |
0x0002 |
* | מתאר כתובת ה-URL |
שוב, ייתכן שהבקשה הזו תישלח פעמיים כדי לבחון קודם את משך הזמן של המתאר שנקרא.
שיקולים ספציפיים לפלטפורמה
אמנם WebUSB API מנסה לספק ממשק עקבי לגישה מפתחים של התקני USB עדיין צריכים להיות מודעים לדרישות שהוטלו אפליקציות כמו דרישות של דפדפני אינטרנט כדי לגשת למכשירים.
macOS
לא נדרש שום דבר מיוחד ב-macOS. אתר שמשתמש ב-WebUSB יכול להתחבר אל על המכשיר ותובעים בעלות על ממשקים שלא נתבעה עליהם בעלות על ידי מנהל התקן ליבה, או לאפליקציה אחרת.
Linux
Linux היא כמו macOS, אבל כברירת מחדל רוב ההפצות לא מגדירות משתמש
חשבונות עם הרשאה לפתוח התקני USB. דימון (daemon) של מערכת שנקרא udev
שאחראים להקצאת המשתמש והקבוצה שמורשים לגשת למכשיר. כלל
כמו הפעולה הזו תקצה בעלות על מכשיר שתואם לספק הנתון
מזהי המוצרים בקבוצה plugdev
, שהיא קבוצה נפוצה של משתמשים שיש להם גישה
לציוד היקפי:
SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="XXXX", GROUP="plugdev"
מחליפים את XXXX
במזהי המוצרים והספק ההקסדצימליים של המכשיר.
לדוגמה ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11"
מתאים ל-Nexus One
בטלפון. יש לכתוב את הערכים האלה ללא "0x" הרגיל תחילית וכל האותיות צריכות להיות קטנות.
כדי שנוכל לזהות אותו בצורה נכונה. כדי למצוא את המזהים של המכשיר, מריצים את שורת הפקודה
כלי lsusb
.
צריך למקם את הכלל הזה בקובץ בספרייה /etc/udev/rules.d
ואז
תיכנס לתוקף ברגע שהמכשיר יחובר לחשמל. אין צורך להפעיל מחדש
udev.
Android
פלטפורמת Android מבוססת על Linux, אבל לא דורשת לבצע בה שינויים כדי
להגדרת המערכת. כברירת מחדל כל מכשיר ללא מנהל התקן מובנה
למערכת ההפעלה שהיא זמינה לדפדפן. המפתחים צריכים להיות
אבל המשתמשים יצפו בשלב נוסף כשהם מתחברים אל
במכשיר. לאחר שמשתמש בוחר מכשיר בתגובה לקריאה אל
requestDevice()
, תוצג ב-Android בקשה אם לאשר
Chrome כדי לגשת אליו. ההנחיה הזאת מופיעה שוב אם משתמש חוזר לאתר
שכבר יש להם הרשאה להתחבר למכשיר והאתר מתקשר
open()
בנוסף, יותר מכשירים יהיו נגישים ב-Android מאשר ב-Linux במחשב כי פחות נהגים נכללים כברירת מחדל. השמטה חשובה, למשל, המחלקה של USB CDC-ACM מיושמת בדרך כלל על ידי מתאמים מסוג USB-לטוריות, אין API ב-Android SDK לצורך תקשורת עם מכשיר עם יציאה טורית.
ChromeOS
גם ChromeOS מבוסס על Linux ולא צריך לבצע בו שינויים לתצורת המערכת. השירות Allow_broker שולט בגישה ל-USB והם יאפשרו לדפדפן לגשת אליהם כל עוד הם נמצאים ממשק אחד שלא נתבעה עליו בעלות.
Windows
מודל מנהל ההתקן של Windows כולל דרישה נוספת. בניגוד ל- פלטפורמות שמעל היכולת לפתוח התקן USB מאפליקציה של משתמש ברירת המחדל, גם אם לא נטען מנהל התקן. במקום זאת יש מנהל התקן WinUSB, שאותו צריך לטעון כדי לספק את הממשק אפליקציות שמשמשות לגישה למכשיר. אפשר לעשות את זה בשתי דרכים את קובץ המידע של מנהל ההתקנים (INF) שמותקן במערכת או על ידי שינוי המכשיר קושחה שמאפשרת לספק את תיאורי התאימות של Microsoft OS במהלך ספירה.
קובץ מידע לנהג (INF)
קובץ מידע של מנהל התקן מורה ל-Windows מה לעשות כאשר נתקלים במכשיר
בפעם הראשונה. מאחר שמערכת המשתמש כבר כוללת את מנהל התקן WinUSB
כל מה שצריך הוא כדי שקובץ ה-INF ישייך את הספק ואת מזהה המוצר
עם כלל ההתקנה החדש הזה. הקובץ הבא הוא דוגמה בסיסית. שומרים את הגרסה
קובץ עם הסיומת .inf
, משנים את הקטעים המסומנים ב-X ואז שמאלה
לוחצים עליו ובוחרים באפשרות 'התקנה' מתפריט ההקשר.
[Version]
Signature = "$Windows NT$"
Class = USBDevice
ClassGUID = {88BAE032-5A81-49f0-BC3D-A4FF138216D6}
Provider = %ManufacturerName%
CatalogFile = WinUSBInstallation.cat
DriverVer = 09/04/2012,13.54.20.543
; ========== Manufacturer/Models sections ===========
[Manufacturer]
%ManufacturerName% = Standard,NTx86,NTia64,NTamd64
[Standard.NTx86]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX
[Standard.NTia64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX
[Standard.NTamd64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX
; ========== Class definition ===========
[ClassInstall32]
AddReg = ClassInstall_AddReg
[ClassInstall_AddReg]
HKR,,,,%ClassName%
HKR,,NoInstallClass,,1
HKR,,IconPath,%REG_MULTI_SZ%,"%systemroot%\system32\setupapi.dll,-20"
HKR,,LowerLogoVersion,,5.2
; =================== Installation ===================
[USB_Install]
Include = winusb.inf
Needs = WINUSB.NT
[USB_Install.Services]
Include = winusb.inf
Needs = WINUSB.NT.Services
[USB_Install.HW]
AddReg = Dev_AddReg
[Dev_AddReg]
HKR,,DeviceInterfaceGUIDs,0x10000,"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
; =================== Strings ===================
[Strings]
ManufacturerName = "Your Company Name Here"
ClassName = "Your Company Devices"
USB\MyCustomDevice.DeviceDesc = "Your Device Name Here"
הקטע [Dev_AddReg]
מגדיר את הקבוצה של DeviceInterfaceGUID עבור
במכשיר. כל ממשק של מכשיר חייב לכלול GUID כדי שאפליקציה
למצוא אותו ולהתחבר אליו באמצעות ממשק ה-API של Windows. שימוש ב-PowerShell של New-Guid
cmdlet או כלי אונליין ליצירת GUID אקראי.
למטרות פיתוח, הכלי של Zadig מספק ממשק פשוט ונוח החלפת מנהל ההתקן הטעון בממשק USB במנהל התקן WinUSB.
תיאורי תאימות של Microsoft OS
הגישה של קובץ INF שלמעלה מסורבלת כי היא דורשת הגדרה של כל במחשב של המשתמש מראש. Windows 8.1 ואילך מציעה חלופה באמצעות שימוש במתארי USB מותאמים אישית. התיאורים האלה מספקים מידע למערכת ההפעלה Windows בפעם הראשונה שהמכשיר מחובר לחשמל, בדרך כלל נכללות בקובץ INF.
אחרי שמגדירים מתארי WebUSB קל להוסיף את מערכת ההפעלה של Microsoft
גם מתארי תאימות. קודם צריך להרחיב את מתאר BOS באמצעות
מתאר יכולת של פלטפורמה נוספת. חשוב לעדכן את wTotalLength
ו-bNumDeviceCaps
כדי להביא בחשבון.
ערך | שדה | תיאור |
---|---|---|
מתאר יכולת של פלטפורמת Microsoft OS 2.0 | ||
0x1C |
bLength | גודל התיאור הזה |
0x10 |
bDescriptorType | מתאר של יכולת המכשיר |
0x05 |
bDevCapabilityType | מתאר של יכולת הפלטפורמה |
0x00 |
bReserved | |
{0xDF, 0x60, 0xDD, 0xD8, 0x89, 0x45, 0xC7, 0x4C, 0x9C, 0xD2, 0x65, 0x9D, 0x9E, 0x64, 0x8A, 0x9F} |
PlatformCapablityUUID | GUID של מתאר תאימות לפלטפורמה של Microsoft OS 2.0 בפורמט קטן |
0x06030000 |
dwWindowsVersion | גרסה מינימלית תואמת של Windows (Windows 8.1) |
0x00B2 |
wMSOSDescriptorSetTotalLength | האורך הכולל של קבוצת התיאור |
0x02 |
bMS_VendorCode | ערך bRequest לאחזור תיאורי Microsoft נוספים |
0x00 |
bAltEnumCode | המכשיר לא תומך בספירה חלופית |
בדומה למתארי WebUSB, צריך לבחור ערך bRequest
שישמש את
לשלוט בהעברות שקשורות לתיאורים האלה. בדוגמה הזאת בחרתי
0x02
הפקודה 0x07
, שממוקמת ב-wIndex
, היא הפקודה לאחזור של Microsoft OS
2.0 מתאר מהמכשיר.
bmRequestType | bRequest | wValue | wIndex | wLength | נתונים (תגובה) |
---|---|---|---|---|---|
0b11000000 |
0x02 |
0x0000 |
0x0007 |
* | ערכת תיאור של MS OS 2.0 |
להתקן USB יכולות להיות מספר פונקציות, ולכן החלק הראשון של מתאר
set מתאר לאיזה פונקציה המאפיינים הבאים משויכים.
בדוגמה הבאה מגדיר את ממשק 1 של מכשיר מורכב. המתאר מעניק
לגבי מערכת ההפעלה, שני פריטי מידע חשובים לגבי הממשק הזה. הגרסה התואמת
מתאר מזהה אומר ל-Windows שהמכשיר הזה תואם ל-WinUSB
לנהג. מתאר מאפיין המרשם פועל באופן דומה
הקטע [Dev_AddReg]
בדוגמת INF שלמעלה, הגדרת נכס מרשם בתור
צריך להקצות לפונקציה הזו GUID של ממשק המכשיר.
ערך | שדה | תיאור |
---|---|---|
כותרת של קבוצת מתאר של Microsoft OS 2.0 | ||
0x000A |
wLength | גודל התיאור הזה |
0x0000 |
wDescriptorType | מתאר כותרת של קבוצת מתאר |
0x06030000 |
dwWindowsVersion | גרסה מינימלית תואמת של Windows (Windows 8.1) |
0x00B2 |
wTotalLength | האורך הכולל של קבוצת התיאור |
כותרת משנה של תצורת Microsoft OS 2.0 | ||
0x0008 |
wLength | גודל התיאור הזה |
0x0001 |
wDescriptorType | תיאור כותרת המשנה של ההגדרה |
0x00 |
bConfigurationValue | חלה על הגדרה 1 (נוספה לאינדקס מ-0 למרות ההגדרות בדרך כלל נוספים לאינדקס מ-1) |
0x00 |
bReserved | הערך חייב להיות 0 |
0x00A8 |
wTotalLength | האורך הכולל של קבוצת המשנה, כולל הכותרת הזו |
כותרת משנה של פונקציית Microsoft OS 2.0 | ||
0x0008 |
wLength | גודל התיאור הזה |
0x0002 |
wDescriptorType | מתאר כותרת של פונקציה |
0x01 |
bFirstInterface | הממשק הראשון של הפונקציה |
0x00 |
bReserved | הערך חייב להיות 0 |
0x00A0 |
wSubsetLength | האורך הכולל של קבוצת המשנה, כולל הכותרת הזו |
מתאר מזהה תואם ל-Microsoft OS 2.0 | ||
0x0014 |
wLength | גודל התיאור הזה |
0x0003 |
wDescriptorType | מתאר מזהה תואם |
"WINUSB\0\0" |
CompatibileID | מחרוזת ASCII מצורפת ל-8 בייטים |
"\0\0\0\0\0\0\0\0" |
SubCompatibleID | מחרוזת ASCII מצורפת ל-8 בייטים |
מתאר מאפיין רישום של Microsoft OS 2.0 | ||
0x0084 |
wLength | גודל התיאור הזה |
0x0004 |
wDescriptorType | מתאר מאפיין במרשם |
0x0007 |
wPropertyDataType | REG_MULTI_SZ |
0x002A |
wPropertyNameLength | אורך שם הנכס |
"DeviceInterfaceGUIDs\0" |
PropertyName | שם מאפיין עם מסוף null בקידוד UTF-16LE |
0x0050 |
wPropertyDataLength | אורך ערך המאפיין |
"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}\0\0" |
PropertyData | GUID ושני מספרי null מקודדים ב-UTF-16LE |
מערכת Windows תשלח שאילתה למכשיר כדי לקבל את המידע הזה פעם אחת בלבד. אם המכשיר לא יגיב עם תיאורים חוקיים הוא לא ישאל שוב בפעם הבאה המכשיר מחובר. Microsoft סיפקה רשימה של מרשם מכשירי USB רשומות שמתארות את ערכי המרשם שנוצרים בזמן ספירת המכשיר. מתי בדיקה תמחק את הרשומות שנוצרו במכשיר כדי לאלץ את Windows לנסות לקרוא את התיאורים שוב.
מידע נוסף זמין בפוסט בבלוג של Microsoft שמסביר איך להשתמש בהם ומתארים.
דוגמאות
קוד לדוגמה שמטמיע התקנים תואמי WebUSB שכוללים גם WebUSB קיימים תיאורים של Microsoft OS בפרויקטים הבאים: