Android Pluginentwicklung

Diese Anleitung erklärt, wie Plugins für die Android-App von TV-Browser geschrieben werden.

Grundlagen

Die Android-App von TV-Browser verwendet die AIDL um Plugins in die App einbinden zu können. Ein Plugin stellt dabei einen Service dar. Ein Plugin für die Android-App wird als eine Klasse geschrieben, die die abstrakte Service-Klasse erweitert.

Um ein Plugin schreiben zu können ist das AIDL-Paket der TV-Browser-App notwendig: TvBrowserAidlPluginPackage_v2.zip

Die Plugin-Schnittstelle ist unter der MIT-Lizenz lizenziert, kann also in jeder Art von Plugin verwendet werden.

Der Inhalt dieses Pakets muss in den src-Ordner der Plugin-App entpackt werden.

Beispiel:

package org.tvbrowser.myplugin

import android.app.Service;

public class MyPlugin extends Service {

  @Override
  public IBinder onBind(Intent intent) {
    ...
  }
  
  ...
}

Die Methode onBind muss einen IBinder vom Typ org.tvbrowser.devplugin.Plugin.Stub zurückgeben. Dieser IBinder stellt die eigentliche Plugin-Funktionalität zur Verfügung.

Ein Beispiel für einen Plugin-Service kann hier eingesehen werden.

Dieser Service muss nun noch in der AndroidManifest.xml unter <application> eingetragen werden.

Beispiel:

        <service
            android:name=".MyPlugin"
            android:label="1"
            android:permission="org.tvbrowser.permission.BIND_PLUGIN"
            android:exported="true">
            <intent-filter>
                <action android:name="org.tvbrowser.intent.action.PLUGIN"/>
                <category android:name="org.tvbrowser.intent.category.MyPlugin"/>
            </intent-filter>

        </service>

Für android:label muss die Version der verwendeten Plugin-Schnittstelle eingetragen werden, damit TV-Browser weiß mit welcher Version der Plugin-Schnittstelle auf das Plugin zugegriffen werden muss. Sollen nur Applikationen mit der Berechtigung org.tvbrowser.permission.BIND_PLUGIN auf den Plugin-Service zugreifen können (also in der Regel nur die TV-Browser-App), dann muss diese Berechtigung für den Service mit android:permission eingetragen werden. Damit TV-Browser auf den Service zugreifen kann, muss dieser mit android:exported="true" nach außen geöffnet sein.

Jeder Plugin-Service muss über einen Intent-Filter verfügen, der als action android:name den Wert org.tvbrowser.intent.action.PLUGIN setzt und für category android:name den Wert org.tvbrowser.intent.category.PLUGINSERVICECLASSNAME wobei PLUGINSERVICECLASSNAME durch den Klassennamen des Plugin-Service zu ersetzen ist. Dieser muss eineindeutig sein, es darf also kein Name sein, den ein anderes Plugin verwendet.

Über den Intent-Filter findet die TV-Browser-App die verfügbaren Plugins. Ein Plugin kann entweder eine eigenständige App mit nur einem Service sein, oder aber auch ein Service der innerhalb einer App, mit eigener Funktionalität, angeboten wird. Man kann natürlich auch mehrere Plugin-Service in einer App anbieten, TV-Browser wird diese dann als eigenständige Plugins behandeln.

Methoden aus org.tvbrowser.devplugin.Plugin

Die Funktionalität des Plugins wird durch die Methode aus org.tvbrowser.devplugin.Plugin zur Verfügung gestellt. Da es sich hierbei um ein Interface handelt, muss die Implementation von org.tvbrowser.devplugin.Plugin.Stub alle Methoden überschreiben. Man muss aber nicht auf jede dieser Methoden reagieren.

Allgemeine Informationen über das Plugin

Folgende allgemeine Informationen über ein Plugin, werden mit den folgenden Methode abgefragt:

• String getVersion() {
• String getName() {
• String getDescription() {
• String getAuthor() {
• String getLicense() {

Diese Methoden werden evtl. auch aufgerufen, wenn ein Plugin nicht aktiviert ist. Für alle diese Methode gilt, dass null zurückgegeben werden muss, falls die entsprechende Information, nicht gesetzt werden soll.

getVersion()

Mit der Methode getVersion() wird ein String zurückgegeben, der die Version des Plugins definiert. Wie diese Version aussieht bleibt dem Plugin-Entwickler überlassen.

getName()

Mit der Methode getName() wird ein String zurückgegeben, der den Namen des Plugins enthält. Es ist sinnvoll hier lokalisierte Namen zurückzugeben.

getDescription()

Mit der Methode getDescription() wird ein String zurückgegeben, der eine Beschreibung der Funktion des Plugins enthält. Es ist sinnvoll hier lokalisierte Beschreibungen zurückzugeben.

getAuthor()

Mit der Methode getAuthor() wird ein String zurückgegeben, der den Namen des Autors enthält.

getLicense()

Mit der Methode getLicense() wird ein String zurückgegeben, der die Lizenz des Plugins enthält. Es ist sinnvoll hier eine lokalisierte Lizenz zurückzugeben.

Aktivierung des Plugins

Bei der Aktivierung eines Plugins wird TV-Browser bestimmte Methoden aufrufen, diese Methoden werden ausschließlich bei der Aktivierung aufgerufen. Eine Aktivierung wird entweder ausgelöst, wenn TV-Browser gestartet wird und das Plugin in den Einstellungen von TV-Browser aktiviert ist oder wenn es in den Einstellungen von TV-Browser aktiviert wird. Die entsprechenden Methoden sind:

• void onActivation(PluginManager pluginManager) {
• void handleFirstKnownProgramId(long programId) {
• long[] getMarkedPrograms() {

void onActivation(PluginManager pluginManager)

Diese Methode wird aufgerufen, damit ein Plugin Aktionen ausführen kann, wie z.B. das Laden von Einstellungen. Der PluginManager bietet Methoden um auf TV-Browser zugreifen zu können, die Instanz sollte also aufbewahrt werden, falls das Plugin Anfragen an TV-Browser stellen können soll.

void handleFirstKnownProgramId(long programId)

Mit dieser Methode wird das Plugin über die kleinste bekannte Sendungs-ID informiert. Sollte das Plugin Informationen über Sendungen mit kleinerer Sendungs-ID gespeichert haben, dann sollten diese hier gelöscht werden, da sie nicht mehr aktuell sind, da Sendungen mit kleinerer Sendungs-ID nicht mehr existieren. Wird eine Sendungs-ID von -1 übergeben, bedeutet dies, dass TV-Browser keine Sendungen enthält und das Plugin alle gespeicherten Sendungs-IDs löschen sollte.

long[] getMarkedPrograms()

Hier kann ein Plugin ein Array mit Sendungs-IDs zurückgeben, die in TV-Browser markiert werden sollen. (ZUR ZEIT NOCH NICHT IN TV-BROWSER IMPLEMENTIERT)

Deaktivierung des Plugins

Wird das Plugin deaktiviert (weil der Nutzer es deaktiviert hat oder TV-Browser beendet wurde), dann wird die Methode void onDeactivation() { aufgerufen. Hier sollte das Plugin spätestens alle Einstellungen speichern. Es kann jedoch vorkommen, dass diese Methode nicht aufgerufen wird, weil das Plugin vom Android-System beendet wird. Daher ist zu empfehlen die Einstellungen immer dann zu speichern, wenn es notwendig ist.

Einstellungen des Plugins

Ein Plugin kann eigene Einstellungen anbieten, um die Funktionalität zu konfigurieren. Dazu existieren folgende Methoden:

• boolean hasPreferences() {
• void openPreferences(List<Channel> subscribedChannels) {

boolean hasPreferences()

Mit dieser Methode wird abgefragt, ob ein Plugin eigene Einstellungen anbietet. Es muss true zurückgegeben werden, wenn das Plugin eigene Einstellungen anbietet oder false zurückgegeben werden, falls nicht.

void openPreferences(List<Channel> subscribedChannels)

Hat ein Plugin bei der Abfrage durch boolean hasPreferences() true zurückgegeben, kann der Aufruf dieser Methode durch den Benutzer ausgelöst werden. Wie die Einstellungen auf Seite des Plugins konfiguriert sind ist nicht festgelegt. Es kann eine eigene simple Activity zur Einstellung oder, was der bevorzugte Weg ist, eine PreferencesActivity mit PreferencesHeaders verwendet werden. Der Methode werden als Parameter eine Liste mit den Sendern übergeben, die der Benutzer in der TV-Browser-App abonniert hat.

Funktionen zu Sendungen von TV-Browser

Die Funktionen für Sendungen von TV-Browser werden über ein Kontextmenü angeboten, Plugins können eigene Funktionen für das Kontextmenü von TV-Browser bereitstellen. Dazu werden die folgenden Methoden verwendet:

• PluginMenu[] getContextMenuActionsForProgram(Program program) {
• boolean onProgramContextMenuSelected(Program program, PluginMenu pluginMenu) {
• boolean isMarked(long programId) {
• byte[] getMarkIcon() {
• ReceiveTarget[] getAvailableProgramReceiveTargets() {
• void receivePrograms(Program[] programs, ReceiveTarget target) {

PluginMenu[] getContextMenuActionsForProgram(Program program)

Wenn der Benutzer das Kontextmenü zu einer Sendung auslöst, wird TV-Browser diese Methode für alle aktiven Plugins aufrufen. Das Plugin kann nun die Sendung program prüfen und für diese spezifische PluginMenus erstellen, die dann zurückgegeben werden. Das PluginMenu muss dafür eine eindeutige ID enthalten, die dieses PluginMenu identifiziert und den Titel des Eintrags für das Kontextmenu. Soll keine Funktion für die übergebene Sendung angeboten werden, muss null zurückgegeben werden.

boolean onProgramContextMenuSelected(Program program, PluginMenu pluginMenu)

Wurde ein Kontextmenueintrag des Plugins von Benutzer ausgewählt wird diese Methode aufgerufen, dieser wird die Sendung program und das ausgewählte Plugin-Menü pluginMenu übergeben. Das Plugin kann jetzt das Plugin-Menü auf die gewählte Funktion prüfen und diese ausführen. Soll die Sendung von TV-Browser markiert werden, muss true zurückgegeben werden, falls nicht, muss false zurückgegeben werden. Das Plugin sollte den Markierungsstatus für die ID der Sendung speichern.

boolean isMarked(long programId)

Wird evtl. aufgerufen um zu prüfen ob die Sendung mit der übergebenen ID vom Plugin markiert ist.

byte[] getMarkIcon()

Soll die Markierung einer Sendung mit einem Icon hervorgehoben werden, müssen hier die Daten dieses Icons als byte-Array zurückgegeben werden. (ZUR ZEIT NOCH NICHT IN TV-BROWSER IMPLEMENTIERT)

ReceiveTarget[] getAvailableProgramReceiveTargets()

(ZUR ZEIT NOCH NICHT IN TV-BROWSER IMPLEMENTIERT)

void receivePrograms(Program[] programs, ReceiveTarget target)

(ZUR ZEIT NOCH NICHT IN TV-BROWSER IMPLEMENTIERT)

Methoden aus org.tvbrowser.devplugin.PluginManager

Der PluginManager bietet Zugriff auf bestimmte Funktionen von TV-Browser, so können mit diesem z.B. Sendungen von TV-Browser abgefragt werden.

Program getProgramWithId(long programId)

Gibt die Sendung mit der passenden ID zurück oder null, falls keine Sendung zur übergebenen ID passt.

Program getProgramForChannelAndTime(int channelId, long startTimeInUTC)

Gibt die Sendung zurück, die auf dem Sender mit der übergebenen Sender-ID zur übergebenen Startzeit in Millisekunden seit 1970 in der UTC-Zeitzone beginnt oder null, falls keine Sendung zu den übergebenen Parametern passt.

List<Channel> getSubscribedChannels()

Gibt eine Liste mit allen, vom Benutzer abonnierten, Sendern zurück.

TvBrowserSettings getTvBrowserSettings()

Hiermit können bestimmte Einstellungen von TV-Browser abgefragt werden, die in der Klasse TvBrowserSettings zur Verfügung gestellt werden.

boolean markProgram(in Program program)()

Hiermit können Sendungen markiert werden, die Methode gibt true zurück, falls die Sendung erfolgreich markiert werden konnte oder bereits markiert ist. Wird false zurückgegeben, konnte die Sendung entweder nicht markiert werden oder existiert nicht mehr.

boolean unmarkProgram(in Program program)()

Hiermit können gesetzte Markierungen von Sendungen entfernt werden, die Methode gibt true zurück, falls die Markierung erfolgreich entfernt werden konnte oder andere Plugins die Sendung markieren. Wird false zurückgegeben, konnte die Markierung entweder nicht entfernt werden oder die Sendung existiert nicht mehr.

HINWEIS: Die Entfernung einer Markierung eines Plugins führt nur dann zur Entfernung der Markierung der Sendung, wenn keine Plugins die Sendung noch markieren.

Beispielcode

Der Quellcode eines vollständigen Plugins für die Android-App kann bei Github eingesehen werden:

https://github.com/ds10git/tvbrowsershareplugin/tree/master/TV-BrowserSharePlugin

Ein weiteres Beispiel findet sich ebenso bei Gitghub:

https://github.com/ds10git/tvbrowsersimplecalendarexportplugin/tree/master/TV-BrowserSimpleCalendarExportPlugin

Ein weiteres Beispiel, das unter der MIT-Lizenz steht, findet sich ebenso bei Gitghub:

https://github.com/ds10git/tvbrowsersimplemarkerplugin/tree/master/TV-BrowserSimpleMarkerPlugin

Der Quellcode von TV-BrowserSimpleMarkerPlugin steht unter der MIT-Lizenz, das bedeutet, dieser kann völlig frei verwendet werden, auch als Vorlage für andere Plugins.