The AECreateDesc function creates a new descriptor record that incorporates the specified data.
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.
Deallocate the memory used by a descriptor record.
if ( !AEDisposeDesc($desc) ) {
# error occurred
}
Creates a new descriptor record by copying the descriptor record from the parameter $DESC.
$newDesc = AEDuplicateDesc($desc);
if ( defined $newDesc ) {
# do something productive
}
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
}
Count the number of descriptor records in any descriptor list. The result is undef if the list is invalid.
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.
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.
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
}
The AEGetKeyDesc function returns a keyword-specified descriptor record from a specified descriptor record. The result is an AEDesc object.
Delete a descriptor record from a descriptor list. All subsequent descriptor records will then move up one place.
Add a descriptor record and a keyword to an Apple event as an Apple event parameter. AEPutParam creates the descriptor record.
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).
Delete an Apple event parameter. Return zero if an error was detected.
The AEGetAttributeDesc function returns the descriptor record for the Apple event attribute with the specified keyword.
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.
The AECreateAppleEvent function creates an Apple event and returns it. TRANSACTIONID defaults to zero. RETURNID defaults to kAutoGenerateReturnID.
Send the Apple Event EVENT. TIMEOUT defaults to kAEDefaultTimeout. SENDPRIORITY defaults to kAENormalPriority. Returns the reply if SENDMODE was kAEWaitReply.
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.
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.
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.
Get the Apple event that is currently being handled.
There is usually no reason for your application to use the AESetTheCurrentEvent function.
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.
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.
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};
The AERemoveEventHandler function removes the Apple event dispatch table entry you specify in the parameters CLASS, EVENTID, and SYSTEM.
The AEGetEventHandler function returns the handler and handlerrefcon for the specified class and event.
($proc, $refcon) = AEGetEventHandler("aevt", "oapp");
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.
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.
Build an AppleEvent descriptor using the format per the Gizmo documentation and return it.
Build parameters for an existing AppleEvent EVENT.
if (!AEBuildParameters($reply, $format, $parm1, $parm2) ) {
# an error occurred
}
Construct an AppleEvent from the format and parameters and return it.
Return a string version of the descriptor record. The result is undef if an error occurred.
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.
Mac OS only.
Translate DESC to a subdescriptor (dictionary entry). Return the subdescriptor.
Mac OS only.
Return the type of the subdescriptor.
Mac OS only.
Return the basic type of the subdescriptor. Differs from AEGetSubDescType in handling of coerced records.
Mac OS only.
Return nonzero if the subdescriptor is a list or record.
Mac OS only.
Returns the data of the subdescriptor.
Mac OS only.
Translate the subdescriptor back to a descriptor of the desired type.
Mac OS only.
Counts the number of subdescriptor items.
Mac OS only.
Returns the item INDEX of the subdescriptor and its type if the subdescriptor represented a record and not a list.
Mac OS only.
Returns the keyword indexed item from the subdescriptor.
The Apple Event Gizmos streams approach uses a streaming model for building a sequence of descriptors.
Return a new AEStream.
Create an AEStream attached to a new AppleEvent.
Opens the stream on the $EVENT. Return undef if an error was detected.
Return the descriptor corresponding to the stream, and close it out.
$stream->Close;
Abort the streaming process, and close it out.
$stream->Abort;
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
}
}
Add data to the descriptor.
Finish up the descriptor.
Add the arbitrary data with the given type as a descriptor to the stream.
Add an Apple Event descriptor to the stream.
Start building a list of AppleEvent descriptors in the stream.
Return zero if an error was detected.
if ( $stream->OpenList() ) {
for $desc (@descList) {
croak unless $stream->WriteAEDesc($desc);
}
die unless $stream->CloseList();
}
Start the process of building a record, to be coerced to the given type.
Change the record type.
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();
}
Add the keyword descriptor to the stream.
Open a descriptor with the given type and key. Use CloseDesc() to close it.
Add the keyword to the immediately following descriptor. Return zero if an error was detected.
Adds the keyword to the list of optional attributes.
