نظرة عامة على ملحق USB

يسمح وضع ملحقات 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> السمات التالية:

    • manufacturer
    • model
    • version

    لا ننصح بالفلترة حسب 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 تحديد ما إذا كان تطبيقك مهتمًا بالملحق المتصل. إذا كان الأمر كذلك، يمكنك إعداد الاتصال بالجهاز الملحق إذا أردت. لإجراء ذلك، يجب أن يستوفي تطبيقك الشروط التالية:

  1. يمكنك استكشاف الأجهزة الملحقة المتصلة باستخدام intent filter الذي يفلتر أحداث الأجهزة الملحقة المرفقة أو من خلال تعداد الأجهزة الملحقة المتصلة والعثور على الجهاز المناسب.
  2. اطلب من المستخدم الإذن بالتواصل مع الملحق، إذا لم تكن قد حصلت عليه من قبل.
  3. التواصل مع الملحق من خلال قراءة البيانات وكتابتها على نقاط النهاية المناسبة للواجهة

اكتشاف إكسسوار

يمكن لتطبيقك اكتشاف الملحقات إما باستخدام 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
            }
        }
    }
};

يسمح إنشاء مستقبِل البث داخل التطبيق، وليس البيان، لتطبيقك بالتعامل مع الأحداث المنفصلة فقط أثناء تشغيله. بهذه الطريقة، يتم إرسال الأحداث المنفصلة إلى التطبيق قيد التشغيل حاليًا فقط ولا يتم بثها إلى جميع التطبيقات.