Chris Nandor > Mac-Carbon-0.82 > AppleEvents/AppleEvents.xs

Download:
Mac-Carbon-0.82.tar.gz

Annotate this POD

CPAN RT

New  4
Open  6
Stalled  1
View/Report Bugs
Source  

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.

syntax highlighting: