/*
	NSAppleEventDescriptor.h
	Copyright (c) 1997-2019, Apple Inc. All rights reserved.
*/

#import <Foundation/NSObject.h>
#import <Foundation/NSDate.h>
#import <CoreServices/CoreServices.h>

@class NSData;

NS_HEADER_AUDIT_BEGIN(nullability, sendability)

typedef NS_OPTIONS(NSUInteger, NSAppleEventSendOptions) {
    /// Sender doesn't want a reply to event.
    NSAppleEventSendNoReply        = kAENoReply,
    /// Sender wants a reply but won't wait.
    NSAppleEventSendQueueReply     = kAEQueueReply,
    /// Sender wants a reply and will wait.
    NSAppleEventSendWaitForReply   = kAEWaitReply,
    /// Server should not interact with user.
    NSAppleEventSendNeverInteract  = kAENeverInteract,
    /// Server may try to interact with user.
    NSAppleEventSendCanInteract    = kAECanInteract,
    /// Server should always interact with user where appropriate.
    NSAppleEventSendAlwaysInteract = kAEAlwaysInteract,
    /// Interaction may switch layer.
    NSAppleEventSendCanSwitchLayer = kAECanSwitchLayer,
    /// Don't record this event.
    NSAppleEventSendDontRecord     = kAEDontRecord,
    /// Don't execute this event; used for recording.
    NSAppleEventSendDontExecute    = kAEDontExecute,
    /// Don't automatically add any sandbox or other annotations to the event.
    NSAppleEventSendDontAnnotate   = kAEDoNotAutomaticallyAddAnnotationsToEvent,

    /// The default options: wait for reply and allow interaction.
    NSAppleEventSendDefaultOptions = NSAppleEventSendWaitForReply | NSAppleEventSendCanInteract
} API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// A wrapper for the Apple event descriptor data type.
///
/// 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, <doc://com.apple.documentation/documentation/coreservices/aedesc>. Scriptable Cocoa applications frequently work with instances of ``NSAppleEventDescriptor``, but should rarely need to work directly with the <doc://com.apple.documentation/documentation/coreservices/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 <doc://com.apple.documentation/documentation/applicationservices/apple_event_manager>. 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](http://developer.apple.com/releasenotes/AppleScript/ASTerminology_AppleEventCodes/TermsAndCodes.html).
///
/// 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](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ScriptableCocoaApplications/SApps_handle_AEs/SAppsHandleAEs.html#//apple_ref/doc/uid/20001239). 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 ``init(aeDescNoCopy:)``. 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 <doc://com.apple.documentation/documentation/applicationservices/apple_event_manager>.
@interface NSAppleEventDescriptor : NSObject<NSCopying, NSSecureCoding> {
    @private
    AEDesc _desc;
    BOOL _hasValidDesc;
    char _padding[3];
}

/// Creates and initializes a descriptor with no parameter or attribute values set.
///
/// You don't typically call this method, as most `NSAppleEventDescriptor` instance methods can't be safely called on the returned empty descriptor.
+ (NSAppleEventDescriptor *)nullDescriptor;

/// Creates a descriptor initialized with the specified event type that stores the specified data (from a series of bytes).
///
/// - Parameters:
///   - descriptorType: The descriptor type to be set in the returned descriptor.
///   - bytes: The data, as a sequence of bytes, to be set in the returned descriptor.
///   - byteCount: The length, in bytes, of the data to be set in the returned descriptor.
/// - Returns: A descriptor with the specified type and data, or `nil` if an error occurs.
+ (nullable NSAppleEventDescriptor *)descriptorWithDescriptorType:(DescType)descriptorType bytes:(nullable const void *)bytes length:(NSUInteger)byteCount;

/// Creates a descriptor initialized with the specified event type that stores the specified data (from an instance of `NSData`).
///
/// - Parameters:
///   - descriptorType: The descriptor type to be set in the returned descriptor.
///   - data: The data, as an instance of `NSData`, to be set in the returned descriptor.
/// - Returns: 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:`.
+ (nullable NSAppleEventDescriptor *)descriptorWithDescriptorType:(DescType)descriptorType data:(nullable NSData *)data;

/// Creates a descriptor initialized with type `typeBoolean` that stores the specified Boolean value.
///
/// - Parameter boolean: The Boolean value to be set in the returned descriptor.
/// - Returns: A descriptor with the specified Boolean value, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithBoolean:(Boolean)boolean;

/// Creates a descriptor initialized with type `typeEnumerated` that stores the specified enumerator data type value.
///
/// - Parameter enumerator: A type code that identifies the type of enumerated data to be stored in the returned descriptor.
/// - Returns: A descriptor with the specified enumerator data type value, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithEnumCode:(OSType)enumerator;

/// Creates a descriptor initialized with Apple event type `typeSInt32` that stores the specified integer value.
///
/// - Parameter signedInt: The integer value to be stored in the returned descriptor.
/// - Returns: A descriptor containing the specified integer value, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithInt32:(SInt32)signedInt;

/// Creates a descriptor initialized with Apple event type `typeIEEE64BitFloatingPoint` that stores the specified double value.
+ (NSAppleEventDescriptor *)descriptorWithDouble:(double)doubleValue API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// Creates a descriptor initialized with type `typeType` that stores the specified type value.
///
/// - Parameter typeCode: The type value to be set in the returned descriptor.
/// - Returns: A descriptor with the specified type, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithTypeCode:(OSType)typeCode;

/// Creates a descriptor initialized with type `typeUnicodeText` that stores the text from the specified string.
///
/// - Parameter string: A string that specifies the text to be stored in the returned descriptor.
/// - Returns: A descriptor that contains the text from the specified string, or `nil` if an error occurs.
+ (NSAppleEventDescriptor *)descriptorWithString:(NSString *)string;

/// Creates a descriptor that stores the specified date value.
+ (NSAppleEventDescriptor *)descriptorWithDate:(NSDate *)date API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// Creates a descriptor that stores the specified file URL.
+ (NSAppleEventDescriptor *)descriptorWithFileURL:(NSURL *)fileURL API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// Creates a descriptor that represents an Apple event, initialized according to the specified information.
///
/// - Parameters:
///   - eventClass: The event class to be set in the returned descriptor.
///   - eventID: The event ID to be set in the returned descriptor.
///   - targetDescriptor: 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).
///   - returnID: 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.
///   - transactionID: 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.
/// - Returns: 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 *)appleEventWithEventClass:(AEEventClass)eventClass eventID:(AEEventID)eventID targetDescriptor:(nullable NSAppleEventDescriptor *)targetDescriptor returnID:(AEReturnID)returnID transactionID:(AETransactionID)transactionID;

/// Creates and initializes an empty list descriptor.
///
/// 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 *)listDescriptor;

/// Creates and initializes a descriptor for an Apple event record whose data has yet to be set.
///
/// 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 *)recordDescriptor;

/// Creates and returns an application address descriptor using the current process.
///
/// The result is suitable for use as the `targetDescriptor` parameter of `+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:`.
+ (NSAppleEventDescriptor *)currentProcessDescriptor API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// Creates and returns an application address descriptor using the specified process identifier.
///
/// The result is suitable for use as the `targetDescriptor` parameter of `+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:`.
+ (NSAppleEventDescriptor *)descriptorWithProcessIdentifier:(pid_t)processIdentifier API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// Creates and returns an application address descriptor using the specified bundle identifier.
///
/// The result is suitable for use as the `targetDescriptor` parameter of `+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:`.
+ (NSAppleEventDescriptor *)descriptorWithBundleIdentifier:(NSString *)bundleIdentifier API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// Creates and returns an application address descriptor using the specified application URL.
///
/// The result is suitable for use as the `targetDescriptor` parameter of `+appleEventWithEventClass:eventID:targetDescriptor:returnID:transactionID:`.
+ (NSAppleEventDescriptor *)descriptorWithApplicationURL:(NSURL *)applicationURL API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// Initializes a newly allocated instance as a descriptor for the specified Carbon `AEDesc` structure.
///
/// 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.
///
/// - Parameter aeDesc: A pointer to the `AEDesc` structure to associate with the descriptor.
/// - Returns: An instance of `NSAppleEventDescriptor` that is associated with the structure pointed to by `aeDesc`, or `nil` if an error occurs.
- (instancetype)initWithAEDescNoCopy:(const AEDesc *)aeDesc NS_DESIGNATED_INITIALIZER;

/// 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).
///
/// - Parameters:
///   - descriptorType: The descriptor type to be set in the returned descriptor.
///   - bytes: The data, as a sequence of bytes, to be set in the returned descriptor.
///   - byteCount: The length, in bytes, of the data to be set in the returned descriptor.
/// - Returns: An instance of `NSAppleEventDescriptor` with the specified type and data. Returns `nil` if an error occurs.
- (nullable instancetype)initWithDescriptorType:(DescType)descriptorType bytes:(nullable const void *)bytes length:(NSUInteger)byteCount;

/// Initializes a newly allocated instance as a descriptor with the specified descriptor type and data (from an instance of `NSData`).
///
/// - Parameters:
///   - descriptorType: The descriptor type to be set in the initialized descriptor.
///   - data: The data to be set in the initialized descriptor.
/// - Returns: An instance of `NSAppleEventDescriptor` with the specified type and data. Returns `nil` if an error occurs.
- (nullable instancetype)initWithDescriptorType:(DescType)descriptorType data:(nullable NSData *)data;

/// Initializes a newly allocated instance as a descriptor for an Apple event, initialized with the specified values.
///
/// - Parameters:
///   - eventClass: The event class to be set in the returned descriptor.
///   - eventID: The event ID to be set in the returned descriptor.
///   - targetDescriptor: 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.
///   - returnID: The return ID to be set in the returned descriptor. Pass `kAutoGenerateReturnID` to have the Apple Event Manager assign a unique return ID.
///   - transactionID: The transaction ID to be set in the returned descriptor. You can specify `kAnyTransactionID` if the Apple event is not one of a series of interdependent Apple events.
/// - Returns: The initialized Apple event (an instance of `NSAppleEventDescriptor`), or `nil` if an error occurs.
- (instancetype)initWithEventClass:(AEEventClass)eventClass eventID:(AEEventID)eventID targetDescriptor:(nullable NSAppleEventDescriptor *)targetDescriptor returnID:(AEReturnID)returnID transactionID:(AETransactionID)transactionID;

/// Initializes a newly allocated instance as an empty list descriptor.
///
/// You can add items to the empty list descriptor with `-insertDescriptor:atIndex:`. The list indices are one-based.
- (instancetype)initListDescriptor;

/// Initializes a newly allocated instance as a descriptor that is an Apple event record.
///
/// 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:`.
- (instancetype)initRecordDescriptor;

/// The `AEDesc` structure encapsulated by the receiver, if it has one.
///
/// If the receiver has a valid `AEDesc` structure, returns a pointer to it; otherwise returns `nil`.
@property (nullable, readonly) const AEDesc *aeDesc NS_RETURNS_INNER_POINTER;

/// The descriptor type of the receiver.
@property (readonly) DescType descriptorType;

/// The receiver's data.
///
/// An instance of `NSData` containing the receiver's data, or `nil` if an error occurs.
@property (readonly, copy) NSData *data;

/// The contents of the receiver as a Boolean value, coercing (to `typeBoolean`) if necessary.
///
/// The contents of the descriptor, as a Boolean value, or `false` if an error occurs.
@property (readonly) Boolean booleanValue;

/// The contents of the receiver as an enumeration type, coercing to `typeEnumerated` if necessary.
///
/// The contents of the descriptor, as an enumeration type, or 0 if an error occurs.
@property (readonly) OSType enumCodeValue;

/// The contents of the receiver as an integer, coercing (to `typeSInt32`) if necessary.
///
/// The contents of the descriptor, as an integer value, or 0 if an error occurs.
@property (readonly) SInt32 int32Value;

/// The contents of the receiver as a double value, coercing (to `typeIEEE64BitFloatingPoint`) if necessary.
@property (readonly) double doubleValue API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// The contents of the receiver as a type, coercing to `typeType` if necessary.
///
/// The contents of the descriptor, as a type, or 0 if an error occurs.
@property (readonly) OSType typeCodeValue;

/// The contents of the receiver as a Unicode text string, coercing to `typeUnicodeText` if necessary.
///
/// The contents of the descriptor, as a string, or `nil` if an error occurs.
@property (nullable, readonly, copy) NSString *stringValue;

/// The contents of the receiver as a date, coercing if necessary.
@property (nullable, readonly, copy) NSDate *dateValue API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// The contents of the receiver as a file URL, coercing if necessary.
@property (nullable, readonly, copy) NSURL *fileURLValue API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// The event class for the receiver.
///
/// 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.
@property (readonly) AEEventClass eventClass;

/// The event ID for the receiver.
///
/// The event ID (a four-character code) for the receiver, or 0 if an error occurs.
/// The receiver must be an Apple event.
@property (readonly) AEEventID eventID;

/// The receiver's return ID (the ID for a reply Apple event).
///
/// The receiver's return ID (an integer value), or 0 if an error occurs. The receiver must be an Apple event.
@property (readonly) AEReturnID returnID;

/// The receiver's transaction ID, if any.
///
/// The receiver's transaction ID (an integer value), or 0 if an error occurs. The receiver must be an Apple event.
@property (readonly) AETransactionID transactionID;

/// Adds a descriptor to the receiver as an Apple event parameter identified by the specified keyword.
///
/// - Parameters:
///   - descriptor: The parameter descriptor to add to the receiver.
///   - keyword: 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.
- (void)setParamDescriptor:(NSAppleEventDescriptor *)descriptor forKeyword:(AEKeyword)keyword;

/// Returns a descriptor for the receiver's Apple event parameter identified by the specified keyword.
///
/// - Parameter keyword: A keyword (a four-character code) that identifies the parameter descriptor to obtain.
/// - Returns: A descriptor for the specified keyword, or `nil` if an error occurs.
///
/// The receiver must be an Apple event.
- (nullable NSAppleEventDescriptor *)paramDescriptorForKeyword:(AEKeyword)keyword;

/// Removes the receiver's parameter descriptor identified by the specified keyword.
///
/// - Parameter keyword: A keyword (a four-character code) that identifies the parameter descriptor to remove.
///
/// The receiver must be an Apple event or Apple event record, both of which can contain parameters.
/// Currently provides no indication if an error occurs.
- (void)removeParamDescriptorWithKeyword:(AEKeyword)keyword;

/// Adds a descriptor to the receiver as an attribute identified by the specified keyword.
///
/// - Parameters:
///   - descriptor: The attribute descriptor to add to the receiver.
///   - keyword: 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.
- (void)setAttributeDescriptor:(NSAppleEventDescriptor *)descriptor forKeyword:(AEKeyword)keyword;

/// Returns a descriptor for the receiver's Apple event attribute identified by the specified keyword.
///
/// - Parameter keyword: A keyword (a four-character code) that identifies the descriptor to obtain.
/// - Returns: The attribute descriptor for the specified keyword, or `nil` if an error occurs.
///
/// The receiver must be an Apple event.
- (nullable NSAppleEventDescriptor *)attributeDescriptorForKeyword:(AEKeyword)keyword;

/// Sends an Apple event.
- (nullable NSAppleEventDescriptor *)sendEventWithOptions:(NSAppleEventSendOptions)sendOptions timeout:(NSTimeInterval)timeoutInSeconds error:(NSError **)error API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// Returns whether or not the receiver is a record-like descriptor.
///
/// Record-like descriptors function as records, but may have a `descriptorType` other than `typeAERecord`,
/// such as `typeObjectSpecifier`.
@property (readonly) BOOL isRecordDescriptor API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);

/// The number of descriptors in the receiver's descriptor list.
///
/// The number of descriptors in the receiver's descriptor list (possibly 0); returns 0 if an error occurs.
@property (readonly) NSInteger numberOfItems;

/// Inserts a descriptor at the specified (one-based) position in the receiving descriptor list, replacing the existing descriptor, if any, at that position.
///
/// - Parameters:
///   - descriptor: The descriptor to insert in the receiver. Specifying an index of 0 or count + 1 causes appending to the end of the list.
///   - index: 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.
- (void)insertDescriptor:(NSAppleEventDescriptor *)descriptor atIndex:(NSInteger)index;

/// Returns the descriptor at the specified (one-based) position in the receiving descriptor list.
///
/// - Parameter index: The one-based descriptor list position of the descriptor to return.
/// - Returns: The descriptor from the specified position (one-based) in the descriptor list, or `nil` if the specified descriptor cannot be obtained.
- (nullable NSAppleEventDescriptor *)descriptorAtIndex:(NSInteger)index;

/// Removes the descriptor at the specified (one-based) position in the receiving descriptor list.
///
/// - Parameter index: 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.
- (void)removeDescriptorAtIndex:(NSInteger)index;

/// Adds a descriptor, identified by a keyword, to the receiver.
///
/// - Parameters:
///   - descriptor: The descriptor to add to the receiver.
///   - keyword: 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.
- (void)setDescriptor:(NSAppleEventDescriptor *)descriptor forKeyword:(AEKeyword)keyword;

/// Returns the receiver's descriptor for the specified keyword.
///
/// - Parameter keyword: A keyword (a four-character code) that identifies the descriptor to obtain.
/// - Returns: A descriptor for the specified keyword, or `nil` if an error occurs.
- (nullable NSAppleEventDescriptor *)descriptorForKeyword:(AEKeyword)keyword;

/// Removes the receiver's descriptor identified by the specified keyword.
///
/// - Parameter 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.
- (void)removeDescriptorWithKeyword:(AEKeyword)keyword;

/// Returns the keyword for the descriptor at the specified (one-based) position in the receiver.
///
/// - Parameter index: The one-based descriptor list position of the descriptor to get the keyword for.
/// - Returns: The keyword (a four-character code) for the descriptor at the one-based location specified by `index`, or 0 if an error occurs.
- (AEKeyword)keywordForDescriptorAtIndex:(NSInteger)index;

/// Returns a descriptor obtained by coercing the receiver to the specified type.
///
/// - Parameter descriptorType: The descriptor type to coerce the receiver to.
/// - Returns: A descriptor of the specified type, or `nil` if an error occurs.
- (nullable NSAppleEventDescriptor *)coerceToDescriptorType:(DescType)descriptorType;

@end

NS_HEADER_AUDIT_END(nullability, sendability)
