AllJoyn Control Panel服务框架用户指南（Android）

AllJoyn Control Panel Service Framework Usage Guide(Android)

1 前言
  1.1 目的
  1.2 范围
  1.3 参考文档
  1.4 缩写词和条目
2 概述
  2.1 参考代码
    2.1.1 源代码
    2.1.2 参考Java应用程序代码
  2.2 获得Control Panel服务框架
  2.3 构建控制端
  2.4 设置AllJoyn框架和About功能  
3 实现控制端
  3.1 初始化AllJoyn框架
  3.2 启动AboutService在服务器模式
    3.2.1 初始化About功能
    3.2.2 倾听来自受控端的通告
  3.3 获得可控的设备
  3.4 启动与受控端的会话
    3.4.1 执行DeviceEventsListeners
  3.5 获得设备control panel
  3.6 获得根容器
    3.6.1 实例ControlPanelEventsListener
  3.7 构建Android UI元素
    3.7.1 ControlPanelExceptionHander
  3.8 编译代码
 

1 前言
1.1 目的
本文档说明如何使用AllJoyn框架ControlPanel参考代码实现ControlPanel服务框架控制端。
 
1.2 范围
本文档适用于软件工程师和假定你已经精通AllJoyn SDK。

1.3 参考文档
以下参考文档基于AllSeen联盟网页Docs/Downloads章节：  
■ AllJoyn. Framework Tutorial
■ Introduction to AllJoyn. Thin Client
■ Guide to AllJoyn. Development Using the Java SDK
■ AllJoyn. Control Panel Service Framework 1.0 Interface Specification
■ Getting Started with the AllJoyn. About Feature 1.0 (Android)
■ Getting Started with the AllJoyn. Control Panel Service Framework 1.0 (Android

1.4 缩写词和条目
术语                  定义
-----------------------------------------------
Adapter                Control Panel服务框架层翻译接收
                      到的UI元素到Android的UI元素
-----------------------------------------------
AllJoyn device        支持AllJoyn框架，能连接到
                      私人网络的设备
-----------------------------------------------
Control panel          允许用户与设备交互的部件集合。
                      一个Control Panel被受控者定义和发布，
                      被控制器发现和显示。一个设备
                      能有多个，能被定义在预语言基础上。
-----------------------------------------------
AllJoyn device        支持AllJoyn框架，能连接到
                      私人网络的设备                      
-----------------------------------------------

Controllee            一个AllJoyn应用程序，发布
                      Control Panel接口，所以其他AllJoyn
                      设备可以控制它。
-----------------------------------------------
Controller            一个AllJoyn应用程序控制另一个
                      发布Control Panel接口的AllJoyn设备
-----------------------------------------------
ControlPanelEventsListener
                      一个接口，监听ControlPanel相关事件
-----------------------------------------------
DeviceControPanel      可控设备的一个具体control panel
-----------------------------------------------
DeviceEventsListener  一个接口，监听会话事件
-----------------------------------------------
Widget                一个UI元素在Control Panel代表一个接口。
                      它生动地表现一个用户执行功能或使用内容。
-----------------------------------------------


2 概述
2.1 参考代码
参考代码包含一个实现Android控制端的应用程序。

2.1.1 源代码
表1列出构建控制端应用程序的软件包。
这个软件包依赖alljoyn.jar和About功能。
------------------------------------------------------
软件包                    描述
------------------------------------------------------
ControlPanelService.jar    服务层做所有违反AllJoyn框架的工作
------------------------------------------------------
ControlPanelAdapter.jar    创建android用户界面视图
------------------------------------------------------

2.1.2 参考Java应用程序代码
------------------------------------------------------
应用程序                  描述
------------------------------------------------------
ControlPanelBrowser.apk    使用服务框架和适配器APIs的样本应用程序
------------------------------------------------------

2.2 获得Control Panel服务框架
参考AllJoyn Control Panel服务框架（Android）文档获得Control Panel服务框架。

2.3 构建控制端
在上层执行以下规定构建受控端。
〉创建AllJoyn应用程序的基础部分；
〉启动AboutClient；
〉监听通告在网络上寻找可控设备；
〉从集合中选择一个control panel,在收到的通过里您的首选语言；
〉设置你想要交互的可控设备之间的会话；
〉通过适配器获得设备的control pane部件，并转换为Andreid UI元素；
〉从适配器获得Android UI元素显示在应用程序中。这些元素组合来创建图形显示控制面板控制器应用程序的最终用户进行交互。

2.4 设置AllJoyn框架和About功能
该服务所需的步骤都是普遍使用的AllJoyn框架和任何应用程序的应用程序使用一个或多个AllJoyn服务。
使用控制面板服务框架之前,必须实现About功能和AllJoyn框架设置。
完成程序根据下列文件中指导：
■ Getting Started with the AllJoyn. About Feature (Android)
■ AllJoyn. About Feature Usage Guide (Android)

 
3 实现控制端
3.1 初始化AllJoyn框架
参考Getting Started with the AllJoyn. About Feature (Android) Feature文档指示建立AllJoyn服务框架。

3.2 启动AboutService在服务器模式
Control Panel服务框架依赖About功能。
关于About功能更多的信息，参见AllJoyn About Feature UsageGuide (Android)。
 
3.2.1 初始化About功能
  aboutClient = AboutServiceImpl.getInstance();
  aboutClient.startAboutClient(bus);

3.2.2 倾听来自受控端的通告
通过About功能注册一个通告处理器接收通过。
  aboutClient.addAnnouncementHandler(announcementHandler);
对于每个接收的通告,检查是否实现了ControlPanel接口。如果是这样,将其保存为一个可控设备供以后使用。
  public void onAnnouncement(String busName, short port, BusObjectDescription[]
                              objectDescriptions, Map aboutMap) {
    Variant varDeviceId = aboutMap.get(AboutKeys.ABOUT_DEVICE_ID);
    String devIdSig = VariantUtil.getSignature(varDeviceId);
    if ( !devIdSig.equals("s") ) {
      return;
    }
    deviceId = varDeviceId.getObject(String.class);
    // get the device name from the annoucement just as the device id above
    for(int i = 0; i < objectDescriptions.length; ++i){
      BusObjectDescription description = objectDescriptions[i];
      String[] supportedInterfaces = description.getInterfaces();
      for(int j = 0; j < supportedInterfaces.length; ++j){
        if(supportedInterfaces[j].startsWith("org.alljoyn.ControlPanel")){
          // found a control panel interface
          if (deviceContext == null) {
            deviceContext = new DeviceContext(deviceId, busName, deviceName);
          }
          deviceContext.addObjectInterfaces(description.getPath(), supportedInterfaces);
        }
      }
    }
  }

3.3 获得可控的设备
一旦检测出可控设备通告，获取ControllableDevice代理对象。
ControllableDevice用于后来创建一个与受控端的会话。
  controllableDevice = ControlPanelService.getInstance().getControllableDevice(deviceContext.deviceId, deviceContext.busName);
 
3.4 启动与受控端的会话
为了获得受控端的control panels,你必须创建一个会话。这是一个异步调用,需要DeviceEventsListener作为回调。
  controllableDevice.startSession(DeviceEventsListener);
监听sessionEstablished事件验证成功建立了会话。
当会话建立，一些control panel容器被接收。
可能有多个control panel容器，每个用途不同。例如，一个家庭用户和另一天技术员。
每一个容器的元素是一个DeviceControlPanel和提供每种语言。
  @Override
  public void sessionEstablished(ControllableDevice device,
  Collection controlPanelContainer)
  {
    //At this point the session was established
  }

3.4.1 实现DeviceEventsListeners
DeviceEventsListener还有其他方法，应该实现接收会话相关的事件从Control Panel服务框架。
  public void sessionLost(ControllableDevice device);
  public void errorOccured(ControllableDevice device, String reason);
更多信息，参见API文档。  

3.5 获得设备control panel
得到一组设备才control panels,并选择所需的语言。
  Collection controlPanels =controlPanelCollection.getControlPanels();
  for(DeviceControlPanel controlPanel : controlPanels) {
    String cpLanguage = controlPanel.getLanguage();
    if (cpLanguage.equalsIgnoreCase(desired_language){
      //found the desired device control panel
      DeviceControlPanel deviceControlPanel = controlPanel;
    }
  }

3.6 获得根容器
一旦DeviceControlPanel被选择，获得它的根容器元素。
根容器元素是顶层UI元素，它包含选择的DeviceControlPanel的所有子ＵＩ元素。
检测根容器类型。它可能是ContainerWidget或AlertDialogWidget的任一个。
  UIElement rootContainerElement =deviceControlPanel.getRootElement(ControlPanelEventsListener);
  UIElementType elementType = rootContainerElement.getElementType();

3.6.1 实现ControlPanelEventsListener
ControlPanelEventsListener接口应该实现接收到的变化,发生在受控端control panel相应的UI反应。
  public void valueChanged(DeviceControlPanel panel, UIElement uielement, ObjectnewValue);
  public void metadataChanged(DeviceControlPanel panel, UIElement uielement);
  public void notificationActionDismiss(DeviceControlPanel panel);
  public void errorOccured(DeviceControlPanel panel, String reason);  

3.7 构建Android UI元素
适配器依次通过从根容器接收的UI元素列表,,构建一个线性布局包含所有的Android视图。
这个应用能移植到activity内部。
  ControlPanelAdapter controlPanelAdapter =new ControlPanelAdapter(Context, ControlPanelExceptionHandler);
  // create an android view for the abstract container
  final View adapterView = controlPanelAdapter.createContainerView(container);
 
3.7.1 ControlPanelExceptionHander
当发生错误检索任何部件,适配器将抛出一个异常在异常处理中更好地处理错误。
应用程序可以决定如何向用户显示这个错误。
一个典型的方法是向用户显示发生了错误。

3.8 编译代码