בנה מכשיר כדי לנצל את מלוא היתרונות של WebUSB API.
במאמר הזה נסביר איך לבנות מכשיר כדי להפיק את המקסימום מ-WebUSB API. להצגת מבוא קצר על ה-API עצמו, ראו גישה להתקני USB באינטרנט.
רקע
האפיק הטורי האוניברסלי (USB) הפך לממשק הפיזי הנפוץ ביותר לחיבור ציוד היקפי למחשב ולמכשירים ניידים. בנוסף להגדרת המאפיינים החשמליים של האוטובוס ומודל כללי לתקשורת עם מכשיר, מפרטי ה-USB כוללים מפרטים של סיווג מכשיר. אלו מודלים כלליים לסוגים מסוימים של מכשירים, כמו אחסון, אודיו, וידאו, רשתות וכו', שיצרני מכשירים יכולים להטמיע. היתרון של מפרטים אלה של סיווג מכשיר הוא שספק של מערכת הפעלה יכול להטמיע מנהל התקן יחיד על סמך מפרט המחלקה ("מנהל התקן של מחלקה") ולכל מכשיר שמטמיע את המחלקה הזו. זה היה שיפור משמעותי לעומת כל יצרן שהיה צריך לכתוב מנהלי התקן משלו.
עם זאת, חלק מהמכשירים לא מתאימים לאחת מסיווגי המכשירים הסטנדרטיים האלה. במקום זאת, היצרן יכול לבחור לתייג את המכשיר שלו ככזה שמטמיע את המחלקה הספציפית לספק. במקרה כזה, מערכת ההפעלה בוחרת את מנהל ההתקן של המכשיר לטעינה על סמך מידע שמסופק בחבילת מנהלי ההתקנים של הספק, בדרך כלל קבוצה של מזהי ספק ומזהי מוצר שידועים כיישום של פרוטוקול ספציפי לספק.
תכונה נוספת של ה-USB היא שהמכשירים עשויים לספק מספר ממשקים למארח שאליו הם מחוברים. בכל ממשק אפשר להטמיע מחלקה סטנדרטית או מחלקה ספציפית לספק. כשמערכת הפעלה בוחרת את מנהלי ההתקנים המתאימים לטיפול במכשיר, מנהל התקן אחר יכול לתבוע בעלות על כל ממשק. לדוגמה, למצלמת USB יש בדרך כלל שני ממשקים, אחד שמטמיע את סיווג הווידאו ב-USB (למצלמה) והשני מטמיע את סיווג האודיו ב-USB (למיקרופון). מערכת ההפעלה לא טוענת "מנהל התקן של מצלמת אינטרנט" אחד, אלא טוענת מנהלי התקנים עצמאיים של וידאו ואודיו, אשר לוקחים אחריות על הפונקציות הנפרדות של המכשיר. ההרכב הזה של מחלקות הממשק מספק גמישות רבה יותר.
יסודות ה-API
לרבים מסיווגי ה-USB הרגילים יש ממשקי API תואמים באינטרנט. לדוגמה,
דף יכול לצלם וידאו ממכשיר של כיתת וידאו באמצעות getUserMedia()
או לקבל אירועי קלט ממכשיר כיתתי עם ממשק אנושי (HID), על ידי האזנה
ל-KeyboardEvents או ל-PointerEvents, או באמצעות Gamepad או
WebHID API.
בדיוק כמו שלא כל המכשירים מטמיעים הגדרת מחלקה סטנדרטית, לא כל המכשירים מטמיעים תכונות שמתאימות לממשקי ה-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 | נקודת קצה (endpoint) אחת |
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 | האורך הכולל של מתאר הדוח |
| תיאור של נקודת קצה (endpoint) | ||
0x07 |
bLength | גודל מתאר זה |
0x05 |
bDescriptorType | תיאור של נקודת קצה (endpoint) |
0b10000001 |
bEndpointAddress | נקודת קצה 1 (הודו) |
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 | שם הממשק (ללא) |
| תיאור של נקודת קצה (endpoint) | ||
0x07 |
bLength | גודל מתאר זה |
0x05 |
bDescriptorType | תיאור של נקודת קצה (endpoint) |
0b10000010 |
bEndpointAddress | נקודת קצה 1 (הודו) |
0b00000010 |
bmAttributes | בכמות גדולה |
0x0040 |
wMaxPacketSize | חבילות של 64 בייטים |
0x00 |
bInterval | לא רלוונטי לנקודות קצה בכמות גדולה |
| תיאור של נקודת קצה (endpoint) | ||
0x07 |
bLength | גודל מתאר זה |
0x05 |
bDescriptorType | תיאור של נקודת קצה (endpoint) |
0b00000011 |
bEndpointAddress | נקודת קצה 3 (יוצאת) |
0b00000010 |
bmAttributes | בכמות גדולה |
0x0040 |
wMaxPacketSize | חבילות של 64 בייטים |
0x00 |
bInterval | לא רלוונטי לנקודות קצה בכמות גדולה |
מתאר ההגדרות האישיות מורכב מכמה מתארים שמחוברים יחד. כל אחד מהם מתחיל בשדות bLength ו-bDescriptorType כדי שאפשר יהיה לזהות אותם. הממשק הראשון הוא ממשק ממשק אנושי (HID) עם מתאר משויך של ממשק אנושי (HID) ונקודת קצה אחת, שמשמשות להעברת אירועי קלט למערכת ההפעלה. הממשק השני הוא ממשק ספציפי לספק עם שתי נקודות קצה (endpoints), שאפשר להשתמש בהן כדי לשלוח פקודות למכשיר ולקבל תגובות בתמורה.
מתארי WebUSB
אמנם WebUSB יכול לפעול עם הרבה מכשירים ללא שינויי קושחה, אבל אפשר להפעיל פונקציונליות נוספת על ידי סימון המכשיר באמצעות תיאורים ספציפיים המציינים תמיכה ב-WebUSB. לדוגמה, אפשר לציין כתובת של דף נחיתה שאליו הדפדפן יוכל להפנות את המשתמש כשהמכשיר מחובר.
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 Platform, שמספק מידע בסיסי על המכשיר. כדי שהדפדפן יאחזר מידע נוסף על המכשיר, הוא משתמש בערך 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 Platform Capability שבהן השדה 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 ולא נדרשת שום שינוי בהגדרות המערכת. השירות permissions_broker שולט בגישה להתקני USB ויאפשר לדפדפן לגשת אליהם כל עוד יש לפחות ממשק אחד שלא נתבעה עליו בעלות.
Windows
דגם מנהל ההתקן של Windows כולל דרישה נוספת. להבדיל מהפלטפורמות שמעל האפשרות לפתוח התקן USB מאפליקציית משתמש היא לא ברירת המחדל, גם אם לא נטען מנהל התקן. במקום זאת יש מנהל התקן מיוחד, WinUSB, שצריך לטעון אותו כדי לספק את הממשק שבו אפליקציות משתמשות כדי לגשת למכשיר. ניתן לעשות זאת באמצעות קובץ מידע מותאם אישית של מנהל התקן (INF) שמותקן במערכת, או על ידי שינוי קושחת המכשיר כך שתספק את מתארי התאימות של Microsoft OS במהלך הספירה.
קובץ פרטי נהג (INF)
קובץ מידע של מנהל התקן מורה ל-Windows מה לעשות אם נתקלים במכשיר בפעם הראשונה. מכיוון שהמערכת של המשתמש כבר כוללת את מנהל התקן WinUSB, כל מה שצריך הוא שקובץ ה-INF ישייך את הספק ומזהה המוצר שלכם לכלל ההתקנה החדש הזה. הקובץ הבא הוא דוגמה בסיסית. שומרים אותה בקובץ עם התוסף .inf, משנים את הקטעים שמסומנים ב-X ולאחר מכן לוחצים עליהם לחיצה ימנית ובוחרים ב-Install (התקנה) מתפריט ההקשר.
[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 כדי שאפליקציה תוכל למצוא ולהתחבר אליו דרך Windows API. משתמשים ב-cmdlet New-Guid של PowerShell או בכלי אונליין כדי ליצור GUID אקראי.
למטרות פיתוח, הכלי של Zaadig מספק ממשק קל להחלפת מנהל ההתקן שנטען בממשק USB במנהל התקן WinUSB.
תיאורי תאימות של Microsoft OS
הגישה של קובצי INF כפי שצוינה למעלה היא מסורבלת, כי היא דורשת להגדיר את כל המכונות של כל משתמש מראש. Windows 8.1 ואילך מציע חלופה באמצעות שימוש במתארי USB בהתאמה אישית. התיאורים האלה מספקים מידע למערכת ההפעלה של Windows בפעם הראשונה שהמכשיר מחובר לחשמל, שבדרך כלל נכלל בקובץ ה-INF.
אחרי שמגדירים מתארי WebUSB, אפשר להוסיף בקלות גם את מתארי התאימות של Microsoft OS. קודם כול מרחיבים את מתאר ה-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 יכולות להיות כמה פונקציות, ולכן החלק הראשון של קבוצת התיאורים מתאר את הפונקציה שאליה משויכים המאפיינים הבאים. בדוגמה הבאה מוגדרת ממשק 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 ועוד שני טרמינטורים ריקים בקידוד UTF-16LE |
מערכת Windows תשלח שאילתה למכשיר רק פעם אחת. אם המכשיר לא יגיב באמצעות תיאורים חוקיים, הוא לא יבקש שוב אישור בפעם הבאה שהוא יחובר. Microsoft סיפקה רשימה של ערכי רישום של מכשירי USB שמתארות את ערכי הרישום שנוצרו במהלך ספירת מכשיר. במהלך הבדיקה, מוחקים את הרשומות שנוצרו במכשיר כדי לאלץ את Windows לנסות לקרוא שוב את התיאורים.
למידע נוסף על השימוש במתארים האלה, תוכלו לקרוא את הפוסט בבלוג של Microsoft.
דוגמאות
בפרויקטים הבאים ניתן למצוא קוד לדוגמה ליישום של מכשירים המותאמים ל-WebUSB, שכוללים גם תיאורים של WebUSB וגם תיאורים של Microsoft OS: