manpagez: man pages & more
man Mac::AppleEvents::Simple(3)
Home | html | info | man
Simple(3)             User Contributed Perl Documentation            Simple(3)




NAME

       Mac::AppleEvents::Simple - Simple access to Mac::AppleEvents


SYNOPSIS

               #!perl -w
               use Mac::AppleEvents::Simple;
               use Mac::Files;  # for NewAliasMinimal
               $alias = NewAliasMinimal(scalar MacPerl::Volumes);
               do_event(qw/aevt odoc MACS/, "'----':alis(\@\@)", $alias);

               # [...]
               use Mac::Errors '$MacError';
               use Mac::AppleEvents;  # for kAENoReply
               $evt = build_event(qw/aevt odoc MACS/, "'----':alis(\@\@)", $alias);
               die "There was a problem: $MacError" if $^E;
               $evt->send_event(kAENoReply);
               die "There was a problem: $MacError" if $^E;


DESCRIPTION

       Requirements

       For MacPerl 5.2.0r4, you should have the latest cpan-mac distribution:

               http://sourceforge.net/projects/cpan-mac/

       For MacPerl 5.6.1 and up, everything you need is included.

       For Mac OS X, you should have the latest Mac::Carbon:

               http://sourceforge.net/projects/macperl/

       Also note the differences between MacPerl and perl on Mac OS X listed
       in Mac::Carbon, especially regarding $^E.

       Overview

       This is just a simple way to do Apple Events.  The example above was
       previously done as:

               #!perl -w
               use Mac::AppleEvents;
               use Mac::Files;
               $alias = NewAliasMinimal(scalar MacPerl::Volumes);
               $evt = AEBuildAppleEvent(qw/aevt odoc sign MACS 0 0/,
                       "'----':alis(\@\@)", $alias) or die $MacError;
               $rep = AESend($evt, kAEWaitReply) or die $MacError;
               AEDisposeDesc($rep);
               AEDisposeDesc($evt);

       The building, sending, and disposing is done automatically.  The
       function returns an object containing the parameters.  (Previously, the
       "AEPrint" results of "AEBuildAppleEvent" and "AESend" would be in
       "$event->{EVENT}" "$event->{REPLY}", but this was wasting way too much
       memory, as some of these things got big; you can call
       "AEPrint($event->{REP})" yourself).

       Also, the Mac::AppleEvents::Simple method will launch the application
       for you, whereas the Mac::AppleEvents method requires the program to be
       running already (or launched via Mac::Processes or Mac::Apps::Launch).
       Launching works only when the target is an app signature or bundle ID.

       The raw AEDesc forms are in "$event->{EVT}" and "$event->{REP}".  So if
       I also "use"'d the Mac::AppleEvents module (or got the symbols via "use
       Mac::AppleEvents::Simple ':all'"), I could extract the direct object
       from the reply like this:

               $dobj = AEPrint(AEGetParamDesc($event->{REP}, keyDirectObject));

       An easier way to get the direct object data, though, is with the "get"
       method, described below.

       The sending of the event uses as its defaults ("kAEWaitReply",
       "kAENormalPriority", "kNoTimeout").  To use different parameters, use
       "build_event" with "send_event".

       Setting "$Mac::AppleEvents::Simple::SWITCH = 1" forces the target app
       to go to the front on sending an event to it.  This works only when the
       target is an app signature or bundle ID.

       Sending an event with "send_event" or "do_event" will check for errors
       automatically, and if there is an error and
       $Mac::AppleEvents::Simple::WARN is true, a warning will be sent to
       "STDERR".  You can also check $^E after each call, or check the values
       of "$event->{ERRNO}" and "$event->{ERROR}".

       If the event reply itself contains a "errn" or "errs" parameter, these
       will also be placed in "$event->{ERRNO}" and "$event->{ERROR}" and $^E
       as appropriate.

       You may decide to roll your own error catching system, too.  In this
       example, the error is returned in the direct object parameter.

               my $event = do_event( ... );
               die $MacError if $^E;  # catch execution errors
               my_warn_for_this_app($event);  # catch AE reply errors

               sub my_warn_for_this_app {
                       my $event = shift;
                       my $error = AEGetParamDesc($event->{REP}, keyDirectObject);
                       if ($error) {
                               my $err = $error->get;
                               if ($err =~ /^-\d+$/ && $^W) {
                                       warn "Application error: $err";
                               }
                               AEDisposeDesc($error);
                       }
               }


FUNCTIONS

       [$EVENT =] do_event(CLASSID, EVENTID, TARGET, FORMAT, PARAMETERS ...)
           The first three parameters are required.  The FORMAT and PARAMETERS
           are documented elsewhere; see Mac::AppleEvents and macperlcat.

           TARGET may be a four-character app ID or a hashref containing
           ADDRESSTYPE and ADDRESS.  Examples:

                   { typeApplSignature()       => '...'            }  # default
                   { typeTargetID()            => pack_ppc(...)    }  # Mac OS only
                   { typeTargetID()            => pack_eppc(...)   }  # Mac OS only
                   { typeApplicationURL()      => pack_eppc_x(...) }  # Mac OS X
                   { typeProcessSerialNumber() => pack_psn(...)    }
                   { typeKernelProcessID()     => pack_pid(...)    }  # Mac OS X only
                   { typeBundleID()            => '...'            }  # Mac OS X only

           See the pack functions below for details.

       $EVENT = build_event(CLASSID, EVENTID, TARGET, FORMAT, PARAMETERS ...)
           This is for delayed execution of the event, or to build an event
           that will be sent specially with "send_event".  Build it with
           "build_event", and then send it with "send_event" method.  The
           parameters are the same as "do_event".

       $EVENT->send_event([GETREPLY, PRIORITY, TIMEOUT]);
           For sending events differently than the defaults, which are
           "kAEWaitReply", "kAENormalPriority", and "kNoTimeout", or for re-
           sending an event.  The parameters are sticky for a given event, so:

                   $evt->send_event(kAENoReply);
                   $evt->send_event;  # kAENoReply is still used

       $EVENT->handle_event(CLASSID, EVENTID, CODE [, SYS]);
           Note: Untested under Mac OS X.  Testing and patches welcome.

           Sets up an event handler by passing CLASSID and EVENTID of the
           event to be handled.  If SYS is true, then it sets up a system-wide
           event handler, instead of an application-wide event handler.

           CODE is a code reference that will be passed three parameters: a
           Mac::AppleEvents::Simple object, the CLASSID, and the EVENTID.  The
           object will work similarly to a regular object.  The REP and EVT
           parameters are switched (that is, you get the event in the REP
           parameter, and the reply to be sent is in the EVT parameter).  This
           is so the other methods will work just fine, and since you will
           only be using actual methods on the object and not accessing its
           data directly, it shouldn't matter, right?

           The other difference is that there is an additional data member in
           the object, called HANDLER, which is for properly disposing of the
           handler when you are done with it.  Your event handler should get
           disposed of for you in the background.

           An example:

                   my @data_out;
                   handle_event('CLAS', 'EVNT', \&handler);
                   sub handler {
                           my($evt) = @_;
                           my @data = $evt->get;
                           push @data_out, [$data[0], $data[9]] if $data[0] && $data[9];
                   }

                   while (1) {
                           if (my $data = shift @data_out) {
                                   print "woohoo: @$data\n";
                           }
                   }

       $EVENT->data([KEY])
       $EVENT->get([KEY])
       data(DESC[, KEY])
       get(DESC[, KEY])
           Similar to "get" and "data" from the Mac::AppleEvents module.  Get
           data from a Mac::AppleEvents::Simple object for a given key
           ("keyDirectObject" is the default).  Can also be called as a
           function, where an AEDesc object is passed as the first parameter.

           For "data", if the descriptor in KEY is an AE list, then a list of
           the descriptors in the list will be returned.  In scalar context,
           only the first element will be returned.

           On the other hand, "get" will return a nested data structure, where
           all nested AE lists will be converted to perl array references, and
           all nested AE records will be converted to perl hash references.
           In scalar context, only the first element of the base list will be
           returned for AE lists.

           Also, "get" will attempt to convert other data into a more usable
           form (such as resolving aliases into paths).

       pack_ppc(ID, NAME, SERVER[, ZONE])
           Note: Not implemented under Mac OS X.

           Packs a PPC record suitable for using in "build_event" and
           "do_event".  Accepts the 4-character ID of the target app, the name
           of the app as it may appear in the PPC Chooser, and the server and
           zone it is on.  If not supplied, zone is assumed to be '*'.

       pack_eppc(ID, NAME, HOST)
           Note: Not implemented under Mac OS X (see pack_eppc_x).

           Packs an EPPC record suitable for using in "build_event" and
           "do_event".  Accepts the 4-character ID of the target app, the name
           of the app as it may appear in the PPC Chooser, and the hostname of
           the machine it is on.  Requires Mac OS 9.

       pack_eppc_x(NAME, HOST [, UID, PID, USERNAME, PASSWORD])
           Note: Not implemented under Mac OS (see pack_eppc).

           Packs an EPPC record suitable for using in "build_event" and
           "do_event" under Mac OS X.  Accepts the name of the app, the
           hostname of the machine it is on, and, optionally, the uid of the
           owner of the app, the process ID of the app, and the
           username/password to connect with.  Note that it is normally
           preferable to allow the Keychain to handle the username/password
           (enter it the first time it is asked for, and select "Add to
           Keychain?").  Requires Mac OS X.

           Note: the UID/PID stuff doesn't actually work for me, in my tests.
           Huh.

           Note: the eppc port (for both Mac OS and Mac OS X) is 3031.

       pack_psn(PSN)
           Simply packs a PSN into a double long.

       pack_pid(PID)
           Note: Mac OS X only.

           Converts a PID into a PSN, then calls "pack_psn".


EXPORT

       Exports functions "do_event", "build_event", "handle_event",
       "pack_ppc", "pack_eppc", "pack_psn", "pack_pid".  All the symbols from
       Mac::AppleEvents are available in @EXPORT_OK and through the "all"
       export tag.


AUTHOR

       Chris Nandor <pudge@pobox.com>, http://pudge.net/

       Copyright (c) 1998-2005 Chris Nandor.  All rights reserved.  This
       program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.


SEE ALSO

       Mac::AppleEvents(3), Mac::OSA(3), Mac::OSA::Simple(3), macperlcat, Inside
       Macintosh: Interapplication Communication.

               http://projects.pudge.net/



perl v5.10.0                      2006-07-06                         Simple(3)

Mac OS X 10.6 - Generated Thu Sep 17 20:13:27 CDT 2009
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.