AppleEvents(3) User Contributed Perl Documentation AppleEvents(3)
NAME
Mac::AppleEvents - Macintosh Toolbox Interface to the Apple Event Manager
SYNOPSIS
use Mac::AppleEvents;
DESCRIPTION
Access to Inside Macintosh is essential for proper use of these functions. Explanations of terms,
processes and procedures are provided there. Any attempt to use these functions without guidance can
cause severe errors in your machine, including corruption of data. You have been warned.
Constants: Apple event Descriptor Types
typeBoolean
A boolean.
typeTrue
A boolean True value.
typeFalse
A boolean False value.
typeChar
A string.
typeShortInteger
A 16 bit integer.
typeInteger
typeLongInteger
A 32 bit integer.
typeMagnitude
An unsigned 32 bit integer.
typeShortFloat
A single precision floating point number.
typeFloat
typeLongFloat
A double precision floating point number.
typeExtended
An extended double precision floating point number.
typeComp
A 64 bit number.
typeAEList
An Apple event list.
typeAERecord
An Apple event record.
typeAppleEvent
An Apple event.
typeFSS
A file specification record.
typeAlias
A file alias record.
typeEnumerated
An enumeration literal (4 byte character).
typeType
An Apple event type (4 byte character).
typeAppParameters
An application launch parameter record.
typeProperty
A property keyword (4 byte character).
typeKeyword
A keyword (4 byte character).
typeSectionH
An Edition Manager section handle.
typeWildCard
An arbitrary value.
typeApplSignature
An application signature (4 byte character).
typeQDRectangle
A QuickDraw rectangle.
typeFixed
A fixed point value.
typeSessionID
A PPC Toolbox session ID.
typeTargetID
A target ID record.
typeProcessSerialNumber
A process serial number.
typeNull
No data.
Constants: Parameter and Attribute Keywords
keyDirectObject
The direct object parameter.
keyErrorNumber
Error number.
keyErrorString
Error string.
keyProcessSerialNumber
Process serial number.
keyTransactionIDAttr
Transaction ID.
keyReturnIDAttr
Return ID.
keyEventClassAttr
Event class.
keyEventIDAttr
Event ID.
keyAddressAttr
Destination address.
keyOptionalKeywordAttr
List of optional keywords.
keyTimeoutAttr
Timeout limit.
keyInteractLevelAttr
Interaction level.
keyEventSourceAttr
Event source address.
keyMissedKeywordAttr
List of mandatory keywords not used.
keyOriginalAddressAttr
Original source address.
keyPreDispatch
Install handler before dispatching.
keySelectProc
Enable/Disable OSL.
keyAERecorderCount
Number of processes recording AppleEvents.
keyAEVersion
Apple Event Manager version.
Constants: Core Apple event Suite
kCoreEventClass
Core Suite Event class.
kAEOpenApplication
Open application without documents.
kAEOpenDocuments
Open documents.
kAEPrintDocuments
Print documents.
kAEQuitApplication
Quit application.
kAEAnswer
Apple event answer event.
kAEApplicationDied
Launched application has ended.
Constants: Miscellaneous
kAENoReply
kAEQueueReply
kAEWaitReply
kAENeverInteract
kAECanInteract
kAEAlwaysInteract
kAECanSwitchLayer
kAEDontReconnect
kAEWantReceipt
kAEDontRecord
kAEDontExecute
kAEInteractWithSelf
kAEInteractWithLocal
kAEInteractWithAll
Apple event sendMode flags.
kAENormalPriority
kAEHighPriority
Apple event priority values.
kAEStartRecording
kAEStopRecording
kAENotifyStartRecording
kAENotifyStopRecording
kAENotifyRecording
Recording events.
kAutoGenerateReturnID
kAnyTransactionID
kAEDefaultTimeout
kNoTimeOut
Special values for return ID, transaction ID, and timeout.
kAENoDispatch
kAEUseStandardDispatch
kAEDoNotIgnoreHandler
kAEIgnoreAppPhacHandler
kAEIgnoreAppEventHandler
kAEIgnoreSysPhacHandler
kAEIgnoreSysEventHandler
kAEIngoreBuiltInEventHandler
kAEDontDisposeOnResume
Options for "AEResumeTheCurrentEvent()".
Variables
%AppleEvent
An array of application-wide event handlers.
$AppleEvent{"aevt", "odoc"} = \&OpenDocument;
%SysAppleEvent
An arrary of system-wide event handlers.
AEDesc
AEDesc is a Perl package that encapsulates an Apple Event Descriptor. It uses the OO methods of
Perl5 to make building and parsing data structures easier.
new TYPE, HANDLE
new TYPE, DATA
new TYPE
new Create a new Apple event descriptor. Sets the type and data to TYPE (default is 'null'), and
HANDLE or DATA (default is empty).
$desc = new AEDesc("aevt", $event);
type TYPE
type
Return the type from the AEDesc structure. If TYPE is present, make it the new type.
data HANDLE
data
Return the data from the AEDesc structure. If HANDLE is present, make it the new data.
Warning: If using Mac OS X, you must dispose of the result on your own. This is because in Mac
OS, we returned the handle from the AEDesc itself, but now we must return a copy. So in Mac OS
we could do:
print $desc->data->get;
Now we must do:
my $handle = $desc->data;
print $handle->get;
$handle->dispose;
Normally, you don't want to call "data" directly anyway, and you would use "get" instead.
get Return the data of the AEDesc structure in a smartly unpacked way.
dispose
Dispose the AEDesc.
AEKeyDesc
AEKeyDesc is a Perl package that encapsulates an Apple event keyword. It uses the OO methods of
Perl5 to make building and parsing data structures easier.
new KEY, TYPE, HANDLE
new KEY, TYPE, DATA
new KEY, TYPE
new KEY
new Creates a new Apple event keyword descriptor. Sets the keyword, type and data to KEY (default is
zero), TYPE (default is 'null'), and HANDLE or DATA (default is empty).
key KEY
key Return the keyword of the AEKeyDesc structure. If KEY is present, make it the new keyword.
type TYPE
type
Return the type from the AEKeyDesc structure. If TYPE is present, make it the new type.
data HANDLE
data
Return the data from the AEKeyDesc structure. If HANDLE is present, make it the new data.
get Return the contents in a smartly unpacked way.
dispose
Dispose the underlying AEDesc.
Raw AppleEvent Interface
AECreateDesc TYPE, DATA
The AECreateDesc function creates a new descriptor record that incorporates the specified data.
AECoerce TYPE, DATA, NEWTYPE
AECoerceDesc DESC, NEWTYPE
The AECoerceDesc function attempts to create a new descriptor record by coercing the specified
descriptor record. AECoerce attempts the same with a Perl data string.
AEDisposeDesc DESC
Deallocate the memory used by a descriptor record.
if ( !AEDisposeDesc($desc) ) {
# error occurred
}
AEDuplicateDesc DESC
Creates a new descriptor record by copying the descriptor record from the parameter $DESC.
$newDesc = AEDuplicateDesc($desc);
if ( defined $newDesc ) {
# do something productive
}
AECreateList FACTOR, BOOL
The AECreateList function creates an empty descriptor list (BOOL is 0), or AE record (BOOL is
nonzero). FACTOR contains the common prefix for each descriptor or is empty.
$list = AECreateList("", 0);
if ( defined $list ) {
# do something productive
}
AECountItems DESCLIST
Count the number of descriptor records in any descriptor list. The result is "undef" if the list
is invalid.
AEPut DESCLIST, INDEX, TYPE, HANDLE
AEPutDesc DESCLIST, INDEX, DESC
Add a descriptor record to any descriptor list. AEPut will manufacture the record to add it to
the list. Return zero if an error was detected.
AEPutKey DESCLIST, KEY, TYPE, HANDLE
AEPutKeyDesc DESCLIST, KEY, DESC
Add a descriptor record and a keyword to an AE record. AEPutKey will manufacture the record to
add it to the AE record. Return zero if an error was detected.
AEGetNthDesc DESCLIST, INDEX [, TYPE]
The AEGetNthDesc function returns a specified descriptor record from a specified descriptor list.
The result is an AEDesc object and the keyword from a keyword specified list.
($Desc, $Key) = AEGetNthDesc($DescList, $i);
if ( defined $Desc ) {
# do something productive
}
AEGetKeyDesc DESCLIST, KEY [, TYPE]
The AEGetKeyDesc function returns a keyword-specified descriptor record from a specified
descriptor record. The result is an AEDesc object.
AEDeleteItem DESCLIST, INDEX
Delete a descriptor record from a descriptor list. All subsequent descriptor records will then
move up one place.
AEPutParam EVENT, KEY, TYPE, HANDLE
AEPutParamDesc EVENT, KEY, DESC
Add a descriptor record and a keyword to an Apple event as an Apple event parameter. AEPutParam
creates the descriptor record.
AEGetParamDesc EVENT, KEY [, TYPE]
The AEGetParamDesc function returns the descriptor record for a specified Apple event parameter,
which it attempts to coerce to the descriptor type specified by TYPE (default is no coercion).
AEDeleteParam EVENT, KEY
Delete an Apple event parameter. Return zero if an error was detected.
AEGetAttributeDesc EVENT, KEY, TYPE
The AEGetAttributeDesc function returns the descriptor record for the Apple event attribute with
the specified keyword.
AEPutAttribute EVENT, KEY, TYPE, HANDLE
AEPutAttributeDesc EVENT, KEY, DESC
The AEPutAttributeDesc function takes a descriptor record and a keyword and adds them to an Apple
event as an attribute. AEPutAttribute creates the record from TYPE and HANDLE. Return zero if
an error was detected.
AECreateAppleEvent CLASS, EVENTID, DESC [, RETURNID [, TRANSACTIONID ] ]
The AECreateAppleEvent function creates an Apple event and returns it. TRANSACTIONID defaults to
zero. RETURNID defaults to kAutoGenerateReturnID.
AESend EVENT, SENDMODE [, SENDPRIORITY [, TIMEOUT ] ]
Send the Apple Event EVENT. TIMEOUT defaults to kAEDefaultTimeout. SENDPRIORITY defaults to
kAENormalPriority. Returns the reply if SENDMODE was kAEWaitReply.
AEResetTimer REPLY
The Apple Event Manager for the server application uses the default reply to send a Reset Timer
event to the client application; the Apple Event Manager for the client application's computer
intercepts this Apple event and resets the client application's timer for the Apple event.
AESuspendTheCurrentEvent EVENT
After a server application makes a successful call to the AESuspendTheCurrentEvent function, it
is no longer required to return a result or a reply for the Apple event that was being handled.
The result is zero if no error was detected.
AEResumeTheCurrentEvent EVENT [, FLAGS, REFCON]
The Apple Event Manager resumes handling the specified Apple event using the handler specified in
the FLAGS parameter, if any. If FLAGS and REFCON are missing, AEResumeTheCurrentEvent simply
informs the Apple Event Manager that the specified event has been handled.
AEGetTheCurrentEvent
Get the Apple event that is currently being handled.
AESetTheCurrentEvent EVENT
There is usually no reason for your application to use the AESetTheCurrentEvent function.
AEGetInteractionAllowed
The AEGetInteractionAllowed function returns a value that indicates the user interaction
preferences for responding to an Apple event. The result is "undef" if an error was detected.
AESetInteractionAllowed LEVEL
The AESetInteractionAllowed function sets the user interaction level for a server application's
response to an Apple event. The result is zero if no error was detected.
AEInstallEventHandler CLASS, EVENTID, HANDLER, HANDLERREFCON [, SYSTEM]
The AEInstallEventHandler function creates an entry in the Apple event dispatch table. You must
supply parameters that specify the event class, the event ID, the address of the handler that
handles Apple events of the specified event class and event ID, and whether the handler is to be
added to the system Apple event dispatch table or your application's Apple event dispatch table.
You can also specify a reference constant that the Apple Event Manager passes to your handler
whenever your handler processes an Apple event.
if (!AEInstallEventHandler(kCoreEventClass, kAEOpenDocuments, 'OpenDocument', 0) ) {
# an error occurred.
}
A much more uniform (and Perl-ish) method is available using the hash arrays %AppleEvent and
%SysAppleEvent to bind handlers to event types.
$AppleEvent{kCoreEventClass, kAEOpenDocuments} = 'OpenDocument';
...
delete $AppleEvent{kCoreEventClass, kAEOpenDocuments};
AERemoveEventHandler CLASS, EVENTID [, SYSTEM]
The AERemoveEventHandler function removes the Apple event dispatch table entry you specify in the
parameters CLASS, EVENTID, and SYSTEM.
AEGetEventHandler CLASS, EVENTID [, SYSTEM]
The AEGetEventHandler function returns the handler and handlerrefcon for the specified class and
event.
($proc, $refcon) = AEGetEventHandler("aevt", "oapp");
AEManagerInfo KEY
Obtain information about the version of the Apple Event Manager currently available or the number
of processes that are currently recording Apple events. The result is "undef" if an error
occurred.
AEGizmos Build/Print
The Apple Event Gizmos were developed by Jens Peter Alfke at Apple as a vastly speeded up AE library.
Consult the AEGizmo documentation for details of usage of the library. The Build/Print facility uses
a formatting convention similar to scanf/printf to put things together.
AEBuild FORMAT, PARM, ...
Build an AppleEvent descriptor using the format per the Gizmo documentation and return it.
AEBuildParameters EVENT, FORMAT, PARM, ...
Build parameters for an existing AppleEvent EVENT.
if (!AEBuildParameters($reply, $format, $parm1, $parm2) ) {
# an error occurred
}
AEBuildAppleEvent CLASS, ID, ADDRESSTYPE, ADDRESS, RETURNID, TRANSACTIONID, FORMAT, PARMS, ...
Construct an AppleEvent from the format and parameters and return it.
AEPrint DESC
Return a string version of the descriptor record. The result is "undef" if an error occurred.
AEGizmos Subdescriptors
The Apple Event Gizmos subdescriptor approach uses a dictionary method for extracting and
constructing descriptors. Parsing an Apple Event using the dictionary is very time efficient, and
translating to and from the dictionary tables is quick and efficient.
AEDescToSubDesc DESC
Mac OS only.
Translate DESC to a subdescriptor (dictionary entry). Return the subdescriptor.
AEGetSubDescType SUBDESC
Mac OS only.
Return the type of the subdescriptor.
AEGetSubDescBasicType SUBDESC
Mac OS only.
Return the basic type of the subdescriptor. Differs from AEGetSubDescType in handling of coerced
records.
AESubDescIsListOrRecord SUBDESC
Mac OS only.
Return nonzero if the subdescriptor is a list or record.
AEGetSubDescData SUBDESC
Mac OS only.
Returns the data of the subdescriptor.
AESubDescToDesc SUBDESC, DESIREDTYPE
Mac OS only.
Translate the subdescriptor back to a descriptor of the desired type.
AECountSubDescItems SUBDESC
Mac OS only.
Counts the number of subdescriptor items.
AEGetNthSubDesc SUBDESC,INDEX
Mac OS only.
Returns the item INDEX of the subdescriptor and its type if the subdescriptor represented a
record and not a list.
AEGetKeySubDesc SUBDESC,KW
Mac OS only.
Returns the keyword indexed item from the subdescriptor.
AEStream
The Apple Event Gizmos streams approach uses a streaming model for building a sequence of
descriptors.
new AEStream
AEStream::Open
Return a new AEStream.
new AEStream(CLASS, ID, ADDRESSTYPE, ADDRESS [, RETURNID [, TRANSACTIONID ] ])
AEStream::CreateEvent CLASS, ID, ADDRESSTYPE, ADDRESS, RETURNID, TRANSACTIONID
Create an AEStream attached to a new AppleEvent.
new AEStream(EVENT)
AEStream::OpenEvent EVENT
Opens the stream on the $EVENT. Return "undef" if an error was detected.
Close
Return the descriptor corresponding to the stream, and close it out.
$stream->Close;
Abort STREAM
Abort the streaming process, and close it out.
$stream->Abort;
OpenDesc TYPE
Start building a descriptor of the given type. Return zero if an error was detected.
if ( $stream->OpenDesc($type) ) {
# Long messy calculation that demonstrates the usefullness of this code
if ( $stream->WriteData($calculatedData)
&& $stream->CloseDesc()
){
# then, my work here is done
}
}
WriteData DATA
Add data to the descriptor.
CloseDesc
Finish up the descriptor.
WriteDesc TYPE, DATA
Add the arbitrary data with the given type as a descriptor to the stream.
WriteAEDesc STREAM, AEDESC
Add an Apple Event descriptor to the stream.
OpenList
Start building a list of AppleEvent descriptors in the stream.
CloseList STREAM
Return zero if an error was detected.
if ( $stream->OpenList() ) {
for $desc (@descList) {
croak unless $stream->WriteAEDesc($desc);
}
die unless $stream->CloseList();
}
OpenRecord [TYPE]
Start the process of building a record, to be coerced to the given type.
SetRecordType TYPE
Change the record type.
CloseRecord STREAM
Close the record currently under construction.
if ( $stream->OpenRecord(typeAErecord) ) {
for $kdesc (@descList) {
die unless $stream->WriteKey($kdesc->key) and
$stream->WriteAEDesc($kdesc->desc);
}
die unless $stream->CloseRecord();
}
WriteKeyDesc KEY, TYPE, DATA
Add the keyword descriptor to the stream.
OpenKeyDesc KEY, TYPE
Open a descriptor with the given type and key. Use CloseDesc() to close it.
WriteKey KEY
Add the keyword to the immediately following descriptor. Return zero if an error was detected.
OptionalParam KEY
Adds the keyword to the list of optional attributes.
AUTHOR
Written by Matthias Ulrich Neeracher <neeracher@mac.com>, documentation by Bob Dalgleish
<bob.dalgleish@sasknet.sk.ca>. Currently maintained by Chris Nandor <pudge@pobox.com>.
perl v5.8.8 2007-09-23 AppleEvents(3)
|