בונים מכשיר כדי להפיק את המקסימום מ-WebUSB API.
במאמר הזה מוסבר איך לפתח מכשיר כדי להפיק את המקסימום מ-WebUSB API. מבוא קצר ל-API עצמו מופיע במאמר גישה להתקני USB באינטרנט.
רקע
האפיק הטורי האוניברסלי (USB) הפך לממשק הפיזי הנפוץ ביותר לחיבור ציוד היקפי למכשירי מחשוב נייחים וניידים. בנוסף להגדרת המאפיינים החשמליים של האוטובוס ודגם כללי לתקשורת עם המכשיר, מפרטי ה-USB כוללים גם קבוצת מפרטים של סיווג המכשיר. אלה מודלים כלליים של סוגים מסוימים של מכשירים, כמו אחסון, אודיו, וידאו, רשתות וכו', שאותם יצרני המכשירים יכולים להטמיע. היתרון של המפרטים האלה של סוגי מכשיר הוא שספק של מערכת הפעלה יכול להטמיע מנהל התקן יחיד בהתאם למפרט המחלקה ('מנהל התקן מחלקה') וכל מכשיר שמטמיע את המחלקה הזו ייתמך. זה היה שיפור גדול לעומת כל יצרן שצריך לכתוב את מנהלי ההתקנים שלו.
עם זאת, יש מכשירים שלא מתאימים לאף אחת מהקטגוריות הסטנדרטיות האלה. במקום זאת, היצרן יכול לבחור לתייג את המכשיר שלו כמכשיר שמטמיע את הכיתה הספציפית לספק. במקרה כזה, מערכת ההפעלה בוחרת איזה מנהל התקן של המכשיר לטעון על סמך מידע שמסופק בחבילת מנהלי ההתקנים של הספק. בדרך כלל מדובר בקבוצה של מזהי מוצרים ומזהי ספקים שידועים כהטמעה של פרוטוקול ספציפי לספק.
תכונה נוספת של USB היא שמכשירים יכולים לספק כמה ממשקים למארח שאליו הם מחוברים. כל ממשק יכול להטמיע מחלקה סטנדרטית או להיות ספציפי לספק. כשמערכת הפעלה בוחרת את מנהלי ההתקנים המתאימים לטיפול במכשיר, כל ממשק יכול להיות מוגדר על ידי מנהל התקנים אחר. לדוגמה, מצלמת אינטרנט מסוג USB מספקת בדרך כלל שני ממשקים, אחד שמטמיע את USB Video Class (למצלמה) ואחד שמטמיע את USB Audio Class (למיקרופון). מערכת ההפעלה לא טוענת "מנהל התקן" אחד של מצלמת אינטרנט, אלא טוענת מנהלי התקנים עצמאיים של וידאו ואודיו, שאחראים על הפונקציות הנפרדות של המכשיר. ההרכב הזה של כיתות ממשק מספק גמישות רבה יותר.
העקרונות הבסיסיים של 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 | ההספק המרבי מופיע במרווחים של 2mA |
| תיאור ממשק | ||
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 משויך ונקודת קצה יחידה שמשמשת להעברת אירועי קלט למערכת ההפעלה. הממשק השני הוא ממשק ספציפי לספק עם שני נקודות קצה שאפשר להשתמש בהן כדי לשלוח פקודות למכשיר ולקבל תשובות בתמורה.
מתארי WebUSB
WebUSB יכול לפעול עם מכשירים רבים ללא שינויים בקושחת הקצרה, אבל כדי להפעיל פונקציונליות נוספת צריך לסמן את המכשיר באמצעות מתארים ספציפיים שמציינים תמיכה ב-WebUSB. לדוגמה, אפשר לציין כתובת URL של דף נחיתה שהדפדפן יוכל להפנות אליה את המשתמש כשהמכשיר מחובר.
Binary device Object Store (BOS) הוא רעיון שהוצג ב-USB 3.0, אבל הוא הועבר גם למכשירי USB 2.0 כחלק מגרסה 2.1. כדי להצהיר על תמיכה ב-WebUSB, צריך לכלול את מתאר יכולות הפלטפורמה הבא בתיאור ה-BOS:
| ערך | שדה | תיאור |
|---|---|---|
| תיאור של מכשיר בינארי ב-Object Store | ||
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 בפורמט little-endian |
0x0100 |
bcdVersion | תיאור WebUSB בגרסה 1.0 |
0x01 |
bVendorCode | ערך bRequest ל-WebUSB |
0x01 |
iLandingPage | כתובת ה-URL של דף הנחיתה |
מזהה ה-UUID של יכולות הפלטפורמה מזהה את הקוד הזה בתור תיאור של יכולות הפלטפורמה של WebUSB, שמספק מידע בסיסי על המכשיר. כדי שהדפדפן יוכל לאחזר מידע נוסף על המכשיר, הוא משתמש בערך bVendorCode כדי לשלוח בקשות נוספות למכשיר. הבקשה היחידה שצוינה כרגע היא GET_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. דימון מערכת שנקרא 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, וגם היא לא דורשת שינוי כלשהו בהגדרות המערכת. השירות permission_broker שולט בגישה למכשירי USB, והוא יאפשר לדפדפן לגשת אליהם כל עוד יש לפחות ממשק אחד שלא נרשם.
Windows
מודל מנהלי ההתקנים של Windows כולל דרישה נוספת. בניגוד לפלטפורמות שלמעלה, היכולת לפתוח מכשיר USB מאפליקציית משתמש היא לא ברירת המחדל, גם אם לא נטען נהג. במקום זאת, יש צורך במנהל התקן מיוחד, WinUSB, כדי לספק את הממשק שאפליקציות משתמשות בו כדי לגשת למכשיר. אפשר לעשות זאת באמצעות קובץ מידע מותאם אישית של הנהג (INF) שמותקן במערכת, או על ידי שינוי הקושחה של המכשיר כדי לספק את תיאורי התאימות של מערכת ההפעלה של Microsoft במהלך המיפוי.
קובץ מידע על מנהל (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] מגדירים את הקבוצה של DeviceInterfaceGUIDs למכשיר. לכל ממשק של מכשיר חייב להיות GUID כדי שאפליקציה תוכל למצוא אותו ולהתחבר אליו באמצעות Windows API. אפשר להשתמש ב-cmdlet של PowerShell New-Guid או בכלי אונליין כדי ליצור מזהה 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 בפורמט little-endian |
0x06030000 |
dwWindowsVersion | הגרסה המינימלית של Windows שתומכת ב-Skype (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 יכולות להיות כמה פונקציות, ולכן החלק הראשון של קבוצת המתאר מתאר לאיזו פונקציה משויכים המאפיינים הבאים. בדוגמה הבאה מגדירים את ממשק 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: