5. Targetting Applications

The Application class

The Application class represents an application to which Apple events will be sent. Its constructor allows applications to be identified in one of four ways: by full path, by eppc URL, by custom AEAddressDesc, or the host application if no other value is given. Its main method, #event, is used to construct the Apple events to send. Several utility methods are also provided.

Application -- the target application

    Class methods:

        process_exists_for_path?(path) -- Does a local process launched
                from the specified application file exist?
            path : string -- application's path, e.g. '/Applications/iCal.app'
            Result : boolean -- Note: if path is invalid, an AE::MacOSError
                    is raised.

        process_exists_for_pid?(pid) -- Is there a local application process
                with the given Unix process id?
            pid : integer
            Result : boolean
		
        process_exists_for_url?(url) -- Does an application process specified
                by the given eppc:// URL exist?
            url : string -- url for remote process
                    (e.g. 'eppc://user:pass@0.0.0.1/TextEdit')
            Result : boolean -- Returns false if process doesn't exist, or if
                    access isn't allowed.

        process_exists_for_desc?(desc) -- Does an application process specified
                by the given AEAddressDesc exist?
            desc : AE::AEDesc -- AEAddressDesc for application
            Result : boolean -- Returns false if process doesn't exist, or if
                    access isn't allowed.

        launch(path) -- launch an application in background if not
                already running, and send it a 'ascrnoop' event
            path : string -- application's path, e.g. '/Applications/iCal.app'
    
    Constructors:

        by_path(path)
            path : string -- full path to local application
                    (e.g. '/Applications/TextEdit.app')

        by_pid(pid)
            pid : integer -- Unix process id

        by_url(url)
            url : string -- url for remote process
                    (e.g. 'eppc://user:pass@0.0.0.1/TextEdit')

        by_desc(desc)
            desc : AEDesc -- AEAddressDesc for application

        current -- the host process

    Methods:

        event(...) -- construct an Apple event (see next chapter for details)

        begin_transaction(session=nil) -- begin a new transaction;
                all Events constructed after begin_transaction is
                called will belong to the same transaction until
                end_transaction or abort_transaction is called
            session : anything -- optional value identifying the 
                    specific session (where supported)

        end_transaction -- end the current transaction

        abort_transaction -- abort the current transaction

        reconnect -- Make sure this Application object has a valid
                AEAddressDesc for the target application, relaunching
                the target application if it's not currently running.
                (Note: this only works for Application objects created
                via the by_path constructor.)

Creating Application objects

When targetting a local application by path, the full path to the application (or application bundle) must be given, including a .app suffix if present. Note that aem identifies local applications by process serial number for reliability. If the target application is not already running when a new Application instance is created, it will be started automatically so that a PSN can be acquired. If the application can't be launched for some reason (e.g. if it's in the Trash), an AEM::CantLaunchApplicationError error will be raised.

If the by_url constructor is used, its url argument should be an eppc URL string. Aem will pack this as an AEDesc of typeApplicationURL. The target machine must have Remote Apple Events enabled in its Sharing preferences.

Clients can also supply their own AEAddressDesc if they prefer. This should be an AE::AEDesc of one of the following types:

KAE::TypeApplicationBundleID
KAE::TypeApplicationURL
KAE::TypeApplSignature
KAE::TypeKernelProcessID
KAE::TypeMachPort
KAE::TypeProcessSerialNumber

See the Apple Event Manager documentation for more information on these addressing modes.

Launching applications

Application.launch is a class method attached to the Application class for convenience. It allows a non-running application to be launched without sending it the 'run' event (aevtoapp) normally sent to applications - a 'no-op' event (ascrnoop) is sent instead. It should be called before creating an Application object for the target application, otherwise the application will be launched as normal.

Transactions

The #begin_transaction and #end_transaction methods are used to start and stop transaction sessions for applications that support this. All events created while a transaction session is active will be identified as part of that transaction.

Note that during a transaction, sending the application an event not created during that transaction will cause an error. Similarly, sending the application an event created during a transaction after that transaction has ended will cause an error.

The #end_transaction method must be called to close both successful and failed transactions on completion. If a transaction session is accidentally left open, aem will attempt to close it when the Application object is garbage-collected, although this cannot be guaranteed to succeed.

Reconnecting to local applications

Because local applications are identified by process serial number, an existing Application object created using the by_path constructor will no longer hold a valid AEAddressDesc if the target application subsequently quits. Sending events to an invalid address will cause a CommandError -600 ("application isn't running") or -609 ("connection is invalid") to be raised.

The process_exists_for_path? class method can be used to check if a local application is running or not, given its full path.

Calling the #reconnect method will create a new AEAddressDesc for an existing Application object that was originally created via the by_path constructor. If the application is not running at the time, it will be started automatically.

Note that only Event instances created after #reconnect is called will receive the new AEAddressDesc. Any Event instances created before reconnect is called will still contain the old AEAddressDesc.