Aufrufen und Beenden von AIR-Anwendungen

AIR-Anwendungen werden durch die folgenden Aktionen des Benutzers (oder des Betriebssystems) aufgerufen:

• Start des Programms aus der Desktop-Shell.

• Verwendung der Anwendung als Befehl in einer Befehlszeilen-Shell.

• Öffnen eines Dateityps, dem die Anwendung als Standardanwendung zugeordnet wurde.

• (Mac OS X) Klicken auf das Anwendungssymbol in der Dock-Taskleiste (unabhängig davon, ob die Anwendung läuft oder nicht).

• Aufruf der Anwendung aus dem Installationsprogramm (nach Abschluss einer Neuinstallation oder nach Doppelklick auf der AIR-Datei einer bereits installierten Anwendung).

• Start einer Aktualisierung der AIR-Anwendung, wenn die installierte Version einen Hinweis eingeblendet hat, dass Aktualisierungen von der Anwendung selbst ausgeführt werden (durch Aufnahme der Deklaration <customUpdateUI>true</customUpdateUI> in die Anwendungsdeskriptordatei).

• (iOS) Empfängt eine Benachrichtigung vom Apple Push Notification service (APNs).

• Ruft die Anwendung über eine URL auf.

• Besuch einer Internetseite, die eine Flash-Badge oder eine Anwendung enthält, welche die Methode com.adobe.air.AIR launchApplication() aufrufen, die Identifikationsinformationen für die AIR-Anwendung enthält. (Der Anwendungsdeskriptor muss auch die Deklaration <allowBrowserInvocation>true</allowBrowserInvocation> enthalten, damit der Browser erfolgreich aufgerufen werden kann.)

Bei jedem Aufruf einer AIR-Anwendung löst AIR ein InvokeEvent-Objekt des Typs invoke durch das Singleton-Objekt NativeApplication aus. Um der Anwendung die für die Initialisierung und die Registrierung eines Ereignis-Listeners benötigte Zeit zu geben, werden invoke -Ereignisse in eine Warteschlange eingereiht und nicht verworfen. Sobald ein Listener registriert ist, werden die Ereignisse in der Warteschlange übermittelt.

Um invoke -Ereignisse zu erhalten, rufen Sie die Methode addEventListener() des NativeApplication-Objekts ( NativeApplication.nativeApplication) auf. Wenn sich ein Ereignis-Listener für ein invoke -Ereignis registriert, empfängt es auch alle invoke -Ereignisse, die vor der Registrierung aufgetreten sind. Nachdem der Aufruf an addEventListener() zurückgegeben wurde, werden die invoke -Ereignisse in der Warteliste in kurzen Abständen aufeinander folgend ausgelöst. Tritt während dieses Vorgangs ein neues invoke -Ereignis auf, kann es vor anderen Ereignissen in der Warteliste ausgelöst werden. Durch diese Einreihung von Ereignissen in eine Warteliste können Sie invoke -Ereignisse, die vor der Ausführung des Initialisierungscodes auftraten, verarbeiten. Denken Sie beim Hinzufügen eines Ereignis-Listeners zu einem späteren Zeitpunkt in der Ausführung (nach der Initialisierung der Anwendung) daran, dass dieser immer noch alle invoke -Ereignisse empfängt, die seit dem Starten der Anwendung aufgetreten sind.

Es wird nur eine Instanz der AIR-Anwendung geöffnet. Wird eine bereits laufende Anwendung erneut aufgerufen, löst AIR ein neues invoke -Ereignis an die bereits laufende Instanz aus. Es ist die Aufgabe der AIR-Anwendung, auf invoke -Ereignisse zu reagieren und die entsprechenden Schritte auszuführen (also zum Beispiel ein neues Dokumentfenster zu öffnen).

Ein InvokeEvent -Objekt enthält die Argumente, die an die Anwendung übergeben werden, sowie das Verzeichnis, aus dem die Anwendung aufgerufen wurde. Wenn die Anwendung aufgrund einer Dateityp-Verknüpfung aufgerufen wurde, dann wird der vollständige Pfad zur Datei in die Befehlszeilenargumente aufgenommen. Wurde die Anwendung wegen einer Anwendungsaktualisierung aufgerufen, wird der vollständige Pfad der AIR-Aktualisierungsdatei angegeben.

Wenn mehrere Dateien in einer Operation geöffnet werden, wird unter Mac OS X ein einzelnes InvokeEvent-Objekt ausgelöst. Jede Datei ist im arguments -Array enthalten. Unter Windows und Linux wird für jede Datei ein separates InvokeEvent-Objekt ausgelöst.

Die Anwendung kann invoke -Ereignisse durch die Registrierung eines Listeners über das NativeApplication-Objekt verarbeiten:

NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvokeEvent); 

Und durch die Definition eines Event-Listeners:

var arguments:Array; 
var currentDir:File; 
public function onInvokeEvent(invocation:InvokeEvent):void { 
    arguments = invocation.arguments; 
    currentDir = invocation.currentDirectory; 
} 

Die mit dem Aufruf einer AIR-Anwendung verknüpften Befehlszeilenargumente werden mit dem InvokeEvent-Objekt, das durch das NativeApplication-Objekt ausgelöst wurde, übermittelt. Die arguments -Eigenschaft von InvokeEvent enthält ein Array der Argumente, die beim Aufruf einer AIR-Anwendung vom Betriebssystem übergeben wurden. Enthalten diese Argumente relative Dateipfadangaben, können Sie die Pfadangaben in der Regel mit der Eigenschaft currentDirectory auflösen.

Die an eine AIR-Anwendung übergebenen Argumente werden wie durch Leerzeichen getrennte Strings behandelt, es sei denn, sie sind von doppelten Anführungszeichen eingeschlossen:

Die currentDirectory -Eigenschaft eines InvokeEvent-Objekts enthält ein File-Objekt, welches das Verzeichnis darstellt, aus dem die Anwendung gestartet wurde.

Wird eine Anwendung aufgerufen, weil eine Datei eines Typs geöffnet wird, der von der Anwendung registriert wurde, wird der native Pfad zur Datei in die Befehlszeilenargumente als String aufgenommen. (Ihre Anwendung ist für das Öffnen der Datei oder die Ausführung der geplanten Aktion an der Datei zuständig.) Wurde eine Anwendung so programmiert, dass Aktualisierungen automatisch durchgeführt werden (und nicht über die Standardbenutzeroberfläche für AIR-Aktualisierungen), wird der native Pfad zur AIR-Datei aufgenommen, wenn ein Benutzer auf eine AIR-Datei klickt, die eine Anwendung mit übereinstimmender Anwendungs-ID enthält.

Sie können mit der Methode resolve() des File-Objekts currentDirectory auf die Datei zugreifen:

if((invokeEvent.currentDirectory != null)&&(invokeEvent.arguments.length > 0)){ 
    dir = invokeEvent.currentDirectory; 
    fileToOpen = dir.resolvePath(invokeEvent.arguments[0]); 
}

Überprüfen Sie, ob ein Argument tatsächlich den Pfad zu einer Datei angibt.

Durch die Einstellung der startAtLogin -Eigenschaft von NativeApplication auf true kann die AIR-Anwendung so eingerichtet werden, dass sie automatisch gestartet wird, wenn sich der Benutzer anmeldet. Sobald die Einstellung vorgenommen wurde, wird die Anwendung bei jeder Benutzeranmeldung automatisch gestartet. Dieser automatische Anwendungsaufruf beim Anmelden erfolgt solange, bis die Einstellung auf false gesetzt wird, der Benutzer die Einstellung manuell über das Betriebssystem ändert oder die Anwendung deinstalliert wird. Hierbei handelt es sich um eine Laufzeiteinstellung. Die Einstellung gilt nur für den aktuellen Benutzer. Die Anwendung muss installiert sein, damit die startAtLogin -Eigenschaft erfolgreich auf true gesetzt werden kann. Wird die Eigenschaft eingestellt, obwohl keine Anwendung installiert ist (wenn sie z. B. mit ADL gestartet wird), wird ein Fehler ausgegeben.

Um festzustellen, ob eine Anwendung automatisch oder durch eine Benutzeraktion aufgerufen wurde, können Sie die reason -Eigenschaft des InvokeEvent-Objekts untersuchen. Wenn die Eigenschaft gleich InvokeEventReason.LOGIN ist, wurde die Anwendung automatisch gestartet. Bei anderen Aufrufpfaden ist die reason -Eigenschaft wie folgt eingestellt:

• InvokeEventReason.NOTIFICATION (nur iOS) - Die Anwendung wurde über APNs aufgerufen. Weitere Informationen zum APNs finden Sie unter Verwenden von Push-Benachrichtigungen .

• InvokeEventReason.OPEN_URL - Die Anwendung wurde von einer anderen Anwendung oder vom System aufgerufen.

• InvokeEventReason.Standard - Alle anderen Fälle.

Damit Sie Zugriff auf die reason -Eigenschaft haben, muss Ihre Anwendung AIR 1.5.1 oder höher als Ziel haben (indem Sie den entsprechenden Namespace-Wert in der Anwendungsdeskriptordatei angeben).

In der folgenden vereinfachten Anwendung wird die reason-Eigenschaft von InvokeEvent verwendet, um das Verhalten für ein Aufrufereignis zu bestimmen. Wenn die reason-Eigenschaft den Wert "login" hat, bleibt die Anwendung im Hintergrund. Andernfalls wird die Hauptanwendung sichtbar gemacht. Eine Anwendung, die dieses Muster verwendet, wird normalerweise bei der Anmeldung gestartet, damit Hintergrundverarbeitung oder Ereignisüberwachung stattfinden kann, und öffnet ein Fenster, wenn der Benutzer die Anwendung aufgerufen hat.

package { 
    import flash.desktop.InvokeEventReason; 
    import flash.desktop.NativeApplication; 
    import flash.display.Sprite; 
    import flash.events.InvokeEvent; 
 
    public class StartAtLogin extends Sprite 
    { 
        public function StartAtLogin() 
        { 
            try 
            { 
                NativeApplication.nativeApplication.startAtLogin = true; 
            } 
            catch ( e:Error ) 
            { 
                trace( "Cannot set startAtLogin:" + e.message ); 
            } 
             
            NativeApplication.nativeApplication.addEventListener( InvokeEvent.INVOKE, onInvoke ); 
        } 
                 
        private function onInvoke( event:InvokeEvent ):void 
        { 
            if( event.reason == InvokeEventReason.LOGIN ) 
            { 
                //do background processing... 
                trace( "Running in background..." ); 
            }             
            else 
            { 
                this.stage.nativeWindow.activate(); 
            } 
        } 
    } 
}

Mit der Funktion für den Browseraufruf kann eine Website eine installierte AIR-Anwendung vom Browser aus aufrufen. Das Aufrufen vom Browser ist nur zulässig, wenn die Anwendungsdeskriptordatei allowBrowserInvocation auf true setzt:

<allowBrowserInvocation>true</allowBrowserInvocation>

Wird die Anwendung über den Browser aufgerufen, löst das NativeApplication-Objekt der Anwendung ein BrowserInvokeEvent-Objekt aus.

Rufen Sie die Methode addEventListener() des NativeApplication-Objekts ( NativeApplication.nativeApplication ) in der AIR-Anwendung auf, um BrowserInvokeEvent-Ereignisse anzunehmen. Wird ein Ereignis-Listener für ein BrowserInvokeEvent-Ereignis registriert, empfängt er auch alle BrowserInvokeEvent-Ereignisse, die vor der Registrierung aufgetreten sind. Diese Ereignisse werden nach der Rückgabe des Aufrufs von addEventListener() ausgelöst, jedoch nicht unbedingt vor anderen BrowserInvokeEvent-Ereignissen, die nach der Registrierung empfangen wurden. Auf diese Weise können Sie BrowserInvokeEvent-Ereignisse verarbeiten, die aufgetreten sind, bevor Ihr Initialisierungscode ausgeführt wird (zum Beispiel, wenn die Anwendung ursprünglich vom Browser aufgerufen wurde). Denken Sie daran, dass beim Hinzufügen eines Ereignis-Listeners zu einem späteren Zeitpunkt in der Ausführung (nach der Initialisierung der Anwendung) dieser immer noch alle BrowserInvokeEvent-Ereignisse empfängt, die seit dem Starten der Anwendung aufgetreten sind.

Das BrowserInvokeEvent-Objekt hat folgende Eigenschaften:

Stellen Sie bei Verwendung der Browseraufrufsfunktion sicher, dass alle Sicherheitsüberlegungen beachtet wurden. Wenn eine Website eine AIR-Anwendung aufruft, kann sie über die Eigenschaft arguments des BrowserInvokeEvent-Objekts Daten senden. Seien Sie vorsichtig, wenn diese Daten bei sicherheitsrelevanten Vorgängen wie Dateien oder Code, die APIs laden, verwendet werden. Wie hoch das Risiko ist, hängt davon ab, was die Anwendung mit den Daten macht. Wenn Sie davon ausgehen, dass die Anwendung nur von einer bestimmten Website aufgerufen wird, sollte die Anwendung die Eigenschaft securityDomain des BrowserInvokeEvent-Objekts prüfen. Sie können auch zur Bedingung machen, dass die Website, die die Anwendung aufruft, HTTPs verwendet. Überprüfen Sie dies mit der Eigenschaft isHTTPS des BrowserInvokeEvent-Objekts.

Die Anwendung muss die übergebenen Daten prüfen. Geht die Anwendung zum Beispiel davon aus, dass URLs an eine spezifische Domäne übergeben werden, muss sie prüfen, dass die URLs tatsächlich auf diese Domäne verweisen. So kann vermieden werden, dass ein Angreifer die Anwendung dazu bringt, ihm sicherheitsrelevante Daten zu senden.

Anwendungen sollten keine BrowserInvokeEvent-Argumente verwenden, die auf lokale Ressourcen verweisen. So darf eine Anwendung keine File-Objekte erstellen, die auf einem Pfad basieren, der vom Browser übergeben wurde. Wird davon ausgegangen, das Remote-Pfadangaben vom Browser übergeben werden, muss die Anwendung sicherstellen, dass diese Pfadangaben nicht das Protokoll file:// anstelle eines Remote-Protokolls verwenden.

Eine Anwendung lässt sich am schnellsten mit einem Aufruf der exit()-Methode des NativeApplication-Objekts schließen. Dies funktioniert problemlos, wenn die Anwendung keine Daten speichern oder externe Ressourcen bereinigen muss. Durch den Aufruf von exit() werden alle Fenster geschlossen und die Anwendung wird beendet. Um jedoch den Fenstern und anderen Anwendungskomponenten die Möglichkeit zu geben, den Vorgang zu unterbrechen, z. B. um wichtige Daten zu speichern, lösen Sie vor dem Aufruf von exit() die entsprechenden Warnereignisse aus.

Es ist sinnvoll, das Verlassen einer Anwendung so zu gestalten, dass die Ausführung immer gleich abläuft, unabhängig davon, wie der Beendigungsvorgang gestartet wurde. Der Benutzer (oder das Betriebssystem) kann die Beendigung der Anwendung auf folgende Arten einleiten:

• Durch Schließen des letzten Anwendungsfensters, wenn NativeApplication.nativeApplication.autoExit auf true gesetzt ist.

• Durch Auswahl des Befehls „Schließen“ im Betriebssystem, wenn der Benutzer zum Beispiel den Befehl für das Schließen der Anwendung aus dem Standardmenü wählt. (Dies geschieht nur auf Mac-Betriebssystemen. Windows und Linux stellen keinen Befehl für das Schließen der Anwendung über die Benutzeroberfläche des Systems zur Verfügung.)

• Durch Herunterfahren des Computers.

Wenn der Befehl zum Schließen vom Betriebssystem über eines dieser Verfahren geleitet wird, löst NativeApplication ein exiting -Ereignis aus. Wird dieses exiting -Ereignis nicht von einem Listener unterbrochen, werden alle offenen Fenster geschlossen. Jedes Fenster löst ein closing - und dann ein close -Ereignis aus. Unterbricht eines der Fenster das closing -Ereignis, wird das Schließen der Anwendung gestoppt.

Wenn die Reihenfolge, in der die Fenster geschlossen werden, für die Anwendung wichtig ist, richten Sie einen Listener für das Ereignis exiting von NativeApplication ein und schließen Sie die Fenster eigenhändig in der richtigen Reihenfolge. Dies ist zum Beispiel erforderlich, wenn ein Dokumentfenster mit Werkzeugpaletten vorhanden ist. Es hat vielleicht unangenehme oder noch schlimmere Folgen, wenn das System die Paletten schließt, der Benutzer jedoch beschlossen hat, den Beendigungsvorgang zu unterbrechen, um Daten zu speichern. Unter Windows tritt das Ereignis exiting nur auf, nachdem das letzte Fenster geschlossen wurde (wenn die Eigenschaft autoExit des NativeApplication-Objekts auf true gesetzt wurde).

Stellen Sie bei allen Schließvorgängen, gleichgültig ob Sie über die Oberfläche des Betriebssystems, Menübefehle oder die Anwendungslogik ausgelöst wurden, sicher, dass der Vorgang gleich abläuft, indem Sie folgende Regeln beachten:

1. Lösen Sie ein exiting -Ereignis immer durch das NativeApplication-Objekt aus, bevor Sie im Anwendungscode exit() aufrufen, und prüfen Sie, dass andere Komponenten der Anwendung das Ereignis nicht abbrechen.

   public function applicationExit():void { 
       var exitingEvent:Event = new Event(Event.EXITING, false, true); 
       NativeApplication.nativeApplication.dispatchEvent(exitingEvent); 
       if (!exitingEvent.isDefaultPrevented()) { 
           NativeApplication.nativeApplication.exit(); 
       } 
   } 

2. Verwenden Sie einen Listener für das Ereignis exiting des NativeApplication.nativeApplication -Objekts und schließen Sie in der Prozedur alle Fenster (lösen Sie erst ein closing -Ereignis aus). Nehmen Sie die notwendigen Bereinigungen, zum Beispiel das Speichern von Anwendungsdaten oder Löschen temporärer Dateien vor, nachdem alle Fenster geschlossen wurden. Verwenden Sie während der Bereinigung nur synchrone Methoden, um sicherzustellen, dass diese abgeschlossen wurden, bevor die Anwendung beendet wird.

   Wenn es gleichgültig ist, in welcher Reihenfolge die Fenster geschlossen werden, können Sie mit einer Schleife durch das Array NativeApplication.nativeApplication.openedWindows vorgehen und die Fenster nacheinander schließen. Wenn die Reihenfolge wichtig ist , stellen Sie einen Mechanismus zur Verfügung, um die Fenster in der richtigen Reihenfolge zu schließen.

   private function onExiting(exitingEvent:Event):void { 
       var winClosingEvent:Event; 
       for each (var win:NativeWindow in NativeApplication.nativeApplication.openedWindows) { 
           winClosingEvent = new Event(Event.CLOSING,false,true); 
           win.dispatchEvent(winClosingEvent); 
           if (!winClosingEvent.isDefaultPrevented()) { 
               win.close(); 
           } else { 
               exitingEvent.preventDefault(); 
           } 
       } 
        
       if (!exitingEvent.isDefaultPrevented()) { 
           //perform cleanup 
       } 
   } 

3. Die Fenster sollten ihre eigene Bereinigung selbst handhaben, indem sie auf ihre jeweiligen closing -Ereignisse warten.

4. Verwenden Sie nur einen exiting -Listener in Ihrer Anwendung, da die zuvor aufgerufenen Prozeduren nicht wissen können, welche auf sie folgenden Prozeduren das exiting -Ereignis unterbrechen. (Auf die Reihenfolge der Ausführung sollte man sich nicht verlassen.)