objc-aem manual | 6. Building and sending events

6. Building and sending events

Creating events

The AEMApplication class's -eventWithEventClass:eventID:returnID:codecs: method is used to create new Apple events targetted at the specified application.

- (id)eventWithEventClass:(AEEventClass)classCode
 eventID:(AEEventID)code
 returnID:(AEReturnID)returnID
 codecs:(id)codecs;

The event class, event ID and return ID arguments are the same as for AECreateAppleEvent.

The codecs argument should be an AEMCodecs instance, or some other object that implements -pack: and -unpack: methods with identical signatures. This object will be used to pack the event's attributes and parameters, and to unpack its return value, if any.

When invoked, this method will return a new AEMEvent instance (assuming that the client hasn't been replaced this with an alternative 'event' class).

The following shortcuts are also provided for convenience:

- (id)eventWithEventClass:(AEEventClass)classCode
 eventID:(AEEventID)code
 returnID:(AEReturnID)returnID;
/*
 * Uses default AEMCodecs instance.
 */
- (id)eventWithEventClass:(AEEventClass)classCode
 eventID:(AEEventID)code
 codecs:(id)codecs;
/*
 * Uses kAutoGenerateReturnID.
 */
- (id)eventWithEventClass:(AEEventClass)classCode
 eventID:(AEEventID)code;
/*
 * Uses kAutoGenerateReturnID and a standard AEMCodecs instance.
 */

The `AEMEvent` class

The AEMEvent class represents an Apple event.

@interface AEMEvent : NSObject
/*
 * Get codecs object used by this AEMEvent instance
 */
 - (id)codecs;
/*
 * Get a pointer to the AEDesc contained by this AEMEvent instance
 */
- (const AppleEvent *)aeDesc;
/*
 * Get an NSAppleEventDescriptor instance containing a copy of this
 * event.
 */
- (NSAppleEventDescriptor *)descriptor;
// Pack event's attributes and parameters, if any.
- (AEMEvent *)setAttributePtr:(void *)dataPtr 
						 size:(Size)dataSize
			 descriptorType:(DescType)typeCode
				 forKeyword:(AEKeyword)key;
- (AEMEvent *)setParameterPtr:(void *)dataPtr 
						 size:(Size)dataSize
			 descriptorType:(DescType)typeCode
				 forKeyword:(AEKeyword)key;
- (AEMEvent *)setAttribute:(id)value forKeyword:(AEKeyword)key;
- (AEMEvent *)setParameter:(id)value forKeyword:(AEKeyword)key;
// Get event's attributes and parameters.
- (id)attributeForKeyword:(AEKeyword)key type:(DescType)type error:(NSError **)error;
- (id)attributeForKeyword:(AEKeyword)key; // shortcut for above
- (id)parameterForKeyword:(AEKeyword)key type:(DescType)type error:(NSError **)error;
- (id)parameterForKeyword:(AEKeyword)key; // shortcut for above
/*
 * Specify how the the reply descriptor should be unpacked.
 * (Default = kAEMUnpackAsItem of typeWildCard)
 */
- (void)setUnpackFormat:(AEMUnpackFormat)format_ type:(DescType)type_;
- (void)getUnpackFormat:(AEMUnpackFormat *)format_ type:(DescType *)type_;
// Send event.
/*
 * sendMode
 * Bitwise flags determining how event should be handled.
 * A common default is kAEWaitReply.
 *
 * timeoutInTicks
 * Number of ticks to wait for application reply before raising
 * timeout error. A positive integer, kDefaultTimeout or kNoTimeOut.
 *
 * error
 * On return, an NSError object that describes an Apple Event
 * Manager or application error if one has occurred, otherwise nil.
 * Pass nil if not required.
 *
 * Return value
 *
 * The value returned by the application, or an NSNull instance if
 * no value was returned, or nil if an error occurred.
 *
 * Notes
 *
 * See AESendMessage for more information on the sendMode and
 * timeoutInTicks arguments.
 *
 */
- (id)sendWithMode:(AESendMode)sendMode 
 timeout:(long)timeoutInTicks
 error:(NSError **)error;
// Convenience shortcuts:
- (id)sendWithError:(NSError **)error;
- (id)send;
@end

The send method may be called any number of times.

Commonly used constants

A large number of Apple event-related constants are defined in the AE and OpenScripting frameworks; some of the more relevant ones are listed below.

Parameter keys

keyDirectObject
keyAERequestedType

(The value for a keyAERequestedType parameter should be an AEMType instance.)

Other parameter keys are defined by individual applications.

Attribute keys

Most of the following attributes are already supplied by other means (e.g. keyEventClassAttr, keyEventIDAttr are supplied separately when creating an Apple event; keyTimeoutAttr when sending it) and are only of interest if unpacking AppleEvent descriptors manually. A few may be used in -setAttribute:forKeyword: (enumConsiderations, enumConsidsAndIgnores, keySubjectAttr):

keyTransactionIDAttr
keyReturnIDAttr
keyEventClassAttr
keyEventIDAttr
keyAddressAttr
keyOptionalKeywordAttr
keyTimeoutAttr
keyInteractLevelAttr
keyEventSourceAttr
keyOriginalAddressAttr
keyAcceptTimeoutAttr
enumConsiderations
enumConsidsAndIgnores
keySubjectAttr

The value of the enumConsiderations attribute should be a list containing zero or more AEMEnum instances with the following codes:

kAECase
kAEDiacritic
kAEWhiteSpace
kAEHyphens
kAEExpansion
kAEPunctuation
kASConsiderReplies
kASNumericStrings

See the Apple Event Manager API reference for more info. Note that the enumConsiderations attribute is deprecated in favour of the enumConsidsAndIgnores attribute.

The value of the enumConsidsAndIgnores attribute should be composed from zero or more of the following bit masks:

kAECaseConsiderMask
kAEDiacriticConsiderMask
kAEWhiteSpaceConsiderMask
kAEHyphensConsiderMask
kAEExpansionConsiderMask
kAEPunctuationConsiderMask
kASConsiderRepliesConsiderMask
kASNumericStringsConsiderMask
kAECaseIgnoreMask
kAEDiacriticIgnoreMask
kAEWhiteSpaceIgnoreMask
kAEHyphensIgnoreMask
kAEExpansionIgnoreMask
kAEPunctuationIgnoreMask
kASConsiderRepliesIgnoreMask
kASNumericStringsIgnoreMask

Send flag constants

The value of the send method's flags argument should be an integer composed from the sum of zero or more of the following bit masks:

kAENoReply
kAEQueueReply
kAEWaitReply
kAEDontReconnect
kAEWantReceipt
kAENeverInteract
kAECanInteract
kAEAlwaysInteract
kAECanSwitchLayer

See the Apple Event Manager API reference for details.

Other constants

kAutoGenerateReturnID

objc-appscript