USB Accessory

原文链接地址 http://developer.android.com/intl/zh-cn/guide/topics/connectivity/usb/accessory.html#manifest

USB附件模式允许用户连接 USB主机硬件专门为android设备。配件必须遵循 Android附属协议中列出 Android配件开发工具包文档。这允许android设备仍不能作为USB主机与USB接口进行交互硬件。当一个Android设备在USB附件模式中,附加的Android USB 附件作为主机,提供了USB总线,并列举了连接设备。 Android 3.1(API级别12)支持USB附件模式和特性也是补丁安卓2.3.4(API级别10)能够支持更广泛的设备。

选择正确的USB配件api

虽然介绍了USB配件api在Android 3.1平台,他们还可以在安卓2.3.4使用Google api插件库。因为这些api 补丁使用外部库,有两个包,您可以导入支持USB 附件模式。取决于安卓设备你想支持,你可能需要使用一种:

com.android.future.usb :在安卓2.3.4,支持USB附件模式谷歌api的插件图书馆包括补丁USB配件api和它们包含在这名称空间。 Android 3.1还支持导入和调用的类在这个名称空间支持插件库编写的应用程序。这个附加组件库是一个瘦包装器在android.hardware.usb 附件的api和不支持USB主机模式。如果你想支持广泛的设备支持USB附件模式,使用插件图书馆和导入这个包。重要的是要注意,并非所有的安卓2.3.4设备需要支持USB附件功能。每个设备制造商决定是否支持这一功能,这就是为什么你必须声明你的清单文件。
android.hardware.usb :该命名空间包含的类支持USB 附件模式在Android 3.1。这个包包含作为框架api的一部分,所以 Android 3.1支持USB附件模式不使用一个附加的库。使用这个包如果你只关心Android 3.1或更新的硬件支持USB设备辅助模式,您可以声明你的清单文件。

安装谷歌api的插件库

如果你想要安装附加组件,可以通过安装Google API Android API 10 与SDK包管理器。看到安装谷歌api 附加组件有关安装附加组件库的更多信息。

API概述

因为框架api的插件库是一个包装器,支持的类 USB附件功能是相似的。您可以使用的参考文档android.hardware.usb 即使你是使用插件库。

下表描述了USB配件api支持的类:

类	描述
`UsbManager`	允许你列举和与连接USB通信配件。
`UsbAccessory`	代表一个USB配件和包含的方法来访问它的识别信息。

使用附加组件库和平台api之间的区别

有两种用法区别使用Google api插件库平台 api。

如果你是使用插件库,你必须获得 UsbManager 对象以下列方式:

UsbManager manager = UsbManager.getInstance(this);

如果你不使用附加组件库,你必须获得 UsbManager 对象以下列方式:

UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);

当你为一个连接过滤器配件意图过滤器, UsbAccessory 对象包含在意图传递给你应用程序。如果你是使用插件库,你必须获得 UsbAccessory 对象以下列方式:

UsbAccessory accessory = UsbManager.getAccessory(intent);

如果你不使用附加组件库,你必须获得 UsbAccessory 对象以下列方式:

UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);

Android清单要求

下面的列表描述了您需要添加到您的应用程序的清单文件使用USB accesory api。的清单和资源文件例子演示如何声明这些项目:

因为不是所有的android设备保证支持USB配件api, 包括一个 < uses-feature > 您的应用程序使用的元素声明的 android.hardware.usb.accessory 特性。
如果您正在使用插件库 , 添加 < uses-library > 元素指定 com.android.future.usb.accessory 为图书馆。
设置最低SDK应用程序的API级别10如果使用插件库如果您正在使用或12 android.hardware.usb 包中。
如果你想让你的应用程序连接USB附件的通知,指定一个 <意图过滤器> 和 <元数据> 元素对的android.hardware.usb.action.USB_ACCESSORY_ATTACHED 你的主要活动的意图。的 <元数据> 元素指向外部的XML资源文件声明确认附件的信息你想检测。

在XML资源文件中,申报的东西 < usb-accessory > 元素的配件要过滤。每一个 < usb-accessory > 可以有以下属性:
- 制造商
- 模型
- 版本
节省的资源文件 res / xml / 目录中。资源文件名称 (没有。 xml扩展)必须与你指定的相同 <元数据> 元素。格式为XML资源文件所示的例子在下面。

清单和资源文件的例子

下面的示例显示了一个示例清单和相应的资源文件:

 ...>     android:name="android.hardware.usb.accessory" />        <version>" />    ...           android:name="com.android.future.usb.accessory" />         ...>            ...                             android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" />                         android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED"                android:resource="@xml/accessory_filter" />

在这种情况下,应该保存在下面的资源文件 res / xml / accessory_filter.xml 并指定任何配件的相应的模型中,制造商,应该过滤和版本。附件发送这些属性的android设备上:

<?xml version="1.0" encoding="utf-8"?>     model="DemoKit" manufacturer="Google" version="1.0"/>

使用附件

当用户连接USB配件Android手机,Android系统确定应用程序是否感兴趣的连接配件。如果是这样,你可以设置如果需要沟通与配件。要做到这一点,您的应用程序有:

发现连接配件用一个意图过滤器,过滤器的配件附加事件或通过列举连接配件,找到合适的一个。
要求用户批准与配件,如果没有了获得的。
与附件的读写数据在适当的接口端点。

发现一个附件

您的应用程序可以发现配件通过使用一个意图过滤器时收到通知用户连接一个附件或通过列举配件已经连接。使用一个意图过滤器是非常有用的,如果你想应用程序能够自动检测所需的配件。列举相关配件是有用的,如果你想要所有的列表连接配件或如果您的应用程序没有过滤的目的。

使用一个意图过滤器

您的应用程序发现特定USB配件,你可以指定一个意图过滤器过滤的android.hardware.usb.action.USB_ACCESSORY_ATTACHED 意图。沿着这个意图过滤器,您需要指定一个资源文件,指定属性的USB 配件,如制造商、模型和版本。当用户连接一个匹配的配件你的辅助滤波器,

下面的例子显示了如何声明意图过滤器:

 ...>    ...             android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" />         android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED"        android:resource="@xml/accessory_filter" />

下面的例子展示了如何声明指定相应的资源文件 USB附件你感兴趣:

<?xml version="1.0" encoding="utf-8"?>     manufacturer="Google, Inc." model="DemoKit" version="1.0" />

在你的活动,你可以获得 UsbAccessory 代表这样的意图的附属配件(附加库):

UsbAccessory accessory = UsbManager.getAccessory(intent);

或者像这样的(与平台api):

UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);

列举配件

应用程序可以列举饰品,当你发现了自己应用程序正在运行。

使用 getAccessoryList() 方法得到一个数组的所有USB配件连接:

UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);UsbAccessory[] accessoryList = manager.getAcccessoryList();

注意: 目前,只有一个连接配件支持一次,但API的设计目的是在未来支持多个附件。

获得许可与配件

在与USB通信配件之前,你的应用程序必须得到你的许可用户。

注意: 如果您的应用程序使用一个意图过滤器发现配件连接,它可以自动接收如果用户许可允许您的应用程序处理的目的。如果没有,你必须请求允许显式地在您的应用程序连接到配件。

明确要求许可可能是必要的在某些情况下,例如当你应用列举了已经连接的配件,然后想要沟通一个。你必须检查权限访问在试图与之前一个附件。如果不是,你将收到一个运行时错误,如果用户拒绝访问配件。

显式地获得许可,首先创建一个广播接收器。这个接收器监听意图让广播时调用 requestPermission() 。调用requestPermission() 显示一个对话框用户请求权限连接配件。下面的示例代码显示了如何创建广播接收机:

private static final String ACTION_USB_PERMISSION =    "com.android.example.USB_PERMISSION";private final BroadcastReceiver mUsbReceiver = 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() 方法在你的活动:

UsbManager mUsbManager = (UsbManager) getSystemService(Context.USB_SERVICE);private static final String ACTION_USB_PERMISSION =    "com.android.example.USB_PERMISSION";...mPermissionIntent = PendingIntent.getBroadcast(this, 0, new Intent(ACTION_USB_PERMISSION), 0);IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION);registerReceiver(mUsbReceiver, filter);

显示对话框,询问用户允许连接到配件,调用 requestPermission() 方法:

UsbAccessory accessory;...mUsbManager.requestPermission(accessory, mPermissionIntent);

当用户回复的对话框,你的广播接收器接收包含意图 EXTRA_PERMISSION_GRANTED 额外的,这是一个布尔值代表回答。之前检查这个额外的价值真正的连接配件。

与一个附件

你可以与附件使用通信 UsbManager 来获得一个文件描述符,您可以设置输入和输出流读写数据描述符。流表示附件的输入和输出端点。你应该设定之间的通信设备和附属在另一个线程,所以你不锁主UI线程。下面的例子显示了如何打开一个与附件:

UsbAccessory mAccessory;ParcelFileDescriptor mFileDescriptor;FileInputStream mInputStream;FileOutputStream mOutputStream;...private void openAccessory() {    Log.d(TAG, "openAccessory: " + accessory);    mFileDescriptor = mUsbManager.openAccessory(mAccessory);    if (mFileDescriptor != null) {        FileDescriptor fd = mFileDescriptor.getFileDescriptor();        mInputStream = new FileInputStream(fd);        mOutputStream = new FileOutputStream(fd);        Thread thread = new Thread(null, this, "AccessoryThread");        thread.start();    }}

线程的 run() 方法,您可以读取和写入附件使用的 FileInputStream 或 FileOutputStream 对象。当阅读数据从一个附件 FileInputStream 对象,确保缓冲你使用USB包数据存储足够大。 Android附属协议支持包缓冲区最多16384个字节,所以你可以选择总是声明你的缓冲区大小为简单起见。

注意: 在一个较低的水平,USB的64字节数据包全速USB高速配件配件和512字节。 Android配件协议包的包在一起的速度为一个逻辑包为简单起见。

更多信息在Android使用线程,明白了流程和线程。

终止通信配件

当你完成通信配件或附件是分离的,关闭通过调用打开文件描述符 close() 。听独立事件,创建一个广播接收器像下面:

BroadcastReceiver mUsbReceiver = 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            }        }    }};

创建应用程序内的广播接收器,而不是清单,允许你它运行时应用程序只处理分离事件。这种方式,分离事件只发送给当前正在运行的应用程序,而不是广播给所有的应用程序。

android里面的USB功能-----Accessory模式