|
|
Application launching and exit optionsThis section discusses options and considerations for launching an installed Adobe® AIR™ application, as well as options and considerations for closing a running application. Application invocationAn AIR application is invoked when the user (or the operating system):
Whenever an AIR application is invoked, AIR dispatches an InvokeEvent object of type invoke through the singleton NativeApplication object. To allow an application time to initialize itself and register an event listener, invoke events are queued instead of discarded. As soon as a listener is registered, all the queued events are delivered. Note: When an application is invoked using the browser
invocation feature, the NativeApplication object only dispatches
an invoke event if the application is not already
running. See Launching an installed AIR application from the browser.
To receive invoke events, call the addEventListener() method of the NativeApplication object (NativeApplication.nativeApplication). When an event listener registers for an invoke event, it also receives all invoke events that occurred before the registration. Queued invoke events are dispatched one at a time on a short interval after the call to addEventListener() returns. If a new invoke event occurs during this process, it may be dispatched before one or more of the queued events. This event queuing allows you to handle any invoke events that have occurred before your initialization code executes. Keep in mind that if you add an event listener later in execution (after application initialization), it will still receive all invoke events that have occurred since the application started. Only one instance of an AIR application is started. When an already running application is invoked again, AIR dispatches a new invoke event to the running instance. It is the responsibility of an AIR application to respond to an invoke event and take the appropriate action (such as opening a new document window). An InvokeEvent object contains any arguments passed to the application, as well as the directory from which the application has been invoked. If the application was invoked because of a file-type association, then the full path to the file is included in the command line arguments. Likewise, if the application was invoked because of an application update, the full path to the update AIR file is provided. Your application can handle invoke events by registering a listener with its NativeApplication object: NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvokeEvent); air.NativeApplication.nativeApplication.addEventListener(air.InvokeEvent.INVOKE, onInvokeEvent); And defining an event listener: var arguments;
var currentDir;
function onInvokeEvent(invocation) {
arguments = invocation.arguments;
currentDir = invocation.currentDirectory;
}
Capturing command line argumentsThe command line arguments associated with the invocation of an AIR application are delivered in the invoke event dispatched by the NativeApplication object. The InvokeEvent.arguments property contains an array of the arguments passed by the operating system when an AIR application is invoked. If the arguments contain relative file paths, you can typically resolve the paths using the currentDirectory property. The arguments passed to an AIR program are treated as white-space delimited strings, unless enclosed in double quotes:
The InvokeEvent.currentDirectory property contains a File object representing the directory from which the application was launched. When an application is invoked because a file of a type registered by the application is opened, the native path to the file is included in the command line arguments as a string. (Your application is responsible for opening or performing the intended operation on the file.) Likewise, when an application is programmed to update itself (rather than relying on the standard AIR update user interface), the native path to the AIR file is included when a user double-clicks an AIR file containing an application with a matching application ID. You can access the file using the resolve() method of the currentDirectory File object: if((invokeEvent.currentDirectory != null)&&(invokeEvent.arguments.length > 0)){
dir = invokeEvent.currentDirectory;
fileToOpen = dir.resolvePath(invokeEvent.arguments[0]);
}
You should also validate that an argument is indeed a path to a file. Example: Invocation event logThe following example demonstrates how to register listeners for and handle the invoke event. The example logs all the invocation events received and displays the current directory and command line arguments. Note: This example uses the AIRAliases.js
file, which you can find in the frameworks folder of the SDK.
<html>
<head>
<title>Invocation Event Log</title>
<script src="AIRAliases.js" />
<script type="text/javascript">
function appLoad(){
air.trace("Invocation Event Log.");
air.NativeApplication.nativeApplication.addEventListener(
air.InvokeEvent.INVOKE, onInvoke);
}
}
function onInvoke(invokeEvent){
logEvent("Invoke event received.");
if (invokeEvent.currentDirectory) {
logEvent("Current directory=" + invokeEvent.currentDirectory.nativePath);
} else {
logEvent("--no directory information available--");
}
if (invokeEvent.arguments.length > 0){
logEvent("Arguments: " + invokeEvent.arguments.toString());
} else {
logEvent("--no arguments--");
}
}
function logEvent(message){
var logger = document.getElementById('log');
var line = document.createElement('p');
line.innerHTML = message;
logger.appendChild(line);
air.trace(message);
}
window.unload = function() {
air.NativeApplication.nativeApplication.removeEventListener(
air.InvokeEvent.INVOKE, onInvoke);
}
</script>
</head>
<body onLoad="appLoad();">
<div id="log"/>
</body>
</html>
Launching on loginAn AIR application can be set to launch automatically when the current user logs in by setting NativeApplication.nativeApplication.startAtLogin=true. Once set, the application automatically starts whenever the user logs in. It continues to launch at start until the setting is changed to false, the user manually changes the setting through the operating system, or the application is uninstalled. Launching on login is a run-time setting. Note: The application does not launch when the computer
system starts. It launches when the user logs in. The setting only
applies to the current user. Also, the application must be installed
to successfully set the startAtLogin property to true. An
error is thrown if the property is set when an application is not
installed (such as when it is launched with ADL).
Browser invocationUsing the browser invocation feature, a website can launch an installed AIR application to be launched from the browser. Browser invocation is only permitted if the application descriptor file sets allowBrowserInvocation to true: <allowBrowserInvocation>true</allowBrowserInvocation> For more information on the application descriptor file, see Setting AIR application properties. When the application is invoked via the browser, the application’s NativeApplication object dispatches a BrowserInvokeEvent object. To receive BrowserInvokeEvent events, call the addEventListener() method of the NativeApplication object (NativeApplication.nativeApplication) in the AIR application. When an event listener registers for a BrowserInvokeEvent event, it also receives all BrowserInvokeEvent events that occurred before the registration. These events are dispatched after the call to addEventListener() returns, but not necessarily before other BrowserInvokeEvent events that might be received after registration. This allows you to handle BrowserInvokeEvent events that have occurred before your initialization code executes (such as when the application was initially invoked from the browser). Keep in mind that if you add an event listener later in execution (after application initialization) it still receives all BrowserInvokeEvent events that have occurred since the application started. The BrowserInvokeEvent object includes the following properties:
If you use the browser invocation feature, be sure to consider security implications. When a website launches an AIR application, it can send data via the arguments property of the BrowserInvokeEvent object. Be careful using this data in any sensitive operations, such as file or code loading APIs. The level of risk depends on what the application is doing with the data. If you expect only a specific website to invoke the application, the application should check the securityDomain property of the BrowserInvokeEvent object. You can also require the website invoking the application to use HTTPs, which you can verify by checking the isHTTPS property of the BrowserInvokeEvent object. The application should validate the data passed in. For example, if an application expects to be passed URLs to a specific domain, it should validate that the URLs really do point to that domain. This can prevent an attacker from tricking the application into sending it sensitive data. No application should use BrowserInvokeEvent arguments that might point to local resources. For example, an application should not create File objects based on a path passed from the browser. If remote paths are expected to be passed from the browser, the application should ensure that the paths do not use the file:// protocol instead of a remote protocol. For details on invoking an application from the browser, see Launching an installed AIR application from the browser. Application terminationThe quickest way to terminate an application is to call NativeApplication.nativeApplication.exit() and this works fine when your application has no data to save or resources to clean up. Calling exit() closes all windows and then terminates the application. However, to allow windows or other components of your application to interrupt the termination process, perhaps to save vital data, dispatch the proper warning events before calling exit(). Another consideration in gracefully shutting down an application is providing a single execution path, no matter how the shut-down process starts. The user (or operating system) can trigger application termination in the following ways:
When an exit command is mediated through the operating system by one of these routes, the NativeApplication dispatches an exiting event. If no listeners cancel the exiting event, any open windows are closed. Each window dispatches a closing and then a close event. If any of the windows cancel the closing event, the shut-down process stops. If the order of window closure is an issue for your application, listen for the exiting event from the NativeApplication and close the windows in the proper order yourself. This might be the case, for example, if you have a document window with tool palettes. It might be inconvenient, or worse, if the system closed the palettes, but the user decided to cancel the exit command to save some data. On Windows, the only time you will get the exiting event is after closing the last window (when the autoExit property of the NativeApplication object is set to true). To provide consistent behavior on all platforms, whether the exit sequence is initiated via operating system chrome, menu commands, or application logic, observe the following good practices for exiting the application:
|
