Gets a copy of the data for a specified Apple event parameter from an Apple event or an Apple event record.
SDK
- macOS 10.0+
Framework
- Core Services
Declaration
Parameters
theAppleEvent
A pointer to the Apple event to get the parameter data from.
theAEKeyword
The keyword that specifies the desired Apple event parameter. Some keyword constants are described in Keyword Parameter Constants.
desiredType
The desired descriptor type for the copied data. For a list of AppleScript’s predefined descriptor types, see Descriptor Type Constants.
If the descriptor specified by the
the
parameter is not of the desired type,AEKeyword AEGet
attempts to coerce the data to this type. However, if the desired type isParam Ptr type
, no coercion is performed.Wild Card On return, you can determine the actual descriptor type by examining the
type
parameter.Code typeCode
A pointer to a descriptor type. On return, specifies the descriptor type of the data pointed to by
data
. The returned type is either the same as the type specified by thePtr desired
parameter or, if the desired type was type wildcard, the true type of the descriptor. SpecifyType NULL
if you do not care about this return value. For a list of AppleScript’s predefined descriptor types, see Descriptor Type Constants.dataPtr
A pointer to a buffer, local variable, or other storage location created and disposed of by your application. The size in bytes must be at least as large as the value you pass in the
maximum
parameter. On return, contains the parameter data. SpecifySize NULL
if you do not care about this return value.maximumSize
The maximum length, in bytes, of the expected Apple event parameter data. The
AEGet
function will not return more data than you specify in this parameter.Param Ptr actualSize
A pointer to a variable of type
Size
. On return, the length, in bytes, of the data for the specified Apple event parameter. If this value is larger than the value you passed in themaximum
parameter, the buffer pointed to bySize data
was not large enough to contain all of the data for the parameter, thoughPtr AEGet
does not write beyond the end of the buffer. If the buffer was too small, you can resize it and callParam Ptr AEGet
again. SpecifyParam Ptr NULL
if you do not care about this return value.
Return Value
A result code. See Result Codes.
Discussion
You should use this function only to extract data from value descriptors such as type
.
Because this function allows you to specify a desired type, it can result in coercion. When used correctly, this has the positive effect of returning the data in the desired format. However, it can have side effects you may not be expecting, such as the overhead of calls to coercion handlers. See also the Version Notes section below for possible problems with coercion.
To get Apple event parameter data for your application to use directly, call AEGet
. To get a descriptor for an Apple event parameter to pass on to another Apple Event Manager routine, call AEGet
.
Before calling AEGet
, you can call the AESize
function to determine a size for the data
buffer. However, unless you specify type
for the desired
parameter, AEGet
may coerce the data, which may cause the size of the data to change.
In some cases, you may get improved efficiency extracting information from an Apple event with the AEGet
function.
Version-Notes
Thread safe starting in OS X v10.2.
If the actual parameter you are getting with AEGet
is a record, AEGet
will erroneously allow you to get the parameter as any type at all, when it really should allow only type
, type
, or type
. For other types, it will place raw record data into the designated buffer. With AppleScript 1.1.2, it would then return err
, as expected. With AppleScript 1.3 and later, however, it returns no
.
You can work around this problem by checking the returned parameter from any call to AEGet
. If the source type is type
and the type you asked for was anything other than type
, type
, or type
, you should assume the coercion failed.