Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/Foundation.framework |
Availability | Available in Mac OS X v10.0 and later. |
Companion guide | |
Declared in | NSAppleEventDescriptor.h |
An instance of NSAppleEventDescriptor
represents a descriptor—the basic building block for Apple events. This class is a wrapper for the underlying Apple event descriptor data type, AEDesc
. Scriptable Cocoa applications frequently work with instances of NSAppleEventDescriptor
, but should rarely need to work directly with the AEDesc
data structure.
A descriptor is a data structure that stores data and an accompanying four-character code. A descriptor can store a value, or it can store a list of other descriptors (which may also be lists). All the information in an Apple event is stored in descriptors and lists of descriptors, and every Apple event is itself a descriptor list that matches certain criteria.
Important: An instance of NSAppleEventDescriptor
can represent any kind of descriptor, from a simple value descriptor, to a descriptor list, to a full-fledged Apple event.
Descriptors can be used to build arbitrarily complex containers, so that one Apple event can represent a script statement such as tell application "TextEdit" to get word 3 of paragraph 6 of document 3
.
In working with Apple event descriptors, it can be useful to understand some of the underlying data types. You’ll find terms such as descriptor, descriptor list, Apple event record, and Apple event defined in Building an Apple Event in Apple Events Programming Guide. You’ll also find information on the four-character codes used to identify information within a descriptor. Apple event data types are defined in Apple Event Manager Reference. The values of many four-character codes used by Apple (and in some cases reused by developers) can be found in AppleScript Terminology and Apple Event Codes.
The most common reason to construct an Apple event with an instance of NSAppleEventDescriptor
is to supply information in a return Apple event. The most common situation where you might need to extract information from an Apple event (as an instance of NSAppleEventDescriptor
) is when an Apple event handler installed by your application is invoked, as described in “Installing an Apple Event Handler” in How Cocoa Applications Handle Apple Events. In addition, if you execute an AppleScript script using the NSAppleScript
class, you get an instance of NSAppleEventDescriptor
as the return value, from which you can extract any required information.
When you work with an instance of NSAppleEventDescriptor
, you can access the underlying descriptor directly, if necessary, with the aeDesc
method. Other methods, including descriptorWithDescriptorType:bytes:length:
make it possible to create and initialize instances of NSAppleEventDescriptor
without creating temporary instances of NSData
.
The designated initializer for NSAppleEventDescriptor
is initWithAEDescNoCopy:
. However, it is unlikely that you will need to create a subclass of NSAppleEventDescriptor
.
Cocoa doesn’t currently provide a mechanism for applications to directly send raw Apple events (though compiling and executing an AppleScript script with NSAppleScript
may result in Apple events being sent). However, Cocoa applications have full access to the Apple Event Manager C APIs for working with Apple events. So, for example, you might use an instance of NSAppleEventDescriptor
to assemble an Apple event and call the Apple Event Manager function AESend
to send it.
If you need to send Apple events, or if you need more information on some of the Apple event concepts described here, see Apple Events Programming Guide and Apple Event Manager Reference.
+ appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:
+ descriptorWithBoolean:
+ descriptorWithDescriptorType:bytes:length:
+ descriptorWithDescriptorType:data:
+ descriptorWithEnumCode:
+ descriptorWithInt32:
+ descriptorWithString:
+ descriptorWithTypeCode:
+ listDescriptor
+ nullDescriptor
+ recordDescriptor
– initListDescriptor
– initRecordDescriptor
– initWithAEDescNoCopy:
– initWithDescriptorType:bytes:length:
– initWithDescriptorType:data:
– initWithEventClass:eventID:targetDescriptor:returnID:transactionID:
– aeDesc
– booleanValue
– coerceToDescriptorType:
– data
– descriptorType
– enumCodeValue
– int32Value
– numberOfItems
– stringValue
– typeCodeValue
– descriptorForKeyword:
– keywordForDescriptorAtIndex:
– removeDescriptorWithKeyword:
– setDescriptor:forKeyword:
Creates a descriptor that represents an Apple event, initialized according to the specified information.
+ (NSAppleEventDescriptor *)appleEventWithEventClass:(AEEventClass)eventClass eventID:(AEEventID)eventID targetDescriptor:(NSAppleEventDescriptor *)addressDescriptor returnID:(AEReturnID)returnID transactionID:(AETransactionID)transactionID
The event class to be set in the returned descriptor.
The event ID to be set in the returned descriptor.
A pointer to a descriptor that identifies the target application for the Apple event. Passing nil
results in an Apple event descriptor that has no keyAddressAttr
attribute (it is valid for an Apple event to have no target address attribute).
The return ID to be set in the returned descriptor. If you pass a value of kAutoGenerateReturnID
, the Apple Event Manager assigns the created Apple event a return ID that is unique to the current session. If you pass any other value, the Apple Event Manager assigns that value for the ID.
The transaction ID to be set in the returned descriptor. A transaction is a sequence of Apple events that are sent back and forth between client and server applications, beginning with the client’s initial request for a service. All Apple events that are part of a transaction must have the same transaction ID. You can specify kAnyTransactionID
if the Apple event is not one of a series of interdependent Apple events.
A descriptor for an Apple event, initialized according to the specified parameter values, or nil
if an error occurs.
Constants such as kAutoGenerateReturnID
and kAnyTransactionID
are defined in AE.framework
, a subframework of ApplicationServices.framework
.
NSAppleEventDescriptor.h
Creates a descriptor initialized with type typeBoolean
that stores the specified Boolean value.
+ (NSAppleEventDescriptor *)descriptorWithBoolean:(Boolean)boolean
The Boolean value to be set in the returned descriptor.
A descriptor with the specified Boolean value, or nil
if an error occurs.
NSAppleEventDescriptor.h
Creates a descriptor initialized with the specified event type that stores the specified data (from a series of bytes).
+ (NSAppleEventDescriptor *)descriptorWithDescriptorType:(DescType)descriptorType bytes:(const void *)bytes length:(NSUInteger)byteCount
The descriptor type to be set in the returned descriptor.
The data, as a sequence of bytes, to be set in the returned descriptor.
The length, in bytes, of the data to be set in the returned descriptor.
A descriptor with the specified type and data, or nil
if an error occurs.
NSAppleEventDescriptor.h
Creates a descriptor initialized with the specified event type that stores the specified data (from an instance of NSData
).
+ (NSAppleEventDescriptor *)descriptorWithDescriptorType:(DescType)descriptorType data:(NSData *)data
The descriptor type to be set in the returned descriptor.
The data, as an instance of NSData
, to be set in the returned descriptor.
A descriptor with the specified type and data, or nil
if an error occurs.
You can use this method to create a descriptor that you can build into a complete Apple event by calling methods such as setAttributeDescriptor:forKeyword:
, setDescriptor:forKeyword:
, and setParamDescriptor:forKeyword:
.
NSAppleEventDescriptor.h
Creates a descriptor initialized with type typeEnumerated
that stores the specified enumerator data type value.
+ (NSAppleEventDescriptor *)descriptorWithEnumCode:(OSType)enumerator
A type code that identifies the type of enumerated data to be stored in the returned descriptor.
A descriptor with the specified enumerator data type value, or nil
if an error occurs.
NSAppleEventDescriptor.h
Creates a descriptor initialized with Apple event type typeSInt32
that stores the specified integer value.
+ (NSAppleEventDescriptor *)descriptorWithInt32:(SInt32)signedInt
The integer value to be stored in the returned descriptor.
A descriptor containing the specified integer value, or nil
if an error occurs.
NSAppleEventDescriptor.h
Creates a descriptor initialized with type typeUnicodeText
that stores the text from the specified string.
+ (NSAppleEventDescriptor *)descriptorWithString:(NSString *)string
A string that specifies the text to be stored in the returned descriptor.
A descriptor that contains the text from the specified string, or nil
if an error occurs.
NSAppleEventDescriptor.h
Creates a descriptor initialized with type typeType
that stores the specified type value.
+ (NSAppleEventDescriptor *)descriptorWithTypeCode:(OSType)typeCode
The type value to be set in the returned descriptor.
A descriptor with the specified type, or nil
if an error occurs.
NSAppleEventDescriptor.h
Creates and initializes an empty list descriptor.
+ (NSAppleEventDescriptor *)listDescriptor
An empty list descriptor, or nil
if an error occurs.
A list descriptor is a descriptor whose data consists of one or more descriptors. You can add items to the list by calling insertDescriptor:atIndex:
or remove them with removeDescriptorAtIndex:
.
Invoking this method is equivalent to allocating an instance of NSAppleEventDescriptor
and invoking initListDescriptor
.
NSAppleEventDescriptor.h
Creates and initializes a descriptor with no parameter or attribute values set.
+ (NSAppleEventDescriptor *)nullDescriptor
A descriptor with no parameter or attribute values set, or nil
if an error occurs.
You don’t typically call this method, as most NSAppleEventDescriptor
instance methods can’t be safely called on the returned empty descriptor.
NSAppleEventDescriptor.h
Creates and initializes a descriptor for an Apple event record whose data has yet to be set.
+ (NSAppleEventDescriptor *)recordDescriptor
An Apple event descriptor whose data has yet to be set, or nil
if an error occurs.
An Apple event record is a descriptor whose data is a set of descriptors keyed by four-character codes. You can add information to the descriptor with methods such as setAttributeDescriptor:forKeyword:
, setDescriptor:forKeyword:
, and setParamDescriptor:forKeyword:
.
Invoking this method is equivalent to allocating an instance of NSAppleEventDescriptor
and invoking initRecordDescriptor
.
NSAppleEventDescriptor.h
Returns a pointer to the AEDesc
structure that is encapsulated by the receiver, if it has one.
- (const AEDesc *)aeDesc
If the receiver has a valid AEDesc
structure, returns a pointer to it; otherwise returns nil
.
NSAppleEventDescriptor.h
Returns a descriptor for the receiver’s Apple event attribute identified by the specified keyword.
- (NSAppleEventDescriptor *)attributeDescriptorForKeyword:(AEKeyword)keyword
A keyword (a four-character code) that identifies the descriptor to obtain.
The attribute descriptor for the specified keyword, or nil
if an error occurs.
The receiver must be an Apple event.
NSAppleEventDescriptor.h
Returns the contents of the receiver as a Boolean value, coercing (to typeBoolean
) if necessary.
- (Boolean)booleanValue
The contents of the descriptor, as a Boolean value, or false
if an error occurs.
NSAppleEventDescriptor.h
Returns a descriptor obtained by coercing the receiver to the specified type.
- (NSAppleEventDescriptor *)coerceToDescriptorType:(DescType)descriptorType
The descriptor type to coerce the receiver to.
A descriptor of the specified type, or nil
if an error occurs.
NSAppleEventDescriptor.h
Returns the receiver’s data as an NSData
object.
- (NSData *)data
An instance of NSData
containing the receiver’s data, or nil
if an error occurs.
NSAppleEventDescriptor.h
Returns the descriptor at the specified (one-based) position in the receiving descriptor list.
- (NSAppleEventDescriptor *)descriptorAtIndex:(NSInteger)anIndex
The one-based descriptor list position of the descriptor to return.
The descriptor from the specified position (one-based) in the descriptor list, or nil
if the specified descriptor cannot be obtained.
NSAppleEventDescriptor.h
Returns the receiver’s descriptor for the specified keyword.
- (NSAppleEventDescriptor *)descriptorForKeyword:(AEKeyword)keyword
A keyword (a four-character code) that identifies the descriptor to obtain.
A descriptor for the specified keyword, or nil
if an error occurs.
NSAppleEventDescriptor.h
Returns the descriptor type of the receiver.
- (DescType)descriptorType
The descriptor type of the receiver.
NSAppleEventDescriptor.h
Returns the contents of the receiver as an enumeration type, coercing (to typeEnumerated
) if necessary.
- (OSType)enumCodeValue
The contents of the descriptor, as an enumeration type, or 0 if an error occurs.
NSAppleEventDescriptor.h
Returns the event class for the receiver.
- (AEEventClass)eventClass
The event class (a four-character code) for the receiver, or 0 if an error occurs.
The receiver must be an Apple event. An Apple event is identified by its event class and event ID, a pair of four-character codes stored as 32-bit integers. For example, most events in the Standard suite have the four-character code 'core'
(defined as the constant kAECoreSuite
in AE.framework
, a subframework of ApplicationServices.framework
). For more information on event classes and event IDs, see Building an Apple Event in Apple Events Programming Guide.
NSAppleEventDescriptor.h
Returns the event ID for the receiver.
- (AEEventID)eventID
The event ID (a four-character code) for the receiver, or 0 if an error occurs.
The receiver must be an Apple event. An Apple event is identified by its event class and event ID, a pair of four-character codes stored as 32-bit integers. For example, the open
Apple event from the Standard suite has the four-character code 'odoc'
(defined as the constant kAEOpen
in AE.framework
, a subframework of ApplicationServices.framework
).
NSAppleEventDescriptor.h
Initializes a newly allocated instance as an empty list descriptor.
- (id)initListDescriptor
An empty list descriptor, or nil
if an error occurs.
You can add items to the empty list descriptor with insertDescriptor:atIndex:
. The list indices are one-based.
NSAppleEventDescriptor.h
Initializes a newly allocated instance as a descriptor that is an Apple event record.
- (id)initRecordDescriptor
The initialized Apple event record, or nil
if an error occurs.
An Apple event record is a descriptor whose data is a set of descriptors keyed by four-character codes. You can add information to the descriptor with methods such as setAttributeDescriptor:forKeyword:
, setDescriptor:forKeyword:
, and setParamDescriptor:forKeyword:
.
NSAppleEventDescriptor.h
Initializes a newly allocated instance as a descriptor for the specified Carbon AEDesc
structure.
- (id)initWithAEDescNoCopy:(const AEDesc *)aeDesc
A pointer to the AEDesc
structure to associate with the descriptor.
An instance of NSAppleEventDescriptor
that is associated with the structure pointed to by aeDesc, or nil
if an error occurs.
The initialized object takes responsibility for calling the AEDisposeDesc
function on the AEDesc
at object deallocation time. This is the designated initializer for this class.
NSAppleEventDescriptor.h
Initializes a newly allocated instance as a descriptor with the specified descriptor type and data (from an arbitrary sequence of bytes and a length count).
- (id)initWithDescriptorType:(DescType)descriptorType bytes:(const void *)bytes length:(NSUInteger)byteCount
The descriptor type to be set in the returned descriptor.
The data, as a sequence of bytes, to be set in the returned descriptor.
The length, in bytes, of the data to be set in the returned descriptor.
An instance of NSAppleEventDescriptor
with the specified type and data. Returns nil
if an error occurs.
NSAppleEventDescriptor.h
Initializes a newly allocated instance as a descriptor with the specified descriptor type and data (from an instance of NSData
).
- (id)initWithDescriptorType:(DescType)descriptorType data:(NSData *)data
The descriptor type to be set in the initialized descriptor.
The data to be set in the initialized descriptor.
An instance of NSAppleEventDescriptor
with the specified type and data. Returns nil
if an error occurs.
NSAppleEventDescriptor.h
Initializes a newly allocated instance as a descriptor for an Apple event, initialized with the specified values.
- (id)initWithEventClass:(AEEventClass)eventClass eventID:(AEEventID)eventID targetDescriptor:(NSAppleEventDescriptor *)addressDescriptor returnID:(AEReturnID)returnID transactionID:(AETransactionID)transactionID
The event class to be set in the returned descriptor.
The event ID to be set in the returned descriptor.
A pointer to a descriptor that identifies the target application for the Apple event. Passing nil
results in an Apple event descriptor that has no keyAddressAttr
attribute (it is valid for an Apple event to have no target address attribute).
The return ID to be set in the returned descriptor. If you pass a value of kAutoGenerateReturnID
, the Apple Event Manager assigns the created Apple event a return ID that is unique to the current session. If you pass any other value, the Apple Event Manager assigns that value for the ID.
The transaction ID to be set in the returned descriptor. A transaction is a sequence of Apple events that are sent back and forth between client and server applications, beginning with the client’s initial request for a service. All Apple events that are part of a transaction must have the same transaction ID. You can specify kAnyTransactionID
if the Apple event is not one of a series of interdependent Apple events.
The initialized Apple event (an instance of NSAppleEventDescriptor
), or nil
if an error occurs.
NSAppleEventDescriptor.h
Inserts a descriptor at the specified (one-based) position in the receiving descriptor list, replacing the existing descriptor, if any, at that position.
- (void)insertDescriptor:(NSAppleEventDescriptor *)descriptor atIndex:(NSInteger)anIndex
The descriptor to insert in the receiver. Specifying an index of 0 or count + 1 causes appending to the end of the list.
The one-based descriptor list position at which to insert the descriptor.
Because it actually replaces the descriptor, if any, at the specified position, this method might better be called replaceDescriptor:atIndex:
. The receiver must be a list descriptor. The indices are one-based. Currently provides no indication if an error occurs.
NSAppleEventDescriptor.h
Returns the contents of the receiver as an integer, coercing (to typeSInt32
) if necessary.
- (SInt32)int32Value
The contents of the descriptor, as an integer value, or 0 if an error occurs.
NSAppleEventDescriptor.h
Returns the keyword for the descriptor at the specified (one-based) position in the receiver.
- (AEKeyword)keywordForDescriptorAtIndex:(NSInteger)anIndex
The one-based descriptor list position of the descriptor to get the keyword for.
The keyword (a four-character code) for the descriptor at the one-based location specified by anIndex, or 0 if an error occurs.
NSAppleEventDescriptor.h
Returns the number of descriptors in the receiver’s descriptor list.
- (NSInteger)numberOfItems
The number of descriptors in the receiver’s descriptor list (possibly 0); returns 0 if an error occurs.
NSAppleEventDescriptor.h
Returns a descriptor for the receiver’s Apple event parameter identified by the specified keyword.
- (NSAppleEventDescriptor *)paramDescriptorForKeyword:(AEKeyword)keyword
A keyword (a four-character code) that identifies the parameter descriptor to obtain.
A descriptor for the specified keyword, or nil
if an error occurs.
The receiver must be an Apple event.
NSAppleEventDescriptor.h
Removes the descriptor at the specified (one-based) position in the receiving descriptor list.
- (void)removeDescriptorAtIndex:(NSInteger)anIndex
The one-based position of the descriptor to remove.
The receiver must be a list descriptor. The indices are one-based. Currently provides no indication if an error occurs.
NSAppleEventDescriptor.h
Removes the receiver’s descriptor identified by the specified keyword.
- (void)removeDescriptorWithKeyword:(AEKeyword)keyword
A keyword (a four-character code) that identifies the descriptor to remove.
The receiver must be an Apple event or Apple event record. Currently provides no indication if an error occurs.
NSAppleEventDescriptor.h
Removes the receiver’s parameter descriptor identified by the specified keyword.
- (void)removeParamDescriptorWithKeyword:(AEKeyword)keyword
A keyword (a four-character code) that identifies the parameter descriptor to remove. Currently provides no indication if an error occurs.
The receiver must be an Apple event or Apple event record, both of which can contain parameters.
NSAppleEventDescriptor.h
Returns the receiver’s return ID (the ID for a reply Apple event).
- (AEReturnID)returnID
The receiver’s return ID (an integer value), or 0 if an error occurs.
The receiver must be an Apple event.
NSAppleEventDescriptor.h
Adds a descriptor to the receiver as an attribute identified by the specified keyword.
- (void)setAttributeDescriptor:(NSAppleEventDescriptor *)descriptor forKeyword:(AEKeyword)keyword
The attribute descriptor to add to the receiver.
A keyword (a four-character code) that identifies the attribute descriptor to add. If a descriptor with that keyword already exists in the receiver, it is replaced.
The receiver must be an Apple event. Currently provides no indication if an error occurs.
NSAppleEventDescriptor.h
Adds a descriptor, identified by a keyword, to the receiver.
- (void)setDescriptor:(NSAppleEventDescriptor *)descriptor forKeyword:(AEKeyword)keyword
The descriptor to add to the receiver.
A keyword (a four-character code) that identifies the descriptor to add. If a descriptor with that keyword already exists in the receiver, it is replaced.
The receiver must be an Apple event or Apple event record. Currently provides no indication if an error occurs.
NSAppleEventDescriptor.h
Adds a descriptor to the receiver as an Apple event parameter identified by the specified keyword.
- (void)setParamDescriptor:(NSAppleEventDescriptor *)descriptor forKeyword:(AEKeyword)keyword
The parameter descriptor to add to the receiver.
A keyword (a four-character code) that identifies the parameter descriptor to add. If a descriptor with that keyword already exists in the receiver, it is replaced.
The receiver must be an Apple event or Apple event record, both of which can contain parameters.
NSAppleEventDescriptor.h
Returns the contents of the receiver as a Unicode text string, coercing (to typeUnicodeText
) if necessary.
- (NSString *)stringValue
The contents of the descriptor, as a string, or nil
if an error occurs.
NSAppleEventDescriptor.h
Returns the receiver’s transaction ID, if any.
- (AETransactionID)transactionID
The receiver’s transaction ID (an integer value), or 0 if an error occurs.
The receiver must be an Apple event. Currently provides no indication if an error occurs. For more information on transactions, see the description for appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:
.
NSAppleEventDescriptor.h
Last updated: 2007-04-10