Bouw een apparaat om optimaal te profiteren van de WebUSB API.
In dit artikel wordt uitgelegd hoe u een apparaat kunt bouwen waarmee u optimaal kunt profiteren van de WebUSB API . Voor een korte inleiding tot de API zelf, zie Toegang tot USB-apparaten op internet .
Achtergrond
De Universal Serial Bus (USB) is de meest gebruikelijke fysieke interface geworden voor het aansluiten van randapparatuur op desktop- en mobiele computerapparatuur. Naast het definiëren van de elektrische kenmerken van de bus en een algemeen model voor communicatie met een apparaat, omvatten USB-specificaties een reeks apparaatklassespecificaties. Dit zijn algemene modellen voor bepaalde klassen apparaten, zoals opslag, audio, video, netwerken, enz., die apparaatfabrikanten kunnen implementeren. Het voordeel van deze apparaatklassespecificaties is dat een leverancier van een besturingssysteem één enkel stuurprogramma kan implementeren op basis van de klassespecificatie (een "klassestuurprogramma") en dat elk apparaat dat die klasse implementeert, zal worden ondersteund. Dit was een grote verbetering ten opzichte van elke fabrikant die zijn eigen stuurprogramma's moest schrijven.
Sommige apparaten passen echter niet in een van deze gestandaardiseerde apparaatklassen. Een fabrikant kan er in plaats daarvan voor kiezen om zijn apparaat te labelen als implementatie van de leverancierspecifieke klasse. In dit geval kiest het besturingssysteem welk apparaatstuurprogramma moet worden geladen op basis van de informatie in het stuurprogrammapakket van de leverancier, doorgaans een reeks leverancier- en product-ID's waarvan bekend is dat ze een bepaald leverancierspecifiek protocol implementeren.
Een ander kenmerk van USB is dat apparaten meerdere interfaces kunnen bieden aan de host waarmee ze zijn verbonden. Elke interface kan een gestandaardiseerde klasse implementeren of leverancierspecifiek zijn. Wanneer een besturingssysteem de juiste stuurprogramma's kiest om het apparaat te bedienen, kan elke interface door een ander stuurprogramma worden geclaimd. Een USB-webcam biedt bijvoorbeeld doorgaans twee interfaces: één die de USB-videoklasse implementeert (voor de camera) en één die de USB-audioklasse implementeert (voor de microfoon). Het besturingssysteem laadt geen enkel "webcamstuurprogramma", maar laadt in plaats daarvan onafhankelijke video- en audioklassestuurprogramma's die de verantwoordelijkheid op zich nemen voor de afzonderlijke functies van het apparaat. Deze samenstelling van interfaceklassen zorgt voor een grotere flexibiliteit.
API-basisprincipes
Veel van de standaard USB-klassen hebben overeenkomstige web-API's. Een pagina kan bijvoorbeeld video vastleggen van een videoklasse-apparaat met behulp van getUserMedia() of invoergebeurtenissen ontvangen van een Human Interface (HID)-klasse-apparaat door te luisteren naar KeyboardEvents of PointerEvents , of door de Gamepad of de WebHID API te gebruiken. Net zoals niet alle apparaten een gestandaardiseerde klassendefinitie implementeren, implementeren niet alle apparaten functies die overeenkomen met bestaande webplatform-API's. Wanneer dit het geval is, kan de WebUSB API deze leemte opvullen door sites een manier te bieden om een leverancierspecifieke interface te claimen en daarvoor ondersteuning rechtstreeks vanuit hun pagina te implementeren.
De specifieke vereisten voor een apparaat om toegankelijk te zijn via WebUSB variëren enigszins van platform tot platform vanwege verschillen in de manier waarop besturingssystemen USB-apparaten beheren, maar de basisvereiste is dat een apparaat niet al een stuurprogramma mag hebben dat de interface claimt die de pagina wil beheren. Dit kan een generiek klassestuurprogramma zijn dat wordt geleverd door de leverancier van het besturingssysteem, of een apparaatstuurprogramma dat wordt geleverd door de leverancier. Omdat USB-apparaten meerdere interfaces kunnen bieden, die elk hun eigen stuurprogramma kunnen hebben, is het mogelijk een apparaat te bouwen waarvoor sommige interfaces door een stuurprogramma worden geclaimd en andere toegankelijk blijven voor de browser.
Een high-end USB-toetsenbord kan bijvoorbeeld een interface van HID-klasse bieden die wordt geclaimd door het invoersubsysteem van het besturingssysteem en een leverancierspecifieke interface die beschikbaar blijft voor WebUSB voor gebruik door een configuratietool. Deze tool kan op de website van de fabrikant worden aangeboden, zodat de gebruiker aspecten van het gedrag van het apparaat, zoals macrotoetsen en lichteffecten, kan wijzigen zonder platformspecifieke software te installeren. De configuratiedescriptor van zo'n apparaat zou er ongeveer zo uitzien:
| Waarde | Veld | Beschrijving |
|---|---|---|
| Configuratiebeschrijving | ||
0x09 | bLengte | Grootte van deze descriptor |
0x02 | bDescriptorType | Configuratiebeschrijving |
0x0039 | wTotale lengte | Totale lengte van deze reeks descriptoren |
0x02 | bNumInterfaces | Aantal interfaces |
0x01 | bConfiguratiewaarde | Configuratie 1 |
0x00 | iConfiguratie | Configuratienaam (geen) |
0b1010000 | bmAttributen | Zelfaangedreven apparaat met wekfunctie op afstand |
0x32 | bMaxVermogen | Het maximale vermogen wordt uitgedrukt in stappen van 2 mA |
| Interface-descriptor | ||
0x09 | bLengte | Grootte van deze descriptor |
0x04 | bDescriptorType | Interface-descriptor |
0x00 | bInterfacenummer | Interface 0 |
0x00 | bAlternatieve instelling | Alternatieve instelling 0 (standaard) |
0x01 | bNumEndpunten | 1 eindpunt |
0x03 | bInterfaceKlasse | HID-interfaceklasse |
0x01 | bInterfaceSubKlasse | Subklasse van de opstartinterface |
0x01 | bInterfaceProtocol | Toetsenbord |
0x00 | iInterface | Interfacenaam (geen) |
| HID-descriptor | ||
0x09 | bLengte | Grootte van deze descriptor |
0x21 | bDescriptorType | HID-descriptor |
0x0101 | bcdHID | HID-versie 1.1 |
0x00 | bLandcode | Doelland voor hardware |
0x01 | bNumDescriptors | Aantal te volgen HID-klassebeschrijvingen |
0x22 | bDescriptorType | Type rapportdescriptor |
0x003F | wDescriptorLengte | Totale lengte van de rapportdescriptor |
| Eindpuntdescriptor | ||
0x07 | bLengte | Grootte van deze descriptor |
0x05 | bDescriptorType | Eindpuntdescriptor |
0b10000001 | bEindpuntadres | Eindpunt 1 (IN) |
0b00000011 | bmAttributen | Onderbreken |
0x0008 | wMaxPakketgrootte | Pakketten van 8 bytes |
0x0A | bInterval | 10 ms interval |
| Interface-descriptor | ||
0x09 | bLengte | Grootte van deze descriptor |
0x04 | bDescriptorType | Interface-descriptor |
0x01 | bInterfacenummer | Interface 1 |
0x00 | bAlternatieve instelling | Alternatieve instelling 0 (standaard) |
0x02 | bNumEndpunten | 2 eindpunten |
0xFF | bInterfaceKlasse | Leverancierspecifieke interfaceklasse |
0x00 | bInterfaceSubKlasse | |
0x00 | bInterfaceProtocol | |
0x00 | iInterface | Interfacenaam (geen) |
| Eindpuntdescriptor | ||
0x07 | bLengte | Grootte van deze descriptor |
0x05 | bDescriptorType | Eindpuntdescriptor |
0b10000010 | bEindpuntadres | Eindpunt 1 (IN) |
0b00000010 | bmAttributen | Bulk |
0x0040 | wMaxPakketgrootte | Pakketten van 64 bytes |
0x00 | bInterval | N.v.t. voor bulkeindpunten |
| Eindpuntdescriptor | ||
0x07 | bLengte | Grootte van deze descriptor |
0x05 | bDescriptorType | Eindpuntdescriptor |
0b00000011 | bEindpuntadres | Eindpunt 3 (UIT) |
0b00000010 | bmAttributen | Bulk |
0x0040 | wMaxPakketgrootte | Pakketten van 64 bytes |
0x00 | bInterval | N.v.t. voor bulkeindpunten |
De configuratiedescriptor bestaat uit meerdere aaneengeschakelde descriptors. Elk begint met de velden bLength en bDescriptorType , zodat ze kunnen worden geïdentificeerd. De eerste interface is een HID-interface met een bijbehorende HID-descriptor en een enkel eindpunt dat wordt gebruikt om invoergebeurtenissen aan het besturingssysteem te leveren. De tweede interface is een leverancierspecifieke interface met twee eindpunten die kunnen worden gebruikt om opdrachten naar het apparaat te verzenden en in ruil daarvoor antwoorden te ontvangen.
WebUSB-descriptors
Hoewel WebUSB met veel apparaten kan werken zonder firmwareaanpassingen, wordt extra functionaliteit mogelijk gemaakt door het apparaat te markeren met specifieke descriptors die ondersteuning voor WebUSB aangeven. U kunt bijvoorbeeld een URL voor de bestemmingspagina opgeven waar de browser de gebruiker naartoe kan leiden wanneer uw apparaat is aangesloten.
De Binary Device Object Store (BOS) is een concept dat is geïntroduceerd in USB 3.0, maar dat ook is teruggeport naar USB 2.0-apparaten als onderdeel van versie 2.1. Het declareren van ondersteuning voor WebUSB begint met het opnemen van de volgende Platform Capability Descriptor in de BOS-descriptor:
| Waarde | Veld | Beschrijving |
|---|---|---|
| Binair apparaat Object Store-descriptor | ||
0x05 | bLengte | Grootte van deze descriptor |
0x0F | bDescriptorType | Binair apparaat Object Store-descriptor |
0x001D | wTotale lengte | Totale lengte van deze reeks descriptoren |
0x01 | bNumDeviceCaps | Aantal apparaatcapaciteitsdescriptors in de BOS |
| Beschrijving van de mogelijkheden van het WebUSB-platform | ||
0x18 | bLengte | Grootte van deze descriptor |
0x10 | bDescriptorType | Beschrijving van apparaatmogelijkheden |
0x05 | bDevCapabilityType | Beschrijving van platformmogelijkheden |
0x00 | bGereserveerd | |
{0x38, 0xB6, 0x08, 0x34, 0xA9, 0x09, 0xA0, 0x47, 0x8B, 0xFD, 0xA0, 0x76, 0x88, 0x15, 0xB6, 0x65} | PlatformcapaciteitUUID | WebUSB-platformcapaciteitsdescriptor GUID in little-endian-indeling |
0x0100 | bcdVersie | WebUSB-descriptor versie 1.0 |
0x01 | bVerkopercode | bVraagwaarde voor WebUSB |
0x01 | iLandingPagina | URL voor landingspagina |
De platformcapaciteit UUID identificeert dit als een WebUSB Platform Capability descriptor , die basisinformatie over het apparaat biedt. Om ervoor te zorgen dat de browser meer informatie over het apparaat ophaalt, gebruikt hij de bVendorCode waarde om aanvullende verzoeken aan het apparaat te verzenden. Het enige verzoek dat momenteel is opgegeven, is GET_URL , dat een URL-descriptor retourneert. Deze zijn vergelijkbaar met tekenreeksdescriptors, maar zijn ontworpen om URL's in zo min mogelijk bytes te coderen. Een URL-descriptor voor "https://google.com" zou er als volgt uitzien:
| Waarde | Veld | Beschrijving |
|---|---|---|
| URL-beschrijving | ||
0x0D | bLengte | Grootte van deze descriptor |
0x03 | bDescriptorType | URL-beschrijving |
0x01 | bSchema | https:// |
"google.com" | URL | UTF-8-gecodeerde URL-inhoud |
Wanneer uw apparaat voor het eerst wordt aangesloten, leest de browser de BOS-descriptor door deze standaard GET_DESCRIPTOR besturingsoverdracht uit te voeren:
| bmRequestType | bVerzoek | wWaarde | index | wLengte | Gegevens (antwoord) |
|---|---|---|---|---|---|
0b10000000 | 0x06 | 0x0F00 | 0x0000 | * | De BOS-descriptor |
Dit verzoek wordt meestal twee keer gedaan, de eerste keer met een voldoende grote wLength zodat de host de waarde van het wTotalLength veld kan achterhalen zonder een grote overdracht uit te voeren, en vervolgens opnieuw wanneer de volledige descriptorlengte bekend is.
Als bij de WebUSB Platform Capability-descriptor het iLandingPage veld is ingesteld op een waarde die niet nul is, voert de browser vervolgens een WebUSB-specifiek GET_URL verzoek uit door een controleoverdracht uit te voeren waarbij de bRequest is ingesteld op de bVendorCode waarde van de platformcapaciteitsdescriptor en wValue is ingesteld op de iLandingPage waarde. De aanvraagcode voor GET_URL ( 0x02 ) gaat in wIndex :
| bmRequestType | bVerzoek | wWaarde | index | wLengte | Gegevens (antwoord) |
|---|---|---|---|---|---|
0b11000000 | 0x01 | 0x0001 | 0x0002 | * | De URL-descriptor |
Opnieuw kan dit verzoek twee keer worden gedaan om eerst de lengte van de te lezen descriptor te onderzoeken.
Platformspecifieke overwegingen
Hoewel de WebUSB API probeert een consistente interface te bieden voor toegang tot USB-apparaten, moeten ontwikkelaars zich nog steeds bewust zijn van de vereisten die aan applicaties worden gesteld, zoals de vereisten van een webbrowser om toegang te krijgen tot apparaten.
macOS
Er is niets speciaals nodig voor macOS. Een website die WebUSB gebruikt, kan verbinding maken met het apparaat en alle interfaces claimen die niet worden geclaimd door een kernelstuurprogramma of een andere applicatie.
Linux
Linux lijkt op macOS, maar standaard stellen de meeste distributies geen gebruikersaccounts in met toestemming om USB-apparaten te openen. Een systeemdaemon genaamd udev is verantwoordelijk voor het toewijzen van de gebruiker en groep die toegang heeft tot een apparaat. Een regel als deze wijst het eigendom van een apparaat dat overeenkomt met de opgegeven leverancier- en product-ID's toe aan de plugdev groep, een gemeenschappelijke groep voor gebruikers met toegang tot randapparatuur:
SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="XXXX", GROUP="plugdev"
Vervang XXXX door de hexadecimale leveranciers- en product-ID's voor uw apparaat. ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" komt bijvoorbeeld overeen met een Nexus One-telefoon. Deze moeten worden geschreven zonder het gebruikelijke voorvoegsel "0x" en zonder kleine letters om correct te worden herkend. Om de ID's voor uw apparaat te vinden, voert u het opdrachtregelprogramma lsusb uit.
Deze regel moet in een bestand in de map /etc/udev/rules.d worden geplaatst en wordt van kracht zodra het apparaat wordt aangesloten. Het is niet nodig om udev opnieuw te starten.
Android
Het Android-platform is gebaseerd op Linux, maar vereist geen wijziging in de systeemconfiguratie. Standaard is elk apparaat waarvoor geen stuurprogramma in het besturingssysteem is ingebouwd, beschikbaar voor de browser. Ontwikkelaars moeten zich er echter van bewust zijn dat gebruikers een extra stap tegenkomen bij het verbinden met het apparaat. Zodra een gebruiker een apparaat selecteert als reactie op een aanroep van requestDevice() , geeft Android een prompt weer met de vraag of Chrome er toegang toe mag krijgen. Deze prompt verschijnt ook opnieuw als een gebruiker terugkeert naar een website die al toestemming heeft om verbinding te maken met een apparaat en de website open() aanroept.
Bovendien zullen er meer apparaten toegankelijk zijn op Android dan op desktop Linux, omdat er standaard minder stuurprogramma's worden meegeleverd. Een opmerkelijke omissie is bijvoorbeeld de USB CDC-ACM-klasse die gewoonlijk wordt geïmplementeerd door USB-naar-serieel-adapters, aangezien er geen API in de Android SDK is voor communicatie met een serieel apparaat.
ChromeOS
ChromeOS is ook gebaseerd op Linux en vereist ook geen wijziging in de systeemconfiguratie. De permissie_broker-service controleert de toegang tot USB-apparaten en geeft de browser toegang tot deze apparaten, zolang er ten minste één niet-geclaimde interface is.
ramen
Het Windows-stuurprogrammamodel introduceert een extra vereiste. In tegenstelling tot de bovenstaande platforms is de mogelijkheid om een USB-apparaat te openen vanuit een gebruikersapplicatie niet de standaard, zelfs als er geen stuurprogramma is geladen. In plaats daarvan is er een speciaal stuurprogramma, WinUSB, dat moet worden geladen om de interface te bieden die toepassingen gebruiken om toegang te krijgen tot het apparaat. Dit kan worden gedaan met een aangepast stuurprogramma-informatiebestand (INF) dat op het systeem is geïnstalleerd of door de apparaatfirmware aan te passen om tijdens de opsomming de Microsoft OS-compatibiliteitsdescriptors te leveren.
Bestuurdersinformatiebestand (INF)
Een stuurprogramma-informatiebestand vertelt Windows wat het moet doen als het voor de eerste keer een apparaat tegenkomt. Omdat het systeem van de gebruiker al het WinUSB-stuurprogramma bevat, hoeft het INF-bestand alleen uw leverancier en product-ID te koppelen aan deze nieuwe installatieregel. Het onderstaande bestand is een eenvoudig voorbeeld. Sla het op in een bestand met de .inf extensie, wijzig de secties gemarkeerd met "X", klik er vervolgens met de rechtermuisknop op en kies "Installeren" in het contextmenu.
[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"
De sectie [Dev_AddReg] configureert de set DeviceInterfaceGUID's voor het apparaat. Elke apparaatinterface moet een GUID hebben zodat een applicatie deze kan vinden en er verbinding mee kan maken via de Windows API. Gebruik de New-Guid PowerShell-cmdlet of een online hulpprogramma om een willekeurige GUID te genereren.
Voor ontwikkelingsdoeleinden biedt de Zadig-tool een eenvoudige interface voor het vervangen van het geladen stuurprogramma voor een USB-interface door het WinUSB-stuurprogramma.
Compatibiliteitsdescriptors voor Microsoft OS
De bovenstaande INF-bestandsbenadering is omslachtig omdat hiervoor de machine van elke gebruiker vooraf moet worden geconfigureerd. Windows 8.1 en hoger biedt een alternatief door het gebruik van aangepaste USB-descriptors. Deze descriptors bieden informatie aan het Windows-besturingssysteem wanneer het apparaat voor het eerst wordt aangesloten en die normaal gesproken in het INF-bestand zou worden opgenomen.
Zodra u WebUSB-descriptors hebt ingesteld, kunt u eenvoudig ook de OS-compatibiliteitsdescriptors van Microsoft toevoegen. Breid eerst de BOS-descriptor uit met deze aanvullende platformcapaciteitsdescriptor. Zorg ervoor dat wTotalLength en bNumDeviceCaps bijwerkt om er rekening mee te houden.
| Waarde | Veld | Beschrijving |
|---|---|---|
| Beschrijving van de mogelijkheden van het Microsoft OS 2.0-platform | ||
0x1C | bLengte | Grootte van deze descriptor |
0x10 | bDescriptorType | Beschrijving van apparaatmogelijkheden |
0x05 | bDevCapabilityType | Beschrijving van platformmogelijkheden |
0x00 | bGereserveerd | |
{0xDF, 0x60, 0xDD, 0xD8, 0x89, 0x45, 0xC7, 0x4C, 0x9C, 0xD2, 0x65, 0x9D, 0x9E, 0x64, 0x8A, 0x9F} | PlatformcapaciteitUUID | Microsoft OS 2.0-platformcompatibiliteitsdescriptor GUID in Little-Endian-indeling |
0x06030000 | dwWindowsVersie | Minimaal compatibele Windows-versie (Windows 8.1) |
0x00B2 | wMSOSDescriptorSetTotalLength | Totale lengte van de descriptorset |
0x02 | bMS_VendorCode | bRequestwaarde voor het ophalen van verdere Microsoft-descriptors |
0x00 | bAltEnumCode | Apparaat ondersteunt geen alternatieve opsomming |
Net als bij de WebUSB-descriptors moet u een bRequest waarde kiezen die moet worden gebruikt bij controleoverdrachten die verband houden met deze descriptors. In dit voorbeeld heb ik 0x02 gekozen. 0x07 , geplaatst in wIndex , is de opdracht om de Microsoft OS 2.0 Descriptor Set van het apparaat op te halen.
| bmRequestType | bVerzoek | wWaarde | index | wLengte | Gegevens (antwoord) |
|---|---|---|---|---|---|
0b11000000 | 0x02 | 0x0000 | 0x0007 | * | MS OS 2.0-descriptorset |
Een USB-apparaat kan meerdere functies hebben en daarom beschrijft het eerste deel van de descriptorset met welke functie de volgende eigenschappen zijn geassocieerd. In het onderstaande voorbeeld wordt interface 1 van een samengesteld apparaat geconfigureerd. De descriptor geeft het besturingssysteem twee belangrijke stukjes informatie over deze interface. De compatibele ID-descriptor vertelt Windows dat dit apparaat compatibel is met het WinUSB-stuurprogramma. De registereigenschapdescriptor functioneert op dezelfde manier als de sectie [Dev_AddReg] van het INF-voorbeeld hierboven, waarbij een registereigenschap wordt ingesteld om aan deze functie een apparaatinterface-GUID toe te wijzen.
| Waarde | Veld | Beschrijving |
|---|---|---|
| Koptekst van de Microsoft OS 2.0-descriptorset | ||
0x000A | wLengte | Grootte van deze descriptor |
0x0000 | wDescriptorType | Descriptor stelt header-descriptor in |
0x06030000 | dwWindowsVersie | Minimaal compatibele Windows-versie (Windows 8.1) |
0x00B2 | wTotale lengte | Totale lengte van de descriptorset |
| Microsoft OS 2.0-configuratiesubsetheader | ||
0x0008 | wLengte | Grootte van deze descriptor |
0x0001 | wDescriptorType | Configuratie subset header desc. |
0x00 | bConfiguratiewaarde | Geldt voor configuratie 1 (geïndexeerd vanaf 0 ondanks configuraties normaal geïndexeerd vanaf 1) |
0x00 | bGereserveerd | Moet op 0 staan |
0x00A8 | wTotale lengte | Totale lengte van de subset inclusief deze header |
| Functiesubsetheader van Microsoft OS 2.0 | ||
0x0008 | wLengte | Grootte van deze descriptor |
0x0002 | wDescriptorType | Functiesubset header-descriptor |
0x01 | bEersteInterface | Eerste interface van de functie |
0x00 | bGereserveerd | Moet op 0 staan |
0x00A0 | wSubsetlengte | Totale lengte van de subset inclusief deze header |
| Microsoft OS 2.0-compatibele ID-descriptor | ||
0x0014 | wLengte | Grootte van deze descriptor |
0x0003 | wDescriptorType | Compatibele ID-beschrijving |
"WINUSB\0\0" | CompatibelID | ASCII-tekenreeks opgevuld tot 8 bytes |
"\0\0\0\0\0\0\0\0" | Subcompatibele ID | ASCII-tekenreeks opgevuld tot 8 bytes |
| Beschrijving van registereigenschap van Microsoft OS 2.0 | ||
0x0084 | wLengte | Grootte van deze descriptor |
0x0004 | wDescriptorType | Beschrijving van registereigenschap |
0x0007 | wPropertyDataType | REG_MULTI_SZ |
0x002A | wPropertyNameLengte | Lengte van de eigenschapsnaam |
"DeviceInterfaceGUIDs\0" | Eigendomsnaam | Eigenschapsnaam met null-terminator gecodeerd in UTF-16LE |
0x0050 | wPropertyDataLengte | Lengte van de waarde van het onroerend goed |
"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}\0\0" | Eigenschapsgegevens | GUID plus twee null-terminators gecodeerd in UTF-16LE |
Windows zal het apparaat slechts één keer om deze informatie vragen. Als het apparaat niet reageert met geldige omschrijvingen, zal het de volgende keer dat het apparaat wordt aangesloten, niet opnieuw vragen. Microsoft heeft een lijst met USB-apparaatregistervermeldingen verstrekt waarin de registervermeldingen worden beschreven die worden gemaakt bij het opsommen van een apparaat. Verwijder bij het testen de vermeldingen die voor een apparaat zijn gemaakt, zodat Windows de descriptors opnieuw moet proberen te lezen.
Raadpleeg voor meer informatie de blogpost van Microsoft over het gebruik van deze descriptors.
Voorbeelden
Voorbeeldcode die WebUSB-bewuste apparaten implementeert die zowel WebUSB-descriptors als Microsoft OS-descriptors bevatten, is te vinden in deze projecten: