AIR-toepassingen oproepen en beëindigen

Een AIR-toepassing wordt opgeroepen wanneer de gebruiker (of het besturingssysteem):

• de toepassing start vanaf het bureaublad;

• de toepassing gebruikt als een opdracht op een opdrachtregel;

• een type bestand opent waarvoor de toepassing de standaardtoepassing is;

• (Mac OS X) op het toepassingspictogram in de dock-balk klikt (ongeacht of de toepassing is gestart);

• de toepassing start vanuit het installatieprogramma (aan het einde van een nieuw installatieproces of na het dubbelklikken op het AIR-bestand voor een geïnstalleerde toepassing);

• Begint een update van een AIR-toepassing wanneer de geïnstalleerde versie heeft aangegeven dat deze zelf toepassingsupdates verwerkt (door een declaratie <customUpdateUI>true</customUpdateUI> op te nemen in het descriptorbestand van de toepassing).

• (iOS) Ontvangt een bericht van de APN's (Apple Push Notification service).

• Roept de toepassing via een URL aan.

• een webpagina bezoekt waarop zich een Flash-badge of -toepassing bevindt die de methode com.adobe.air.AIR launchApplication() oproept met de identificatiegegevens voor de AIR-toepassing. (Oproepen vanuit de browser is alleen mogelijk als in de toepassingsdescriptor ook de declaratie <allowBrowserInvocation>true</allowBrowserInvocation> is opgenomen.)

Wanneer een AIR-toepassing wordt opgeroepen, wordt een InvokeEvent-object van het type invoke verzonden via het NativeApplication-singletonobject. Om een toepassing tijd te geven zichzelf te starten en een gebeurtenislistener te registreren, worden gebeurtenissen van het type invoke in de wachtrij geplaatst in plaats van verzonden. Zodra een listener is geregistreerd, worden alle gebeurtenissen in de wachtrij afgeleverd.

Roep de methode addEventListener() van het NativeApplication-object ( NativeApplication.nativeApplication ) op om gebeurtenissen van het type invoke te ontvangen. Wanneer een gebeurtenislistener een gebeurtenis van het type invoke heeft geregistreerd, ontvangt deze ook alle gebeurtenissen van het type invoke die vóór de registratie zijn opgetreden. Gebeurtenissen van het type invoke in de wachtrij worden een voor een, kort na elkaar verzonden nadat het oproepen van addEventListener() is uitgevoerd. Als er een nieuwe gebeurtenis van het type invoke optreedt tijdens dit proces, kan deze worden verzonden voordat een of meer gebeurtenissen in de wachtrij zijn verzonden. Omdat gebeurtenissen in een wachtrij worden opgeslagen, kunt u alle opgetreden gebeurtenissen van het type invoke verwerken voordat uw initialisatiecode wordt uitgevoerd. Denk eraan dat als u later tijdens de uitvoering (na het initialiseren van de toepassing) een gebeurtenislistener toevoegt, deze nog steeds alle gebeurtenissen van het type invoke ontvangt die zijn opgetreden sinds de toepassing is gestart.

Er wordt slechts één instantie van een AIR-toepassing gestart. Wanneer een toepassing die al is gestart opnieuw wordt opgeroepen, wordt een nieuwe gebeurtenis van het type invoke verzonden naar de gestarte instantie. Het is de verantwoordelijkheid van een AIR-toepassing om te reageren op een gebeurtenis van het type invoke en de juiste actie uit te voeren (zoals het openen van een nieuw documentvenster).

Een InvokeEvent -object bevat alle argumenten die aan de toepassing worden doorgegeven en ook de map van waaruit de toepassing is opgeroepen. Als de toepassing is opgeroepen via een gekoppeld bestandstype, wordt het volledige pad naar het bestand opgenomen in de opdrachtregelargumenten. Als de toepassing is opgeroepen via een toepassingsupdate, wordt het volledige pad naar het AIR-updatebestand opgenomen.

Wanneer meer bestanden in één bewerking worden geopend, wordt een enkel InvokeEvent-object verzonden op Mac OS X. Elk bestand is opgenomen in de array arguments . In Windows en Linux wordt voor elk bestand een afzonderlijk InvokeEvent-object verzonden.

Uw toepassing kan gebeurtenissen van het type invoke verwerken door een listener te registreren met het NativeApplication-object:

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

En een gebeurtenislistener te definiëren:

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

De opdrachtregelargumenten die gekoppeld zijn aan de aanroeping van een AIR-toepassing worden geleverd in het InvokeEvent-object dat wordt verzonden door het NativeApplication-object. De eigenschap InvokeEvent- arguments bevat een array van de argumenten die door het besturingssysteem worden doorgegeven wanneer er een AIR-toepassing wordt aangeroepen. Als de argumenten relatieve bestandspaden bevatten, kunt u de paden gewoonlijk omzetten met de eigenschap currentDirectory .

De argumenten die aan een AIR-programma worden doorgegeven, worden behandeld als met spaties gescheiden tekenreeksen, tenzij ze tussen dubbele aanhalingstekens staan:

De eigenschap currentDirectory van een InvokeEvent-object bevat een Bestandsobject die de map weergeeft waarin een toepassing werd gestart.

Wanneer een toepassing wordt opgeroepen omdat een bestandstype wordt geopend dat door de toepassing is geregistreerd, wordt het oorspronkelijke pad naar het bestand als een tekenreeks opgenomen in de opdrachtregelargumenten. (Uw toepassing is verantwoordelijk voor het openen van het bestand of het uitvoeren van de gewenste bewerking.) Wanneer een toepassing is geprogrammeerd om zichzelf te updaten (en niet afhankelijk is van de standaard gebruikersinterface voor AIR-updates), wordt het oorspronkelijke pad naar het AIR-bestand opgenomen wanneer een gebruiker dubbelklikt op een AIR-bestand dat een toepassing met een overeenkomende toepassings-id bevat.

U kunt het bestand openen met de methode resolve() van het File-object currentDirectory :

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

U moet ook controleren of een argument inderdaad een pad naar een bestand is.

Een AIR-toepassing kan worden ingesteld zodat deze automatisch opstart wanneer de huidige gebruiker zich aanmeldt door de eigenschap NativeApplication startAtLogin in te stellen op true . Wanneer dit is ingesteld, wordt de toepassing automatisch gestart wanneer de gebruiker zich aanmeldt. De toepassing wordt altijd gestart bij het aanmelden, totdat de instelling wordt gewijzigd in false , als de gebruiker de instelling handmatig via het besturingssysteem wijzigt of wanneer de toepassing wordt verwijderd. Starten bij aanmelden is een runtime-instelling. De instelling geldt alleen voor de huidige gebruiker. De toepassing moet zijn geïnstalleerd om de eigenschap startAtLogin op true in te kunnen stellen. Er wordt een fout gemeld als de eigenschap wordt ingesteld wanneer een toepassing niet is geïnstalleerd (bijvoorbeeld als deze wordt gestart met ADL).

Om te bepalen of een toepassing automatisch is gestart of als gevolg van een gebruikersactie, kunt u de eigenschap reason van het InvokeEvent-object bekijken. Als de eigenschap gelijk is aan InvokeEventReason.LOGIN , wordt de toepassing automatisch gestart. Voor andere aanroeppaden is de eigenschap reason als volgt ingesteld:

• InvokeEventReason.NOTIFICATION (iOS only) - De toepassing werd aangeroepen via APN's. Zie Pushberichten gebruiken voor meer informatie over APN's.

• InvokeEventReason.OPEN_URL - De toepassing werd aangeroepen door een andere toepassing op door het systeem.

• InvokeEventReason.Standard - Alle overige gevallen.

Om de eigenschap reason te openen, moet uw toepassing gericht zijn op AIR 1.5.1 of hoger (door de correcte naamruimtewaarde in te stellen in het descriptorbestand van de toepassing).

De volgende, vereenvoudigde toepassing gebruikt de redeneigenschap InvokeEvent om het gedrag te beslissen wanneer er een aanroepgebeurtenis plaatsvindt. Als de redeneigenschap 'login' is, blijft de toepassing op de achtergrond. Anders wordt de hoofdtoepassing zichtbaar. Een toepassing die dit patroon gebruikt, start over het algemeen bij de aanmelding, zodat deze achtergrondverwerking of gebeurteniscontrole kan uitvoeren en er een venster wordt geopend na een aanroepgebeurtenis die door een gebruiker is geactiveerd.

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(); 
            } 
        } 
    } 
}

Met de browseroproepfunctie kan een website een geïnstalleerde AIR-toepassing starten vanaf een browser. Oproepen vanuit de browser is alleen toegestaan als allowBrowserInvocation op true is ingesteld in het descriptorbestand van de toepassing:

<allowBrowserInvocation>true</allowBrowserInvocation>

Wanneer de toepassing wordt opgeroepen vanuit de browser, verzendt het NativeApplication-object van de toepassing een BrowserInvokeEvent-object.

Als u BrowserInvokeEvent-gebeurtenissen wilt ontvangen, roept u de methode addEventListener() van het NativeApplication-object ( NativeApplication.nativeApplication ) op in de AIR-toepassing. Wanneer een gebeurtenislistener een BrowserInvokeEvent-gebeurtenis heeft geregistreerd, ontvangt deze ook alle BrowserInvokeEvent-gebeurtenissen die vóór de registratie zijn opgetreden. Deze gebeurtenissen worden verzonden nadat addEventListener() is uitgevoerd, maar niet noodzakelijkerwijs vóór andere BrowserInvokeEvent-gebeurtenissen die na de registratie zijn ontvangen. Zo kunt u BrowserInvokeEvent-gebeurtenissen verwerken die zijn opgetreden voordat uw initialisatiecode is uitgevoerd (bijvoorbeeld wanneer de toepassing is opgeroepen vanuit de browser). Denk eraan dat als u later tijdens de uitvoering (na het initialiseren van de toepassing) een gebeurtenislistener toevoegt, deze nog steeds alle BrowserInvokeEvent-gebeurtenissen ontvangt die zijn opgetreden sinds de toepassing is gestart.

Het BrowserInvokeEvent-object bevat de volgende eigenschappen:

Als u de browseroproepfunctie gebruikt, moet u rekening houden met de gevolgen voor de beveiliging. Wanneer een website een AIR-toepassing start, kan deze via de eigenschap arguments van het BrowserInvokeEvent-object gegevens verzenden. Wees voorzichtig wanneer u deze gegevens gebruikt bij gevoelige bewerkingen, zoals API's die bestanden of code laden. Het risico is afhankelijk van wat de toepassing met de gegevens doet. Als u verwacht dat alleen een specifieke website de toepassing aanroept, moet de toepassing de eigenschap securityDomain of het BrowserInvokeEvent-object controleren. U kunt er ook voor zorgen dat de website die de toepassing oproept HTTP's gebruikt, die u kunt controleren door de eigenschap isHTTPS van het BrowserInvokeEvent-object te bekijken.

De toepassing moet de doorgegeven gegevens valideren. Als een toepassing bijvoorbeeld verwacht dat URL's naar een bepaald domein worden doorgegeven, moet de toepassing controleren of de URL's echt naar dat domein verwijzen. Dit kan voorkomen dat een aanvaller de toepassing ertoe overhaalt vertrouwelijke gegevens te verzenden.

Een toepassing moet geen BrowserInvokeEvent-argumenten gebruiken die naar lokale resources verwijzen. Een toepassing moet bijvoorbeeld geen File-objecten maken die zijn gebaseerd op een pad dat vanuit de browser is doorgegeven. Als wordt verwacht dat externe paden vanuit de browser worden doorgegeven, moet de toepassing ervoor zorgen dat in de paden niet het protocol file:// wordt gebruikt in plaats van een extern protocol.

De snelste manier om een toepassing te sluiten is het aanroepen van de NativeApplication exit()-methode. Dit werkt prima wanneer uw toepassing geen gegevens heeft om op te slaan of externe resources om op te schonen. Als u exit() oproept, worden alle vensters gesloten en wordt de toepassing beëindigd. Als vensters of andere componenten van de toepassing echter het beëindigingsproces mogen onderbreken, bijvoorbeeld om essentiële gegevens op te slaan, moet u de juiste waarschuwingsgebeurtenissen verzenden voordat u exit() oproept.

Een toepassing kan ook netjes worden afgesloten door een enkel uitvoeringspad op te geven dat onafhankelijk is van de manier waarop het afsluitingsproces is gestart. De gebruiker (of het besturingssysteem) kan het beëindigen van de toepassing op de volgende manieren activeren:

• door het laatste toepassingsvenster te sluiten wanneer NativeApplication.nativeApplication.autoExit op true is ingesteld;

• door de opdracht Afsluiten van de toepassing te selecteren vanuit het besturingssysteem, bijvoorbeeld wanneer de gebruiker de opdracht Afsluiten kiest in het standaardmenu. (Dit gebeurt alleen in Mac OS. Windows en Linux beschikken niet over een opdracht om de toepassing af te sluiten via de systeeminterface.)

• door de computer af te sluiten.

Wanneer op een van deze manieren een afsluitopdracht wordt overgebracht via het besturingssysteem, verzendt NativeApplication de gebeurtenis exiting . Als geen enkele listener de gebeurtenis exiting annuleert, worden alle geopende vensters gesloten. Elk venster verzendt de gebeurtenis closing en de gebeurtenis close . Als een van de vensters de gebeurtenis closing annuleert, stopt het afsluitproces.

Als de volgorde waarin vensters worden gesloten belangrijk is voor de toepassing, luistert u naar de gebeurtenis exiting van NativeApplication en sluit u de vensters zelf in de juiste volgorde. Dit kan nodig zijn wanneer u bijvoorbeeld een documentvenster met gereedschappaletten hebt. Het kan onhandig zijn, of erger, als het systeem de paletten heeft gesloten, maar de gebruiker besloot om de afsluitopdracht te annuleren om gegevens op te slaan. In Windows ontvangt u de gebeurtenis exiting alleen nadat het laatste venster is gesloten (wanneer de eigenschap autoExit van het NativeApplication-object is ingesteld op true ).

Houd u aan de volgende aanbevolen procedures voor het afsluiten van een toepassing, zodat het gedrag consistent is voor alle platformen, of de afsluitopdracht nu wordt geactiveerd via de interface van het besturingssysteem, menuopdrachten of logica in de toepassing:

1. Verzend altijd de gebeurtenis exiting via het NativeApplication-object voordat exit() wordt opgeroepen in de code van de toepassing en controleer of geen andere component van de toepassing de gebeurtenis annuleert.

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

2. Luister naar de gebeurtenis exiting van de toepassing vanuit het NativeApplication.nativeApplication -object en sluit in de handler alle vensters (verzend eerst de gebeurtenis closing ). Voer alle benodigde opruimtaken uit, zoals het opslaan van toepassingsgegevens of het verwijderen van tijdelijke bestanden, nadat alle vensters zijn gesloten. Gebruik tijdens het opruimen alleen synchrone methoden, zodat u zeker weet dat deze zijn voltooid voordat de toepassing wordt afgesloten.

   Als de volgorde waarin de vensters worden gesloten niet belangrijk is, kunt u de array NativeApplication.nativeApplication.openedWindows doorlopen en elk venster achtereenvolgens sluiten. Als de volgorde wel belangrijk is, moet u zorgen dat de vensters in de juiste volgorde worden gesloten.

   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. Vensters moeten altijd hun eigen opruimtaken uitvoeren door te luisteren naar hun eigen closing -gebeurtenissen.

4. Gebruik slechts één exiting -listener in uw toepassing, omdat handlers die eerder zijn opgeroepen niet kunnen weten of volgende handlers de gebeurtenis exiting zullen annuleren (en het zou onverstandig zijn om te vertrouwen op de volgorde van uitvoering).