--- title: AEBuildAppleEvent framework: Core Services role: symbol role_heading: Function platforms: [macOS 10.0+] path: coreservices/1573757-aebuildappleevent --- # AEBuildAppleEvent Constructs an entire Apple event in a single call. ## Declaration ```occ OSStatus AEBuildAppleEvent(AEEventClass theClass, AEEventID theID, DescType addressType, const void *addressData, Size addressLength, SInt16 returnID, SInt32 transactionID, AppleEvent *result, AEBuildError *error, const char *paramsFmt, ...); ``` ## Parameters - `theClass`: The event class for the resulting Apple event. See [doc://com.apple.documentation/documentation/coreservices/aeeventclass](coreservices/aeeventclass.md). - `theID`: The event id for the resulting Apple event. See [doc://com.apple.documentation/documentation/coreservices/aeeventid](coreservices/aeeventid.md). - `addressType`: The address type for the addressing information described in the next two parameters: usually one of `typeApplSignature`, `typeProcessSerialNumber`, or `typeKernelProcessID`. See [doc://com.apple.documentation/documentation/coreservices/desctype](coreservices/desctype.md). - `addressData`: A pointer to the address information. - `addressLength`: The number of bytes pointed to by the `addressData` parameter. - `returnID`: The return ID for the created Apple event. 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 for this Apple event. A transaction is a sequence of Apple events that are sent back and forth between the 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 the `kAnyTransactionID` constant if the Apple event is not one of a series of interdependent Apple events. - `result`: A pointer to a descriptor where the resulting descriptor should be stored. See [doc://com.apple.documentation/documentation/coreservices/appleevent](coreservices/appleevent.md) for a description of the data type. - `error`: A pointer to an `AEBuildError` structure where additional information about any errors that occur will be saved. This is an optional parameter and you can pass `NULL` if this information is not required. See [doc://com.apple.documentation/documentation/coreservices/aebuilderror](coreservices/aebuilderror.md) for a description of the data type. - `paramsFmt`: An AEBuild format string describing the AppleEvent record to be created. The format of these strings is described in Technical Note TN2106, [link-1670417](link-1670417.md). That technote also describes possible error return codes for syntax errors in the format string. ## Return Value A numeric result code indicating the success of the call. A value of `AEBuildSyntaxNoErr` (zero) means the call succeeded. You can use the `error` parameter to discover information about other errors. See [Result Codes](../applicationservices/apple_event_manager.md). ## Discussion **IMPORTANT:** Following the parameters described above, the `AEBuildAppleEvent` function takes a variable number of parameters as specified by the format string provided in the `paramsFmt` parameter. This function and related “AEBuild” routines (including [AEBuildDesc](1573758-aebuilddesc.md) and [AEBuildParameters](1573755-aebuildparameters.md), and the variable-argument versions, [vAEBuildAppleEvent](1441729-vaebuildappleevent.md), [vAEBuildDesc](1446775-vaebuilddesc.md), and [vAEBuildParameters](1448040-vaebuildparameters.md)) provide a very simple translation service for converting specially formatted strings into complex Apple event descriptors. Normally, creating complex Apple event descriptors requires a large number of calls to Apple event Manager routines to build up the descriptor piece by piece. The `AEBuildAppleEvent` function and related routines allow you to consolidate all of the calls required to construct a complex Apple event descriptor into a single system call that creates the desired structure as directed by a format string that you provide. In many ways, the AEBuild routines are very much like the standard C library's `printf` suite of routines. The syntax for the format string that you provide is very simple and allows for the substitution of data items into the Apple event descriptors being created. The `AEBuildAppleEvent` function is similar to [AECreateAppleEvent](1448525-aecreateappleevent.md), but in addition to creating the Apple event, it also constructs the parameters for the event from the last three arguments. You can use `AEBuildAppleEvent` to build an entire Apple event, or [AEBuildParameters](1573755-aebuildparameters.md) to add additional parameters to an existing Apple event. The syntax of the formatting string for an entire Apple event (as passed to `AEBuildAppleEvent`) is almost identical to that used to represent the contents of an Apple event, without the curly braces. The event is defined as a sequence of name-value pairs, with optional parameters preceded with a tilde (~) character. The syntax is described in Technical Note TN2106, [AEBuild*, AEPrint*, and Friends](../link-1670417.md). It is important to note that the identifier for the direct parameter in an Apple event, specified by the constant `keyDirectObject`, is four minus signs (`'----'`). The minus sign has special meaning in AEBuild strings, and it should always be enclosed in single quotes when it is used to identify the direct parameter for an Apple event in a descriptor string. ### Version-Notes Prior to OS X version 10.3, `AEBuildAppleEvent` would fail if you supplied a data parameter with size greater than 32767 bytes. ## See Also ### Creating Apple Event Structures in Memory - [AEBuildDesc](1573758-aebuilddesc.md) - [AEBuildParameters](1573755-aebuildparameters.md) - [AEPrintDescToHandle](1445158-aeprintdesctohandle.md) - [vAEBuildAppleEvent](1441729-vaebuildappleevent.md) - [vAEBuildDesc](1446775-vaebuilddesc.md) - [vAEBuildParameters](1448040-vaebuildparameters.md)