Android基於Cling開發DLNA應用

# Android基於Cling開發DLNA應用

## DLNA

DLNA，Digital Living Network Alliance的簡稱，即數字生活網絡聯盟。其由消費性電子、移動電話以及電腦廠商組成。目標在於創建一套可以使得各廠商的產品互相連接，互相適應的工業標準，從而爲消費者實現數字化生活。

更多資料：

1. About DLNA
2. 維基百科
3. 百度百科

## Cling

UPnP/DLNA library for Java and Android。

GitHub最多關注，當前仍在維護，許可協議爲LGPL或CDDL。

用戶手冊：Cling on Android

以下爲中文譯文：

## 5. Android上的Cling
Cling Core爲Android應用提供了UPnP棧。由於如今大部分Android系統都是小型手持設備，所以通常你需要寫控制端應用。然而你也可以寫Android上的UPnP服務應用，其所有特性Cling Core都支持。

```
Android模擬器上的Cling
在寫此時，Android模擬器還不支持接收UDP組播。不過，可以發送UDP組播。你能夠發送一個組播UPnP搜尋，並接收UDP單播迴應，繼而發現正運行的設備。你發現不了在搜尋後新開啓的設備，並且在設備關閉時也收不到消息。另外，其他在你網絡的控制端應用，則不能發現你本地的Android設備或服務。在你測試應用時，所有這些情況都會使你感到困惑，所以除非你真得理解哪些有作用、哪些沒有，不然你應當使用一個真正的設備。
這章闡述了你如何整合Cling到你的Android應用，使其成爲一個共享的部件。
```

### 5.1. 配置應用服務
你可以在Android應用主activity中實例化Cling UpnpService。另一方面，如果你好些activities都要要求訪問UPnP棧，那麼最好採用後臺服務，android.app.Service。之後，任何想要訪問UPnP棧的activity，都能夠在需要時綁定或解綁該服務。

該服務組件的接口是org.teleal.cling.android.AndroidUpnpService：

```
public interface AndroidUpnpService {
    public UpnpService get();
    public UpnpServiceConfiguration getConfiguration();
    public Registry getRegistry();
    public ControlPoint getControlPoint();
}
```

activity通常訪問已知UPnP設備的註冊表，或者通過ControlPoint查詢和控制UPnP設備。
你必須在AndroidManifest.xml內配置內建的服務實現：

```
<manifest ...>

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    <application ...>

        <activity ...>
            ...
        </activity>

        <service android:name="org.teleal.cling.android.AndroidUpnpServiceImpl"/>

    </application>

</manifest>
```

此Cling UPnP服務要求設備WiFi接口的訪問權限，事實上其也只將會綁定網絡接口。
此服務將會自動檢測WiFi接口的關閉，並優雅地處理這種情形：任何客戶端操作都會導致"no response from server"狀態，而你的代碼必須預料並處理該狀態。

當服務組件創建或銷燬時，會相應開啓和關閉UPnP系統。這依賴於在你的activities裏是如何訪問此組件的。

### 5.2 activity如何訪問服務
service的生命週期在Android中很好的被定義了。如果service還沒啓動的話，第一個綁定服務的activity將會啓動它。當不再有activity綁定到service上時，操作系統將會銷燬此service。

讓我們寫一個簡單的UPnP瀏覽activity。它用於將所有你網絡內的設備顯示在一個列表內，並有一個菜單選項來觸發搜尋。activity連接UPnP服務之後，會一直監聽註冊表內設備的增加和刪除，所以顯示的設備列表會實時更新。

以下是activity類的骨架：

```
import android.app.ListActivity;
import android.content.ComponentName;
import android.content.Context;
import android.content.Intent;
import android.content.ServiceConnection;
import android.os.Bundle;
import android.os.IBinder;
import android.view.Menu;
import android.view.MenuItem;
import android.widget.ArrayAdapter;
import android.widget.Toast;
import org.teleal.cling.android.AndroidUpnpService;
import org.teleal.cling.android.AndroidUpnpServiceImpl;
import org.teleal.cling.model.meta.Device;
import org.teleal.cling.model.meta.LocalDevice;
import org.teleal.cling.model.meta.RemoteDevice;
import org.teleal.cling.registry.DefaultRegistryListener;
import org.teleal.cling.registry.Registry;

public class UpnpBrowser extends ListActivity {

    private ArrayAdapter<DeviceDisplay> listAdapter;

    private AndroidUpnpService upnpService;

    private ServiceConnection serviceConnection = ...

    private RegistryListener registryListener = new BrowseRegistryListener();

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        listAdapter =
            new ArrayAdapter(
                this,
                android.R.layout.simple_list_item_1
            );
        setListAdapter(listAdapter);

        getApplicationContext().bindService(
            new Intent(this, AndroidUpnpServiceImpl.class),
            serviceConnection,
            Context.BIND_AUTO_CREATE
        );
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        if (upnpService != null) {
            upnpService.getRegistry().removeListener(registryListener);
        }
        getApplicationContext().unbindService(serviceConnection);
    }

    ...

}
```

我們採用Android運行時默認提供的佈局和ListActivity父類。注意這個類可以是你應用的主activity，或者進一步上升進任務的堆棧。listAdapter黏合了Cling Registry上設備的增加移除事件與展示在用戶界面的列表項目。

當沒有後臺服務綁定到該activity時，upnpService變量爲null。綁定和解綁發生在onCreate()和onDestroy()回調，所以activity綁定服務和它的生存週期一樣長。

```
暫停後臺的UPnP服務
當一個activity不再活動時（停止或暫停狀態），它仍會綁定着UPnP服務。UPnP服務將會持續運行，即使應用不再可見。由於UPnP服務的註冊表一定會定期維護髮現的設備、刷新本地設備的通告、刪除過期的GENA事件訂閱等，將會消耗你設備的CPU和電量。當activity onPause()或onStop()方法被調用時，你可以調用Registry#pause()來通知UPnP服務不再維護註冊表。之後，你可以通過Registry#resume()來恢復後臺服務，或同時用Registry#isPaused()檢查狀態。請閱讀這些方法的Javadoc瞭解詳細信息，以及暫停註冊表維護對於設備、服務和GENA訂閱的意義。
```

以下是使用ServiceConnection處理綁定和解綁服務：

```
private ServiceConnection serviceConnection = new ServiceConnection() {

    public void onServiceConnected(ComponentName className, IBinder service) {
        upnpService = (AndroidUpnpService) service;

        // Refresh the list with all known devices
        listAdapter.clear();
        for (Device device : upnpService.getRegistry().getDevices()) {
            registryListener.deviceAdded(device);
        }

        // Getting ready for future device advertisements
        upnpService.getRegistry().addListener(registryListener);

        // Search asynchronously for all devices
        upnpService.getControlPoint().search();
    }

    public void onServiceDisconnected(ComponentName className) {
        upnpService = null;
    }
};
```

首先，所有已知的UPnP設備能夠被查詢和顯示（如果UPnP服務剛開啓且到到目前還沒有設備通告它的存在）。

然後，給UPnP服務的註冊表增加一個監聽者。該監聽者將會處理在你網絡上發現的設備的增加和移除，並在更新在用戶界面列表內顯示的項目。當activity銷燬時，BrowseRegistryListener會被移除。

最後，通過發送一個搜尋消息給所有UPnP設備，你會開啓異步搜索，此時這些設備將通告它們的存在。注意這個搜尋消息不是每次連接服務都需要的。這隻需一次，在當主activity和應用啓動時，其會將已知設備寫入註冊表。

以下是BrowseRegistryListener，他的任務就是更新列表項的顯示：

```
class BrowseRegistryListener extends DefaultRegistryListener {

    @Override
    public void remoteDeviceDiscoveryStarted(Registry registry, RemoteDevice device) {
        deviceAdded(device);
    }

    @Override
    public void remoteDeviceDiscoveryFailed(Registry registry, final RemoteDevice device, final Exception ex) {
        runOnUiThread(new Runnable() {
            public void run() {
                Toast.makeText(
                        BrowseActivity.this,
                        "Discovery failed of '" + device.getDisplayString() + "': " +
                                (ex != null ? ex.toString() : "Couldn't retrieve device/service descriptors"),
                        Toast.LENGTH_LONG
                ).show();
            }
        });
        deviceRemoved(device);
    }

    @Override
    public void remoteDeviceAdded(Registry registry, RemoteDevice device) {
        deviceAdded(device);
    }

    @Override
    public void remoteDeviceRemoved(Registry registry, RemoteDevice device) {
        deviceRemoved(device);
    }

    @Override
    public void localDeviceAdded(Registry registry, LocalDevice device) {
        deviceAdded(device);
    }

    @Override
    public void localDeviceRemoved(Registry registry, LocalDevice device) {
        deviceRemoved(device);
    }

    public void deviceAdded(final Device device) {
        runOnUiThread(new Runnable() {
            public void run() {
                DeviceDisplay d = new DeviceDisplay(device);
                int position = listAdapter.getPosition(d);
                if (position >= 0) {
                    // Device already in the list, re-set new value at same position
                    listAdapter.remove(d);
                    listAdapter.insert(d, position);
                } else {
                    listAdapter.add(d);
                }
            }
        });
    }

    public void deviceRemoved(final Device device) {
        runOnUiThread(new Runnable() {
            public void run() {
                listAdapter.remove(new DeviceDisplay(device));
            }
        });
    }
}
```

鑑於性能的原因，當發現設備時，我們會直到一個完整的hydrated（所有設備被檢索和驗證）設備元數據模型可用時才執行等待。我們響應儘可能得快，同時只當remoteDeviceAdded()方法被調用時纔去等待。甚至當搜索仍在運行時，我們仍舊顯示所有設備。在臺式電腦上你通常不需要關心這個，不過，Android手持設備效率慢，並且UPnP使用好些臃腫的XML描述符來交換關於設備和服務的元數據。有時，在設備和它的服務完全可用前，這可能會花費數秒鐘。而remoteDeviceDiscoveryStarted()和remoteDeviceDiscoveryFailed()方法在搜索處理時會盡快被調用。順便說一句，如果設備有相同的UDN就表示相等的(a.equal(b))，但它們可能不會完全一致(a==b)。

注意註冊表將會在分開的線程中調用監聽者方法。你必須在UI線程中更新顯示列表數據。

activity中以下兩個方法增加了用來搜尋的菜單，如此用戶才能手動的刷新列表：

```
@Override
public boolean onCreateOptionsMenu(Menu menu) {
    menu.add(0, 0, 0, R.string.search_lan)
        .setIcon(android.R.drawable.ic_menu_search);
    return true;
}

@Override
public boolean onOptionsItemSelected(MenuItem item) {
    if (item.getItemId() == 0 && upnpService != null) {
        upnpService.getRegistry().removeAllRemoteDevices();
        upnpService.getControlPoint().search();
    }
    return false;
}
```

最後，DeviceDisplay類是一個非常簡單的JavaBean，只提供一個toString()方法來呈現列表信息。通過修改此方法，你能夠顯示任何關於UPnP設備的信息：

```
class DeviceDisplay {
    Device device;

    public DeviceDisplay(Device device) {
        this.device = device;
    }

    public Device getDevice() {
        return device;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        DeviceDisplay that = (DeviceDisplay) o;
        return device.equals(that.device);
    }

    @Override
    public int hashCode() {
        return device.hashCode();
    }

    @Override
    public String toString() {
        // Display a little star while the device is being loaded
        return device.isFullyHydrated() ? device.getDisplayString() : device.getDisplayString() + " *";
    }
}
```

還有我們必須覆蓋相等操作，這樣我們纔可以用DeviceDisplay實例作爲便捷的處理，從列表中手動地移除和增加設備。

### 5.3. 優化服務行爲
UPnP服務運行時會消耗內存和CPU。儘管通常在一個正常的機器上沒有什麼問題，但在Android手持設備上就可能會有了。如果你禁用Cling UPnP服務的某些功能，或者設置暫停且在合適時恢復它，你可以留有更多的內存和電量。

#### 5.3.1. 調整註冊表維護
當服務運行時，後臺有好些東西在執行。首先，有一個服務的註冊表和其維護線程。如果你寫一個控制端，後臺註冊表維護者將會定期從遠程服務更新你對外的GENA訂閱。當沒有通知斷開網絡時，它也會到期並移除任何遠程服務。如果你正提供服務，你的設備通告將被註冊表維護者刷新，並在GENA訂閱沒及時更新時移除它。註冊表維護者爲了有效得防止UPnP網絡上的過時狀態，所以所有參與者會實時更新其他參與者的視圖等等。

默認情況下，註冊表維護者會每秒運行並檢查是否有事要做（當然，大多數情況下沒事做）。然而默認的Android配置有5秒的間隔休眠，所以這已經花費了更少的後臺CPU佔用時間 — 不過你的應用可能會暴露稍微過時的信息。在UpnpServiceConfiguration你可以通過覆蓋getRegistryMaintenanceIntervalMillis()進一步的調整設置。在Android上，你必須子類化服務實現來提供一個新的配置。

```
public class MyUpnpService extends AndroidUpnpServiceImpl {

    @Override
    protected AndroidUpnpServiceConfiguration createConfiguration(WifiManager wifiManager) {
        return new AndroidUpnpServiceConfiguration(wifiManager) {

            @Override
            public int getRegistryMaintenanceIntervalMillis() {
                return 7000;
            }

        };
    }
}
```

此時不要忘了在AndroidManifest.xml內配置MyUpnpService，而不是原先的實現。當在你的activities裏綁定服務時，也必須使用該類型。

#### 5.3.2. 暫停和恢復註冊表維護
另外一個更有效同時也不是很複雜的優化是，每當你的activites不再需要UPnP服務時，暫停和恢復註冊表。這通常發生在當activity不在前臺（暫停），甚至不再顯示（停止）時。默認情況下，activity狀態改變對UPnP服務沒有影響，除非你在activities生命週期的回調內綁定和解綁服務。

除了綁定和解綁服務，你也可以在activity onPause()或onStop()方法被調用時，通過調用Registry#pause()來暫停註冊表。之後，你可以通過Registry#resume()來恢復後臺服務，或同時用Registry#isPaused()檢查狀態。

請閱讀這些方法的Javadoc瞭解詳細信息，以及暫停註冊表維護對於設備、服務和GENA訂閱的意義。根據你的應用要做什麼，否則這種小的優化可能不值得處理這些效果。另一方面，你的應用應當能夠處理失敗的GENA訂閱續期，或者消失的遠程設備。

#### 5.3.3. 配置搜索
最有效的優化是UPnP設備有選擇性的搜索。儘管UPnP服務的網絡傳輸層在後臺會保持運行（線程正等待且socket被綁定），這個特性允許你有選擇且快速的丟棄搜索信息。

舉例來說，如果你正在寫一個控制端，且不通告你想要控制的服務（對其他設備沒興趣），那麼你可以丟棄所有接收的搜索信息。另一方面，如果你只提供設備和服務，所有搜索信息（除了你自身服務的搜索信息）可能都可以被丟棄，你對其他遠程設備和其服務一點都不會有興趣。

一旦UDP數據包內容可用，該搜索信息就會被Cling選擇並偷偷的丟棄，所以不需要進一步得解析和處理，同時CPU時間和內存消耗顯著得減少，即使當你在Android手持設備上後臺持續運行UPnP服務。

爲了配置你的控制端應用支持哪些服務，需要覆蓋前面章節展示的服務接口並提供一組ServiceType實例：

```
public class MyUpnpService extends AndroidUpnpServiceImpl {

    @Override
    protected AndroidUpnpServiceConfiguration createConfiguration(WifiManager wifiManager) {
        return new AndroidUpnpServiceConfiguration(wifiManager) {

            @Override
            public ServiceType[] getExclusiveServiceTypes() {
                return new ServiceType[] {
                        new UDAServiceType("SwitchPower")
                };
            }

        };
    }
}
```

這個配置將會忽略所有不通告chemas-upnp-org:SwitchPower:1的任何通告。這是我們控制端要處理的，不需要其他任何東西了。如果你返回一個空的數組（默認行爲），所有服務和設備將會發現以及沒有通告會被丟棄。

如果你正在寫一個控制端應用而不是服務應用，你可以讓getExclusiveServiceTypes()方法返回null。這將會完全禁用搜索，此時所有設備和服務的通告一接收就會被丟棄。