يمكنك بناء جهاز لتحقيق الاستفادة الكاملة من WebUSB API.
توضّح هذه المقالة كيفية إنشاء جهاز لتحقيق الاستفادة الكاملة من WebUSB API. للحصول على مقدمة موجزة عن واجهة برمجة التطبيقات نفسها، يمكنك الاطّلاع على الوصول إلى أجهزة USB على الويب.
الخلفية
أصبح الناقل التسلسلي العالمي (USB) هو الواجهة المادية الأكثر شيوعًا لتوصيل الأجهزة الملحقة بأجهزة الكمبيوتر المكتبية والأجهزة الجوّالة. بالإضافة إلى تحديد الخصائص الكهربائية للحافلة ونموذج عام للاتصال بأي جهاز، تتضمن مواصفات USB مجموعة من مواصفات فئة الجهاز. هذه طُرز عامة لفئات معيّنة من الأجهزة، مثل مساحة التخزين والصوت والفيديو والشبكات وما إلى ذلك، والتي يمكن للشركات المصنّعة للأجهزة تنفيذها. تتمثل ميزة مواصفات فئة الأجهزة هذه في أنه يمكن لمورّد نظام التشغيل تنفيذ برنامج تشغيل واحد وفقًا لمواصفات الفئة ("برنامج تشغيل من فئة") وأي جهاز ينفّذ هذه الفئة سيكون متوافقًا. كان هذا تحسنًا كبيرًا مقارنة بكل شركة مصنعة بحاجة إلى كتابة برامج تشغيل الأجهزة الخاصة بها.
على الرغم من ذلك، لا تتوافق بعض الأجهزة مع إحدى فئات الأجهزة الموحدة هذه. وقد تختار الشركة المصنعة بدلاً من ذلك تصنيف أجهزتها على أنها تنفيذ فئة خاصة بالمورّدين. في هذه الحالة، يختار نظام التشغيل برنامج تشغيل الجهاز الذي سيتم تحميله بناءً على المعلومات المقدمة في حزمة برنامج التشغيل لدى البائع، وعادةً ما تكون مجموعة من معرّفات الموردين والمنتج التي تُعرف بتنفيذ بروتوكول خاص بمورّد معين.
ومن الميزات الأخرى لـ USB أن الأجهزة قد توفر واجهات متعددة للمضيف الذي تتصل به. يمكن لكل واجهة تنفيذ إما فئة موحّدة أو خاصة بالمورّدين. عندما يختار نظام تشغيل برامج التشغيل الصحيحة للتعامل مع الجهاز، يمكن المطالبة بكل واجهة بواسطة برنامج تشغيل مختلف. على سبيل المثال، توفّر كاميرا الويب USB عادةً واجهتَين، إحداهما تنفّذ فئة الفيديو USB (للكاميرا) والأخرى تنفّذ فئة الصوت USB (للميكروفون). لا يحمّل نظام التشغيل "برنامج تشغيل كاميرا ويب" واحدًا، بل يحمِّل بدلاً من ذلك برامج تشغيل مستقلة من فئة الفيديو والصوت تتحمّل مسؤولية الوظائف المنفصلة للجهاز. يوفر تكوين فئات الواجهة مزيدًا من المرونة.
أساسيات واجهة برمجة التطبيقات
فالعديد من فئات أجهزة USB العادية تتضمّن واجهات برمجة تطبيقات ويب مقابلة. على سبيل المثال، يمكن لصفحة التقاط فيديو من جهاز فئة فيديو باستخدام getUserMedia()
أو تلقّي أحداث الإدخال من جهاز فئة واجهة بشرية (HID) من خلال الاستماع
إلى KeyboardEvents أو PointerEvents أو باستخدام Gamepad أو
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 | الإصدار 1.1 من HID |
0x00 |
bCountryCode | البلد المستهدَف للأجهزة |
0x01 |
bNumDescriptors | عدد واصفات فئة HID المطلوب اتباعها |
0x22 |
bDescriptorType | نوع وصف التقرير |
0x003F |
wDescriptorLength | إجمالي طول واصف التقرير |
واصف نقطة النهاية | ||
0x07 |
bLength | حجم أداة الوصف هذه |
0x05 |
bDescriptorType | واصف نقطة النهاية |
0b10000001 |
bEndpointAddress | نقطة النهاية 1 (الهند) |
0b00000011 |
bmAttributes | المقاطعة |
0x0008 |
wMaxPacketSize | حزم 8 بايت |
0x0A |
bInterval | فاصل زمني 10 ملي ثانية |
واصف الواجهة | ||
0x09 |
bLength | حجم أداة الوصف هذه |
0x04 |
bDescriptorType | واصف الواجهة |
0x01 |
bInterfaceNumber | الواجهة 1 |
0x00 |
bAlternateSetting | الإعداد البديل 0 (تلقائي) |
0x02 |
bNumEndpoints | نقطتا نهاية |
0xFF |
bInterfaceClass | فئة الواجهة الخاصة بالمورّد |
0x00 |
bInterfaceSubClass | |
0x00 |
bInterfaceProtocol | |
0x00 |
iInterface | اسم الواجهة (بدون) |
واصف نقطة النهاية | ||
0x07 |
bLength | حجم أداة الوصف هذه |
0x05 |
bDescriptorType | واصف نقطة النهاية |
0b10000010 |
bEndpointAddress | نقطة النهاية 1 (الهند) |
0b00000010 |
bmAttributes | مجمَّع |
0x0040 |
wMaxPacketSize | حزم 64 بايت |
0x00 |
bInterval | لا ينطبق لنقاط النهاية المجمّعة |
واصف نقطة النهاية | ||
0x07 |
bLength | حجم أداة الوصف هذه |
0x05 |
bDescriptorType | واصف نقطة النهاية |
0b00000011 |
bEndpointAddress | نقطة النهاية 3 (OUT) |
0b00000010 |
bmAttributes | مجمَّع |
0x0040 |
wMaxPacketSize | حزم 64 بايت |
0x00 |
bInterval | لا ينطبق لنقاط النهاية المجمّعة |
يتألف واصف الإعداد من عدة أدوات وصف متّصلة معًا. ويبدأ كل منها بالحقلَين bLength
وbDescriptorType
حتى يمكن التعرّف عليهما. الواجهة الأولى هي واجهة HID مع واصف HID مرتبط بها ونقطة نهاية واحدة تُستخدم لتسليم أحداث الإدخال إلى نظام التشغيل. الواجهة الثانية هي واجهة خاصة بالمورّد تحتوي على نقطتي نهاية يمكن استخدامهما لإرسال الأوامر إلى الجهاز وتلقي الردود في المقابل.
أدوات وصف WebUSB
على الرغم من أنّ WebUSB يمكن أن يعمل مع العديد من الأجهزة بدون إجراء تعديلات على البرامج الثابتة، يتم تفعيل وظائف إضافية من خلال وضع علامة على الجهاز بوصفات معيّنة تشير إلى التوافق مع WebUSB. على سبيل المثال، يمكنك تحديد عنوان URL للصفحة المقصودة يمكن للمتصفح توجيه المستخدم إليه عندما يكون الجهاز موصولاً بمصدر طاقة.
متجر كائنات الجهاز الثنائي (BOS) هو مفهوم تم طرحه في USB 3.0 ولكن تمت إعادة توفيره أيضًا إلى أجهزة USB 2.0 كجزء من الإصدار 2.1. يبدأ توضيح إتاحة WebUSB بتضمين واصف إمكانيات النظام الأساسي التالي في واصف BOS:
القيمة | الحقل | الوصف |
---|---|---|
واصف Object Store للجهاز الثنائي | ||
0x05 |
bLength | حجم أداة الوصف هذه |
0x0F |
bDescriptorType | واصف Object Store للجهاز الثنائي |
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 | واصف إمكانية النظام الأساسي لـ WebUSB بتنسيق GUID بتنسيق صغير الأطراف |
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 يتضمّن الحقل 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 الاتصال بالجهاز والمطالبة بأي واجهات لم يطلبها برنامج تشغيل kernel أو تطبيق آخر.
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 إلى التسلسلي، نظرًا لعدم وجود واجهة برمجة تطبيقات في حزمة تطوير البرامج (SDK) لنظام التشغيل Android للاتصال بجهاز تسلسلي.
ChromeOS
يستند نظام التشغيل ChromeOS إلى نظام التشغيل Linux أيضًا ولا يتطلب أي تعديل على إعداد النظام. تتحكّم خدمة License_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. استخدِم أمر New-Guid
PowerShell
أو أداة على الإنترنت لإنشاء معرّف GUID عشوائي.
لأغراض التطوير، توفر أداة Zadig واجهة سهلة لاستبدال برنامج التشغيل الذي تم تحميله لواجهة USB ببرنامج التشغيل WinUSB.
أدوات وصف التوافق مع نظام التشغيل Microsoft
يعتبر نهج ملف 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 | واصف التوافق مع النظام الأساسي لـ Microsoft OS 2.0 GUID بتنسيق صغير النهاية |
0x06030000 |
dwWindowsVersion | الحد الأدنى من إصدار Windows المتوافق (Windows 8.1) |
0x00B2 |
wMSOSDescriptorSetTotalLength | إجمالي طول مجموعة الواصف |
0x02 |
bMS_VendorCode | قيمة طلب استرداد المزيد من واصف 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 | اسم الموقع يتضمّن فاصلاً فارغًا مرمّزًا بترميز UTF-16LE |
0x0050 |
wPropertyDataLength | طول قيمة الخاصية |
"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}\0\0" |
PropertyData | معرّف GUID بالإضافة إلى فاصلَين فارغَين تم ترميزهما بترميز UTF-16LE |
سيقوم نظام Windows بالاستعلام عن الجهاز عن هذه المعلومات مرة واحدة فقط. وإذا لم يستجب الجهاز بأوصاف صالحة، فلن يطلب مرة أخرى في المرة التالية التي يتم فيها توصيل الجهاز. قدّمت Microsoft قائمة بإدخالات سجلّ جهاز USB التي تصف إدخالات قاعدة بيانات المسجّلين التي تم إنشاؤها عند تعداد جهاز. عند الاختبار، احذف الإدخالات التي تم إنشاؤها لأحد الأجهزة لإجبار نظام التشغيل Windows على محاولة قراءة الواصفات مرة أخرى.
لمزيد من المعلومات، اطّلِع على مشاركة المدونة من Microsoft حول كيفية استخدام أدوات الوصف هذه.
أمثلة
يمكن العثور في هذه المشاريع على مثال على رمز يتم فيه تنفيذ الأجهزة المستندة إلى WebUSB التي تتضمّن أدوات وصف WebUSB وأدوات وصف نظام التشغيل Microsoft: