يسمح وضع ملحقات USB للمستخدمين بتوصيل أجهزة مضيف USB المصمّمة خصيصًا للأجهزة التي تعمل بنظام التشغيل Android. يجب أن تلتزم الملحقات ببروتوكول ملحقات Android الموضّح في مستندات مجموعة تطوير ملحقات Android. يتيح ذلك للأجهزة التي تعمل بنظام التشغيل Android والتي لا يمكنها العمل كمضيف USB مواصلة التفاعل مع أجهزة USB. عندما يكون الجهاز الذي يعمل بنظام التشغيل Android في وضع ملحق USB، يعمل ملحق USB المرفق بنظام التشغيل Android كمضيف، ويوفر الطاقة لناقل USB، ويعدد الأجهزة المتصلة. يتيح الإصدار 3.1 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 12) وضع ملحقات USB، كما تم نقل الميزة إلى الإصدار 2.3.4 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 10) لإتاحة استخدام مجموعة أكبر من الأجهزة.
اختيار واجهات برمجة التطبيقات المناسبة لملحقات USB
على الرغم من أنّ واجهات برمجة التطبيقات لملحقات USB تم تقديمها إلى المنصة في الإصدار Android 3.1، إلا أنّها متاحة أيضًا في الإصدار Android 2.3.4 باستخدام مكتبة الإضافات في Google APIs. بما أنّ واجهات برمجة التطبيقات هذه تم نقلها إلى إصدارات سابقة باستخدام مكتبة خارجية، هناك حزمتان يمكنك استيرادهما لإتاحة وضع ملحقات USB. استنادًا إلى الأجهزة التي تريد إتاحة استخدامها والتي تعمل بنظام التشغيل Android، قد تحتاج إلى استخدام إحدى الطريقتين بدلاً من الأخرى:
com.android.future.usb: لإتاحة وضع ملحقات USB في الإصدار 2.3.4 من نظام التشغيل Android، تتضمّن مكتبة الإضافات في Google APIs واجهات برمجة تطبيقات ملحقات USB التي تم نقلها من إصدارات أحدث، وهي مضمّنة في مساحة الاسم هذه. يتيح Android 3.1 أيضًا استيراد الفئات واستدعاءها ضمن مساحة الاسم هذه لإتاحة التطبيقات المكتوبة باستخدام مكتبة الإضافات. هذه المكتبة الإضافية هي برنامج تضمين بسيط لواجهات برمجة تطبيقات ملحقاتandroid.hardware.usbولا تتيح وضع مضيف USB.إذا أردت إتاحة أكبر مجموعة من الأجهزة التي تتوافق مع وضع ملحقات USB، استخدِم مكتبة الإضافات واستورِد هذه الحزمة. تجدر الإشارة إلى أنّه ليس من الضروري أن تتيح جميع أجهزة Android 2.3.4 ميزة ملحقات USB. وتقرّر كل شركة مصنّعة للأجهزة ما إذا كانت ستتيح هذه الميزة أم لا، ولهذا السبب يجب تحديدها في ملف البيان.
android.hardware.usb: تحتوي مساحة الاسم هذه على الفئات التي تتيح وضع ملحقات USB في الإصدار 3.1 من نظام التشغيل Android. يتم تضمين هذه الحزمة كجزء من واجهات برمجة التطبيقات لإطار العمل، لذا يتيح الإصدار 3.1 من نظام التشغيل Android وضع ملحق USB بدون استخدام مكتبة إضافية. استخدِم هذه الحزمة إذا كنت تهتم فقط بالأجهزة التي تعمل بنظام التشغيل Android 3.1 أو الأجهزة الأحدث التي تتضمّن دعمًا للأجهزة في وضع ملحقات USB، والذي يمكنك الإعلان عنه في ملف البيان.
تثبيت مكتبة الإضافات في Google APIs
إذا أردت تثبيت الإضافة، يمكنك إجراء ذلك من خلال تثبيت حزمة Google APIs Android API 10 باستخدام SDK Manager. يمكنك الاطّلاع على تثبيت إضافة Google APIs لمزيد من المعلومات حول تثبيت مكتبة الإضافات.
نظرة عامة على واجهة برمجة التطبيقات
بما أنّ مكتبة الإضافات هي برنامج تضمين لواجهات برمجة التطبيقات الخاصة بإطار العمل، فإنّ الفئات التي تتيح ميزة ملحقات USB متشابهة. يمكنك استخدام المستندات المرجعية لـ android.hardware.usb حتى إذا كنت تستخدم مكتبة الإضافات.
ملاحظة: هناك اختلاف بسيط في الاستخدام بين مكتبة الإضافات وواجهات برمجة التطبيقات الخاصة بإطار العمل يجب الانتباه إليه.
يوضّح الجدول التالي الفئات التي تتوافق مع واجهات برمجة التطبيقات لملحقات USB:
| الفئة | الوصف |
|---|---|
UsbManager |
يتيح لك تعداد ملحقات USB المتصلة والتواصل معها. |
UsbAccessory |
يمثّل هذا الإذن ملحق USB ويحتوي على طرق للوصول إلى معلوماته التي تكشف الهوية. |
الاختلافات في الاستخدام بين مكتبة الإضافات وواجهات برمجة التطبيقات الخاصة بالمنصة
هناك اختلافان في الاستخدام بين استخدام مكتبة إضافات Google APIs وواجهات برمجة التطبيقات الخاصة بالمنصة.
إذا كنت تستخدم مكتبة الإضافات، عليك الحصول على عنصر UsbManager بالطريقة التالية:
Kotlin
val manager = UsbManager.getInstance(this)
Java
UsbManager manager = UsbManager.getInstance(this);
إذا لم تكن تستخدم مكتبة الإضافات، عليك الحصول على عنصر UsbManager بالطريقة التالية:
Kotlin
val manager = getSystemService(Context.USB_SERVICE) as UsbManager
Java
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
عند الفلترة بحثًا عن ملحق متصل باستخدام intent filter، يتم تضمين عنصر UsbAccessory داخل الهدف الذي يتم تمريره إلى
تطبيقك. إذا كنت تستخدم مكتبة الإضافات، عليك الحصول على عنصر UsbAccessory بالطريقة التالية:
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
إذا لم تكن تستخدم مكتبة الإضافات، عليك الحصول على عنصر UsbAccessory بالطريقة التالية:
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
متطلبات ملف بيان Android
توضّح القائمة التالية ما تحتاج إلى إضافته إلى ملف بيان تطبيقك قبل العمل مع واجهات برمجة التطبيقات لملحقات USB. توضّح أمثلة ملفات البيان والموارد كيفية الإعلان عن هذه العناصر:
- بما أنّه لا يمكن ضمان توافق جميع الأجهزة التي تعمل بنظام التشغيل Android مع واجهات برمجة التطبيقات لملحقات USB،
يجب تضمين عنصر
<uses-feature>يوضّح أنّ تطبيقك يستخدم ميزةandroid.hardware.usb.accessory. - إذا كنت تستخدم
مكتبة الإضافات،
أضِف العنصر
<uses-library>مع تحديدcom.android.future.usb.accessoryللمكتبة. - اضبط الحد الأدنى لحزمة تطوير البرامج (SDK) للتطبيق على مستوى واجهة برمجة التطبيقات 10 إذا كنت تستخدم مكتبة الإضافات
أو مستوى واجهة برمجة التطبيقات 12 إذا كنت تستخدم حزمة
android.hardware.usb. -
إذا أردت أن يتم إشعار تطبيقك بملحق USB متصل، حدِّد زوج عناصر
<intent-filter>و<meta-data>لغرضandroid.hardware.usb.action.USB_ACCESSORY_ATTACHEDفي نشاطك الرئيسي. يشير العنصر<meta-data>إلى ملف موارد XML خارجي يوضّح معلومات تكشف الهوية حول الملحق الذي تريد رصده.في ملف موارد XML، حدِّد عناصر
<usb-accessory>للملحقات التي تريد فلترتها. يمكن أن يتضمّن كل عنصر<usb-accessory>السمات التالية:manufacturermodelversion
لا ننصح بالفلترة حسب
version. قد لا يحدّد الملحق أو الجهاز دائمًا سلسلة إصدار (عن قصد أو عن غير قصد). عندما يعلن تطبيقك عن سمة إصدار للفلترة وفقًا لها ولا يحدّد الملحق أو الجهاز سلسلة إصدار، يؤدي ذلك إلى حدوثNullPointerExceptionفي الإصدارات القديمة من Android. تم حلّ هذه المشكلة في Android 12.احفظ ملف الموارد في دليل
res/xml/. يجب أن يكون اسم ملف المورد (بدون الامتداد .xml) مطابقًا للاسم الذي حدّدته في العنصر<meta-data>. يظهر أيضًا تنسيق ملف موارد XML في المثال التالي.
أمثلة على ملفات البيان والموارد
يوضّح المثال التالي نموذج بيان وملف الموارد المقابل له:
<manifest ...> <uses-feature android:name="android.hardware.usb.accessory" /> <uses-sdk android:minSdkVersion="<version>" /> ... <application> <uses-library android:name="com.android.future.usb.accessory" /> <activity ...> ... <intent-filter> <action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" /> </intent-filter> <meta-data android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" android:resource="@xml/accessory_filter" /> </activity> </application> </manifest>
في هذه الحالة، يجب حفظ ملف الموارد التالي في
res/xml/accessory_filter.xml ويحدّد أنّه يجب فلترة أي ملحق يتضمّن
الطراز والشركة المصنّعة والإصدار المقابل. يرسل الملحق هذه السمات إلى الجهاز الذي يعمل بنظام التشغيل Android:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory model="DemoKit" manufacturer="Google" version="1.0"/> </resources>
العمل مع الملحقات
عندما يوصّل المستخدمون ملحقات USB بجهاز Android، يمكن لنظام Android تحديد ما إذا كان تطبيقك مهتمًا بالملحق المتصل. إذا كان الأمر كذلك، يمكنك إعداد الاتصال بالجهاز الملحق إذا أردت. لإجراء ذلك، يجب أن يستوفي تطبيقك الشروط التالية:
- يمكنك استكشاف الأجهزة الملحقة المتصلة باستخدام intent filter الذي يفلتر أحداث الأجهزة الملحقة المرفقة أو من خلال تعداد الأجهزة الملحقة المتصلة والعثور على الجهاز المناسب.
- اطلب من المستخدم الإذن بالتواصل مع الملحق، إذا لم تكن قد حصلت عليه من قبل.
- التواصل مع الملحق من خلال قراءة البيانات وكتابتها على نقاط النهاية المناسبة للواجهة
اكتشاف إكسسوار
يمكن لتطبيقك اكتشاف الملحقات إما باستخدام intent filter ليتم إعلامك عندما يقوم المستخدم بتوصيل ملحق أو عن طريق تعداد الملحقات المتصلة بالفعل. يُعدّ استخدام intent filter مفيدًا إذا أردت أن يتمكّن تطبيقك من رصد أحد الملحقات التي تريدها تلقائيًا. يُعدّ تعداد الملحقات المتصلة مفيدًا إذا كنت تريد الحصول على قائمة بجميع الملحقات المتصلة أو إذا لم يفلتر تطبيقك هدفًا.
استخدام intent filter
لجعل تطبيقك يكتشف ملحق USB معيّنًا، يمكنك تحديد intent filter
للفلترة حسب intent android.hardware.usb.action.USB_ACCESSORY_ATTACHED. بالإضافة إلى intent filter هذا، عليك تحديد ملف موارد يحدّد خصائص ملحق USB، مثل الشركة المصنّعة والطراز والإصدار.
يوضّح المثال التالي كيفية الإعلان عن intent filter:
<activity ...> ... <intent-filter> <action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" /> </intent-filter> <meta-data android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" android:resource="@xml/accessory_filter" /> </activity>
يوضّح المثال التالي كيفية الإعلان عن ملف الموارد المقابل الذي يحدّد ملحقات USB التي تهمّك:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory manufacturer="Google, Inc." model="DemoKit" version="1.0" /> </resources>
في نشاطك، يمكنك الحصول على UsbAccessory الذي يمثّل
الملحق المرفق من الطلب على النحو التالي (باستخدام مكتبة الإضافات):
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
أو على النحو التالي (باستخدام واجهات برمجة التطبيقات الخاصة بالمنصة):
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
تعداد الملحقات
يمكنك جعل تطبيقك يعدد الملحقات التي تم تحديدها أثناء تشغيل تطبيقك.
استخدِم طريقة getAccessoryList()
للحصول على مصفوفة لجميع ملحقات USB المتصلة:
Kotlin
val manager = getSystemService(Context.USB_SERVICE) as UsbManager val accessoryList: Array<out UsbAccessory> = manager.accessoryList
Java
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); UsbAccessory[] accessoryList = manager.getAccessoryList();
ملاحظة: يمكن استخدام ملحق واحد متصل فقط في كل مرة.
الحصول على إذن للتواصل مع جهاز ملحق
قبل الاتصال بملحق USB، يجب أن يحصل تطبيقك على إذن من المستخدمين.
ملاحظة: إذا كان تطبيقك يستخدم intent filter لاكتشاف الملحقات عند توصيلها، سيتلقّى تلقائيًا الإذن إذا سمح المستخدم لتطبيقك بمعالجة intent. وإذا لم يكن الأمر كذلك، يجب طلب الإذن صراحةً في تطبيقك قبل الاتصال بالملحق.
قد يكون طلب الإذن صراحةً ضروريًا في بعض الحالات، مثلاً عندما يعدد تطبيقك الملحقات المتصلة بالفعل ثم يريد الاتصال بأحدها. يجب التحقّق من إذن الوصول إلى أحد الملحقات قبل محاولة الاتصال به. وإذا لم يكن الأمر كذلك، فستتلقى خطأ أثناء التشغيل إذا رفض المستخدم الإذن بالوصول إلى الملحق.
للحصول على الإذن صراحةً، عليك أولاً إنشاء مستقبل بث. يستمع هذا المُستقبِل إلى الغرض الذي يتم بثه عند استدعاء requestPermission(). يؤدي استدعاء requestPermission() إلى عرض مربّع حوار للمستخدم يطلب منه الإذن بالاتصال بالجهاز الملحق. يوضّح الرمز النموذجي التالي كيفية إنشاء جهاز استقبال البث:
Kotlin
private const val ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION" private val usbReceiver = object : BroadcastReceiver() { override fun onReceive(context: Context, intent: Intent) { if (ACTION_USB_PERMISSION == intent.action) { synchronized(this) { val accessory: UsbAccessory? = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) { accessory?.apply { // call method to set up accessory communication } } else { Log.d(TAG, "permission denied for accessory $accessory") } } } } }
Java
private static final String ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION"; private final BroadcastReceiver usbReceiver = new BroadcastReceiver() { public void onReceive(Context context, Intent intent) { String action = intent.getAction(); if (ACTION_USB_PERMISSION.equals(action)) { synchronized (this) { UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) { if(accessory != null){ // call method to set up accessory communication } } else { Log.d(TAG, "permission denied for accessory " + accessory); } } } } };
لتسجيل جهاز استقبال البث، ضع هذا في إجراء onCreate() في نشاطك:
Kotlin
private const val ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION" ... val manager = getSystemService(Context.USB_SERVICE) as UsbManager ... permissionIntent = PendingIntent.getBroadcast(this, 0, Intent(ACTION_USB_PERMISSION), 0) val filter = IntentFilter(ACTION_USB_PERMISSION) registerReceiver(usbReceiver, filter)
Java
UsbManager usbManager = (UsbManager) getSystemService(Context.USB_SERVICE); private static final String ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION"; ... permissionIntent = PendingIntent.getBroadcast(this, 0, new Intent(ACTION_USB_PERMISSION), 0); IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION); registerReceiver(usbReceiver, filter);
لعرض مربّع الحوار الذي يطلب من المستخدمين الإذن بالاتصال بالملحق، يمكنك استدعاء الطريقة
requestPermission():
Kotlin
lateinit var accessory: UsbAccessory ... usbManager.requestPermission(accessory, permissionIntent)
Java
UsbAccessory accessory; ... usbManager.requestPermission(accessory, permissionIntent);
عندما يردّ المستخدمون على مربّع الحوار، يتلقّى جهاز استقبال البثّ الطلب الذي يحتوي على السمة الإضافية EXTRA_PERMISSION_GRANTED، وهي قيمة منطقية تمثّل الإجابة. تحقَّق من هذه القيمة الإضافية للتأكّد من أنّها صحيحة قبل الاتصال
بالملحق.
التواصل مع ملحق
يمكنك التواصل مع الملحق باستخدام UsbManager للحصول على واصِف ملف يمكنك إعداد عمليات نقل البيانات الواردة والصادرة لقراءة البيانات وكتابتها في الواصِف. وتمثّل عمليات النقل نقاط النهاية المجمّعة للإدخال والإخراج في الملحق. يجب إعداد الاتصال بين الجهاز والملحق في سلسلة محادثات أخرى، حتى لا يتم قفل سلسلة واجهة المستخدم الرئيسية. يوضّح المثال التالي كيفية فتح ملحق للتواصل معه:
Kotlin
private lateinit var accessory: UsbAccessory private var fileDescriptor: ParcelFileDescriptor? = null private var inputStream: FileInputStream? = null private var outputStream: FileOutputStream? = null ... private fun openAccessory() { Log.d(TAG, "openAccessory: $mAccessory") fileDescriptor = usbManager.openAccessory(accessory) fileDescriptor?.fileDescriptor?.also { fd -> inputStream = FileInputStream(fd) outputStream = FileOutputStream(fd) val thread = Thread(null, this, "AccessoryThread") thread.start() } }
Java
UsbAccessory accessory; ParcelFileDescriptor fileDescriptor; FileInputStream inputStream; FileOutputStream outputStream; ... private void openAccessory() { Log.d(TAG, "openAccessory: " + accessory); fileDescriptor = usbManager.openAccessory(accessory); if (fileDescriptor != null) { FileDescriptor fd = fileDescriptor.getFileDescriptor(); inputStream = new FileInputStream(fd); outputStream = new FileOutputStream(fd); Thread thread = new Thread(null, this, "AccessoryThread"); thread.start(); } }
في طريقة run() لسلسلة المحادثات، يمكنك القراءة والكتابة في الملحق باستخدام
كائنات FileInputStream أو FileOutputStream. عند قراءة
البيانات من ملحق باستخدام كائن FileInputStream، تأكَّد من أنّ المخزن المؤقت الذي
تستخدمه كبير بما يكفي لتخزين بيانات حزمة USB. يتيح بروتوكول ملحقات Android استخدام مخازن مؤقتة للحزم تصل سعتها إلى 16384 بايت، لذا يمكنك اختيار تحديد المخزن المؤقت دائمًا بهذا الحجم لتبسيط الأمر.
ملاحظة: على مستوى أدنى، تكون الحزم بحجم 64 بايت لملحقات USB ذات السرعة الكاملة و512 بايت لملحقات USB ذات السرعة العالية. ويجمع بروتوكول ملحقات Android الحِزم معًا لكلا السرعتَين في حزمة منطقية واحدة من أجل التبسيط.
لمزيد من المعلومات حول استخدام سلاسل المحادثات في Android، يُرجى الاطّلاع على العمليات وسلاسل المحادثات.
إنهاء الاتصال بملحق
عند الانتهاء من الاتصال بملحق أو إذا تم فصل الملحق، أغلِق واصِف الملف الذي فتحته من خلال استدعاء close().
للاستماع إلى أحداث الفصل، أنشئ جهاز استقبال بث مثل ما يلي:
Kotlin
var usbReceiver: BroadcastReceiver = object : BroadcastReceiver() { override fun onReceive(context: Context, intent: Intent) { if (UsbManager.ACTION_USB_ACCESSORY_DETACHED == intent.action) { val accessory: UsbAccessory? = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) accessory?.apply { // call your method that cleans up and closes communication with the accessory } } } }
Java
BroadcastReceiver usbReceiver = new BroadcastReceiver() { public void onReceive(Context context, Intent intent) { String action = intent.getAction(); if (UsbManager.ACTION_USB_ACCESSORY_DETACHED.equals(action)) { UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); if (accessory != null) { // call your method that cleans up and closes communication with the accessory } } } };
يسمح إنشاء مستقبِل البث داخل التطبيق، وليس البيان، لتطبيقك بالتعامل مع الأحداث المنفصلة فقط أثناء تشغيله. بهذه الطريقة، يتم إرسال الأحداث المنفصلة إلى التطبيق قيد التشغيل حاليًا فقط ولا يتم بثها إلى جميع التطبيقات.