1 {
2 File: AE/AEDataModel.h
3
4 Contains: AppleEvent Data Model Interfaces.
5
6
7
8 Copyright: � 1996-2008 by Apple Computer, Inc., all rights reserved
9
10 Bugs?: For bug reports, consult the following page on
11 the World Wide Web:
12
13 http://bugs.freepascal.org
14
15 }
16 { Pascal Translation Updated: Gale R Paeper, <gpaeper@empirenet.com>, July 2018 }
17
18 {
19 Modified for use with Free Pascal
20 Version 308
21 Please report any bugs to <gpc@microbizz.nl>
22 }
23
24 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
25 {$mode macpas}
26 {$modeswitch cblocks}
27 {$packenum 1}
28 {$macro on}
29 {$inline on}
30 {$calling mwpascal}
31
32 unit AEDataModel;
33 interface
34 {$setc UNIVERSAL_INTERFACES_VERSION := $0400}
35 {$setc GAP_INTERFACES_VERSION := $0308}
36
37 {$ifc not defined USE_CFSTR_CONSTANT_MACROS}
38 {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
39 {$endc}
40
41 {$ifc defined CPUPOWERPC and defined CPUI386}
42 {$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
43 {$endc}
44 {$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
45 {$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
46 {$endc}
47
48 {$ifc not defined __ppc__ and defined CPUPOWERPC32}
49 {$setc __ppc__ := 1}
50 {$elsec}
51 {$setc __ppc__ := 0}
52 {$endc}
53 {$ifc not defined __ppc64__ and defined CPUPOWERPC64}
54 {$setc __ppc64__ := 1}
55 {$elsec}
56 {$setc __ppc64__ := 0}
57 {$endc}
58 {$ifc not defined __i386__ and defined CPUI386}
59 {$setc __i386__ := 1}
60 {$elsec}
61 {$setc __i386__ := 0}
62 {$endc}
63 {$ifc not defined __x86_64__ and defined CPUX86_64}
64 {$setc __x86_64__ := 1}
65 {$elsec}
66 {$setc __x86_64__ := 0}
67 {$endc}
68 {$ifc not defined __arm__ and defined CPUARM}
69 {$setc __arm__ := 1}
70 {$elsec}
71 {$setc __arm__ := 0}
72 {$endc}
73 {$ifc not defined __arm64__ and defined CPUAARCH64}
74 {$setc __arm64__ := 1}
75 {$elsec}
76 {$setc __arm64__ := 0}
77 {$endc}
78
79 {$ifc defined cpu64}
80 {$setc __LP64__ := 1}
81 {$elsec}
82 {$setc __LP64__ := 0}
83 {$endc}
84
85
86 {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
87 {$error Conflicting definitions for __ppc__ and __i386__}
88 {$endc}
89
90 {$ifc defined __ppc__ and __ppc__}
91 {$setc TARGET_CPU_PPC := TRUE}
92 {$setc TARGET_CPU_PPC64 := FALSE}
93 {$setc TARGET_CPU_X86 := FALSE}
94 {$setc TARGET_CPU_X86_64 := FALSE}
95 {$setc TARGET_CPU_ARM := FALSE}
96 {$setc TARGET_CPU_ARM64 := FALSE}
97 {$setc TARGET_OS_MAC := TRUE}
98 {$setc TARGET_OS_IPHONE := FALSE}
99 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
100 {$setc TARGET_OS_EMBEDDED := FALSE}
101 {$elifc defined __ppc64__ and __ppc64__}
102 {$setc TARGET_CPU_PPC := FALSE}
103 {$setc TARGET_CPU_PPC64 := TRUE}
104 {$setc TARGET_CPU_X86 := FALSE}
105 {$setc TARGET_CPU_X86_64 := FALSE}
106 {$setc TARGET_CPU_ARM := FALSE}
107 {$setc TARGET_CPU_ARM64 := FALSE}
108 {$setc TARGET_OS_MAC := TRUE}
109 {$setc TARGET_OS_IPHONE := FALSE}
110 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
111 {$setc TARGET_OS_EMBEDDED := FALSE}
112 {$elifc defined __i386__ and __i386__}
113 {$setc TARGET_CPU_PPC := FALSE}
114 {$setc TARGET_CPU_PPC64 := FALSE}
115 {$setc TARGET_CPU_X86 := TRUE}
116 {$setc TARGET_CPU_X86_64 := FALSE}
117 {$setc TARGET_CPU_ARM := FALSE}
118 {$setc TARGET_CPU_ARM64 := FALSE}
119 {$ifc defined iphonesim}
120 {$setc TARGET_OS_MAC := FALSE}
121 {$setc TARGET_OS_IPHONE := TRUE}
122 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
123 {$elsec}
124 {$setc TARGET_OS_MAC := TRUE}
125 {$setc TARGET_OS_IPHONE := FALSE}
126 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
127 {$endc}
128 {$setc TARGET_OS_EMBEDDED := FALSE}
129 {$elifc defined __x86_64__ and __x86_64__}
130 {$setc TARGET_CPU_PPC := FALSE}
131 {$setc TARGET_CPU_PPC64 := FALSE}
132 {$setc TARGET_CPU_X86 := FALSE}
133 {$setc TARGET_CPU_X86_64 := TRUE}
134 {$setc TARGET_CPU_ARM := FALSE}
135 {$setc TARGET_CPU_ARM64 := FALSE}
136 {$ifc defined iphonesim}
137 {$setc TARGET_OS_MAC := FALSE}
138 {$setc TARGET_OS_IPHONE := TRUE}
139 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
140 {$elsec}
141 {$setc TARGET_OS_MAC := TRUE}
142 {$setc TARGET_OS_IPHONE := FALSE}
143 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
144 {$endc}
145 {$setc TARGET_OS_EMBEDDED := FALSE}
146 {$elifc defined __arm__ and __arm__}
147 {$setc TARGET_CPU_PPC := FALSE}
148 {$setc TARGET_CPU_PPC64 := FALSE}
149 {$setc TARGET_CPU_X86 := FALSE}
150 {$setc TARGET_CPU_X86_64 := FALSE}
151 {$setc TARGET_CPU_ARM := TRUE}
152 {$setc TARGET_CPU_ARM64 := FALSE}
153 {$setc TARGET_OS_MAC := FALSE}
154 {$setc TARGET_OS_IPHONE := TRUE}
155 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
156 {$setc TARGET_OS_EMBEDDED := TRUE}
157 {$elifc defined __arm64__ and __arm64__}
158 {$setc TARGET_CPU_PPC := FALSE}
159 {$setc TARGET_CPU_PPC64 := FALSE}
160 {$setc TARGET_CPU_X86 := FALSE}
161 {$setc TARGET_CPU_X86_64 := FALSE}
162 {$setc TARGET_CPU_ARM := FALSE}
163 {$setc TARGET_CPU_ARM64 := TRUE}
164 {$ifc defined ios}
165 {$setc TARGET_OS_MAC := FALSE}
166 {$setc TARGET_OS_IPHONE := TRUE}
167 {$setc TARGET_OS_EMBEDDED := TRUE}
168 {$elsec}
169 {$setc TARGET_OS_MAC := TRUE}
170 {$setc TARGET_OS_IPHONE := FALSE}
171 {$setc TARGET_OS_EMBEDDED := FALSE}
172 {$endc}
173 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
174 {$elsec}
175 {$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ nor __arm64__ is defined.}
176 {$endc}
177
178 {$ifc defined __LP64__ and __LP64__ }
179 {$setc TARGET_CPU_64 := TRUE}
180 {$elsec}
181 {$setc TARGET_CPU_64 := FALSE}
182 {$endc}
183
184 {$ifc defined FPC_BIG_ENDIAN}
185 {$setc TARGET_RT_BIG_ENDIAN := TRUE}
186 {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
187 {$elifc defined FPC_LITTLE_ENDIAN}
188 {$setc TARGET_RT_BIG_ENDIAN := FALSE}
189 {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
190 {$elsec}
191 {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
192 {$endc}
193 {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
194 {$setc CALL_NOT_IN_CARBON := FALSE}
195 {$setc OLDROUTINENAMES := FALSE}
196 {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
197 {$setc OPAQUE_UPP_TYPES := TRUE}
198 {$setc OTCARBONAPPLICATION := TRUE}
199 {$setc OTKERNEL := FALSE}
200 {$setc PM_USE_SESSION_APIS := TRUE}
201 {$setc TARGET_API_MAC_CARBON := TRUE}
202 {$setc TARGET_API_MAC_OS8 := FALSE}
203 {$setc TARGET_API_MAC_OSX := TRUE}
204 {$setc TARGET_CARBON := TRUE}
205 {$setc TARGET_CPU_68K := FALSE}
206 {$setc TARGET_CPU_MIPS := FALSE}
207 {$setc TARGET_CPU_SPARC := FALSE}
208 {$setc TARGET_OS_UNIX := FALSE}
209 {$setc TARGET_OS_WIN32 := FALSE}
210 {$setc TARGET_RT_MAC_68881 := FALSE}
211 {$setc TARGET_RT_MAC_CFM := FALSE}
212 {$setc TARGET_RT_MAC_MACHO := TRUE}
213 {$setc TYPED_FUNCTION_POINTERS := TRUE}
214 {$setc TYPE_BOOL := FALSE}
215 {$setc TYPE_EXTENDED := FALSE}
216 {$setc TYPE_LONGLONG := TRUE}
217 uses MacTypes,MixedMode;
218 {$endc} {not MACOSALLINCLUDE}
219
220
221 {$ifc TARGET_OS_MAC}
222
223 {$ALIGN MAC68K}
224
225 { Apple event descriptor types }
226 const
227 typeBoolean = FourCharCode('bool');
228 typeChar = FourCharCode('TEXT'); { Deprecated, use typeUTF8Text instead. }
229
230 {
231 * The following descriptor types are deprecated due to their lack of
232 * explicit encoding or byte order definition. Please use
233 * typeUTF16ExternalRepresentation or typeUTF8Text instead. }
234 const
235 typeStyledUnicodeText = FourCharCode('sutx'); { Not implemented }
236 typeEncodedString = FourCharCode('encs'); { Not implemented }
237 typeUnicodeText = FourCharCode('utxt'); { native byte ordering, optional BOM }
238 typeCString = FourCharCode('cstr'); { MacRoman characters followed by a NULL byte }
239 typePString = FourCharCode('pstr'); { Unsigned length byte followed by MacRoman characters }
240
241 {
242 * The preferred unicode text types. In both cases, there is no explicit null termination or length byte.
243 }
244 const
245 typeUTF16ExternalRepresentation = FourCharCode('ut16'); { big-endian 16 bit unicode with optional byte-order-mark, or little-endian 16 bit unicode with required byte-order-mark. }
246 typeUTF8Text = FourCharCode('utf8'); { 8 bit unicode }
247
248 { Preferred numeric Apple event descriptor types }
249 const
250 typeSInt16 = FourCharCode('shor'); { SInt16 : signed, 16 bit integer }
251 typeUInt16 = FourCharCode('ushr'); { UInt16 : unsigned, 16 bit integer }
252 typeSInt32 = FourCharCode('long'); { SInt32 : signed, 32 bit integer }
253 typeUInt32 = FourCharCode('magn'); { UInt32 : unsigned, 32 bit integer }
254 typeSInt64 = FourCharCode('comp'); { SInt64 : signed, 64 bit integer }
255 typeUInt64 = FourCharCode('ucom'); { UInt64 : unsigned, 64 bit integer }
256 typeIEEE32BitFloatingPoint = FourCharCode('sing'); { float }
257 typeIEEE64BitFloatingPoint = FourCharCode('doub'); { double }
258 type128BitFloatingPoint = FourCharCode('ldbl');
259 typeDecimalStruct = FourCharCode('decm');
260
261 { Non-preferred Apple event descriptor types }
262 {$ifc TARGET_CPU_64}
263 { On Mac OS X 64 bit, the following types have been removed because their meaning is unclear or confusing.
264 For example, people have assumed that the appropriate data type for typeLongInteger would be long; but
265 on 64 bit 'long' is a 64 bit value and the appropriate type should be typeComp.
266
267 You should change your existing code to not use the following types, and use the more specific ones. Check
268 through your code to make sure that the datasize referenced by these types is the correct type.
269
270 type constant change to data type should be
271 ------------- --------- -------------------
272 typeSMInt typeSInt16 SInt16
273 typeShortInteger typeSInt16 SInt16
274 typeInteger typeSInt32 SInt32
275 typeLongInteger typeSInt32 SInt32
276 typeComp typeSInt64 SInt64 or Wide
277 typeSMFloat typeIEEE32BitFloatingPoint Float32
278 typeShortFloat typeIEEE32BitFloatingPoint Float32
279 typeLongFloat typeIEEE64BitFloatingPoint Float64
280
281 There is no good type on 64 bit to use for typeEntended; either change your code to pass typeIEEE64BitFloatingPoint
282 for typeExtended and live with the reduction in range or use type128BitFloatingPoint.
283
284 }
285 {$elsec} {TARGET_CPU_64}
286 { Non-preferred Apple event descriptor types }
287 typeSMInt = FourCharCode('shor');
288 typeShortInteger = FourCharCode('shor');
289 typeInteger = FourCharCode('long');
290 typeLongInteger = FourCharCode('long');
291 typeMagnitude = FourCharCode('magn');
292 typeComp = FourCharCode('comp');
293 typeSMFloat = FourCharCode('sing');
294 typeShortFloat = FourCharCode('sing');
295 typeFloat = FourCharCode('doub');
296 typeLongFloat = FourCharCode('doub');
297 typeExtended = FourCharCode('exte');
298 {$endc} {TARGET_CPU_64}
299
300 { More Apple event descriptor types }
301 const
302 typeAEList = FourCharCode('list');
303 typeAERecord = FourCharCode('reco');
304 typeAppleEvent = FourCharCode('aevt');
305 typeEventRecord = FourCharCode('evrc');
306 typeTrue = FourCharCode('true');
307 typeFalse = FourCharCode('fals');
308 typeAlias = FourCharCode('alis'); { AliasPtr, from a valid AliasHandle }
309 typeEnumerated = FourCharCode('enum');
310 typeType = FourCharCode('type'); { OSType }
311 typeAppParameters = FourCharCode('appa');
312 typeProperty = FourCharCode('prop');
313 typeFSRef = FourCharCode('fsrf'); { FSRef. Deprecated; use typeFileURL or typeBookmark data to refer to files in AppleEvents }
314 typeFileURL = FourCharCode('furl'); { a UTF-8 encoded full path, using native path separators }
315 typeBookmarkData = FourCharCode('bmrk'); { the bytes of a CFURLBookmarkData }
316 typeKeyword = FourCharCode('keyw'); { OSType }
317 typeSectionH = FourCharCode('sect');
318 typeWildCard = FourCharCode('****');
319 typeApplSignature = FourCharCode('sign'); { OSType }
320 typeQDRectangle = FourCharCode('qdrt');
321 typeFixed = FourCharCode('fixd');
322 typeProcessSerialNumber = FourCharCode('psn '); { ProcessSerialNumber }
323 typeApplicationURL = FourCharCode('aprl');
324 typeNull = FourCharCode('null'); { null or nonexistent data }
325
326 {$ifc not TARGET_CPU_64}
327 {
328 FSSpecs are deprecated on Mac OS X, and their use in AppleEvents is discouraged. You should change
329 your code to use typeFileURL or typeFileBookmark. In __LP64__ code, coercions into typeFSS is not supported,
330 and coercion from typeFSS is not guaranteed to work correctly in all cases.
331 }
332 const
333 typeFSS = FourCharCode('fss '); { FSSpec }
334
335 {$endc} {not TARGET_CPU_64}
336
337 const
338 typeCFAttributedStringRef = FourCharCode('cfas');
339 typeCFMutableAttributedStringRef = FourCharCode('cfaa');
340 typeCFStringRef = FourCharCode('cfst');
341 typeCFMutableStringRef = FourCharCode('cfms');
342 typeCFArrayRef = FourCharCode('cfar');
343 typeCFMutableArrayRef = FourCharCode('cfma');
344 typeCFDictionaryRef = FourCharCode('cfdc');
345 typeCFMutableDictionaryRef = FourCharCode('cfmd');
346 typeCFNumberRef = FourCharCode('cfnb');
347 typeCFBooleanRef = FourCharCode('cftf');
348 typeCFTypeRef = FourCharCode('cfty');
349
350 { New addressing modes for MacOS X }
351 const
352 typeKernelProcessID = FourCharCode('kpid');
353 typeMachPort = FourCharCode('port');
354
355
356 const
357 typeAuditToken = FourCharCode('tokn'); { Mac OS X 10.8, returned as keyAuditTokenAttr and is a typedef audit_token_t }
358
359 { Targeting applications by bundle ID is only available in Mac OS X 10.3 or later. }
360 const
361 typeApplicationBundleID = FourCharCode('bund');
362
363 { Keywords for Apple event attributes }
364 const
365 keyTransactionIDAttr = FourCharCode('tran'); { AETransactionID }
366 keyReturnIDAttr = FourCharCode('rtid'); { AEReturnID }
367 keyEventClassAttr = FourCharCode('evcl'); { AEEventClass }
368 keyEventIDAttr = FourCharCode('evid'); { AEEventID }
369 keyAddressAttr = FourCharCode('addr');
370 keyOptionalKeywordAttr = FourCharCode('optk');
371 keyTimeoutAttr = FourCharCode('timo'); { SInt32 }
372 keyInteractLevelAttr = FourCharCode('inte'); { this attribute is read only - will be set in AESend }
373 keyEventSourceAttr = FourCharCode('esrc'); { this attribute is read only - returned as typeShortInteger }
374 keyMissedKeywordAttr = FourCharCode('miss'); { this attribute is read only }
375 keyOriginalAddressAttr = FourCharCode('from'); { new in 1.0.1 }
376 keyAcceptTimeoutAttr = FourCharCode('actm'); { new for Mac OS X }
377 keyReplyRequestedAttr = FourCharCode('repq'); { Was a reply requested for this event - returned as typeBoolean }
378 // #if __MAC_OS_X_VERSION_MIN_REQUIRED >= 1060
379 keySenderEUIDAttr = FourCharCode('seid'); { read only, returned as typeSInt32. Will be the euid of the sender of this event. }
380 keySenderEGIDAttr = FourCharCode('sgid'); { read only, returned as typeSInt32. Will be the egid of the sender of this event. }
381 keySenderUIDAttr = FourCharCode('uids'); { read only, returned as typeSInt32. Will be the uid of the sender of this event. }
382 keySenderGIDAttr = FourCharCode('gids'); { read only, returned as typeSInt32. Will be the gid of the sender of this event. }
383 keySenderPIDAttr = FourCharCode('spid'); { read only, returned as typeSInt32. Will be the pid of the sender of this event. }
384 keySenderAuditTokenAttr = FourCharCode('tokn'); { read only, returned as an audit_token_t. Will be the audit token of the sender of this event. }
385 // #endif
386 // #if __MAC_OS_X_VERSION_MIN_REQUIRED >= 1080
387 keySenderApplescriptEntitlementsAttr = FourCharCode('entl'); { read only, an AEDesc containing opaque data representing the entitlements held by the sender. Interpreted by sandbox routines. }
388 keySenderApplicationIdentifierEntitlementAttr = FourCharCode('aiea');
389 keySenderApplicationSandboxed = FourCharCode('sssb'); { read-only, an AEDesc typeBoolean, true if the sender application was in an application sandbox }
390 keyActualSenderAuditToken = FourCharCode('acat'); { read-only, an AEDesc typeAuditToken of the acual ( possibly over-ridden ) audit token for the sender of this event }
391 // #endif
392
393 // #if defined(__MAC_10_13) && __MAC_OS_X_VERSION_MIN_REQUIRED >= __MAC_10_13
394 keyAppleEventAttributesAttr = FourCharCode('attr'); { read-only, an AEDescList of AEKeyword entries of the attributes on this event. }
395 // #endif
396
397 { These bits are specified in the keyXMLDebuggingAttr (an SInt32) }
398 const
399 kAEDebugPOSTHeader = 1 shl 0; { headers of the HTTP post we sent - typeChar }
400 kAEDebugReplyHeader = 1 shl 1; { headers returned by the server }
401 kAEDebugXMLRequest = 1 shl 2; { the XML request we sent }
402 kAEDebugXMLResponse = 1 shl 3; { the XML reply from the server }
403 kAEDebugXMLDebugAll = $FFFFFFFF; { everything! }
404
405 { These values can be added as a parameter to the direct object of a
406 SOAP message to specify the serialization schema. If not
407 specified, kSOAP1999Schema is the default. These should be added as
408 typeType. }
409 const
410 kSOAP1999Schema = FourCharCode('ss99');
411 kSOAP2001Schema = FourCharCode('ss01');
412
413 const
414 { outgoing event attributes }
415 keyUserNameAttr = FourCharCode('unam');
416 keyUserPasswordAttr = FourCharCode('pass'); { not sent with the event }
417 keyDisableAuthenticationAttr = FourCharCode('auth'); { When present and with a non zero value (that is, false, or integer 0), }
418 { AESend will not authenticate the user. If not present, or with a non-zero}
419 { value, AESend will prompt for authentication information from the user if the interaction level allows. }
420 keyXMLDebuggingAttr = FourCharCode('xdbg'); { a bitfield of specifying which XML debugging data is to be returned with the event }
421 { Event class / id }
422 kAERPCClass = FourCharCode('rpc '); { for outgoing XML events }
423 kAEXMLRPCScheme = FourCharCode('RPC2'); { event ID: event should be sent to an XMLRPC endpoint }
424 kAESOAPScheme = FourCharCode('SOAP'); { event ID: event should be sent to a SOAP endpoint }
425 kAESharedScriptHandler = FourCharCode('wscp'); { event ID: handler for incoming XML requests }
426 { these parameters exist as part of the direct object of the event for both incoming and outgoing requests }
427 keyRPCMethodName = FourCharCode('meth'); { name of the method to call }
428 keyRPCMethodParam = FourCharCode('parm'); { the list (or structure) of parameters }
429 keyRPCMethodParamOrder = FourCharCode('/ord'); { if a structure, the order of parameters (a list) }
430 { when keyXMLDebugginAttr so specifies, these additional parameters will be part of the reply. }
431 keyAEPOSTHeaderData = FourCharCode('phed'); { what we sent to the server }
432 keyAEReplyHeaderData = FourCharCode('rhed'); { what the server sent to us }
433 keyAEXMLRequestData = FourCharCode('xreq'); { what we sent to the server }
434 keyAEXMLReplyData = FourCharCode('xrep'); { what the server sent to us }
435 { additional parameters that can be specified in the direct object of the event }
436 keyAdditionalHTTPHeaders = FourCharCode('ahed'); { list of additional HTTP headers (a list of 2 element lists) }
437 keySOAPAction = FourCharCode('sact'); { the SOAPAction header (required for SOAP messages) }
438 keySOAPMethodNameSpace = FourCharCode('mspc'); { Optional namespace (defaults to m:) }
439 keySOAPMethodNameSpaceURI = FourCharCode('mspu'); { Required namespace URI }
440 keySOAPSchemaVersion = FourCharCode('ssch'); { Optional XML Schema version, defaults to kSOAP1999Schama }
441
442 {
443 When serializing AERecords as SOAP structures, it is possible
444 to specify the namespace and type of the structure. To do this,
445 add a keySOAPStructureMetaData record to the top level of the
446 record to be serialized. If present, this will be used to specify
447 the structure namespace. This will produce a structure elment that
448 looks like:
449
450 <myStruct
451 xmlns:myNamespace="http://myUri.org/xsd",
452 xsi:type="myNamespace:MyStructType">
453 ...
454 </myStruct>
455
456 }
457 const
458 keySOAPStructureMetaData = FourCharCode('/smd');
459 keySOAPSMDNamespace = FourCharCode('ssns'); { "myNamespace"}
460 keySOAPSMDNamespaceURI = FourCharCode('ssnu'); { "http://myUri.org/xsd"}
461 keySOAPSMDType = FourCharCode('sstp'); { "MyStructType"}
462
463 {
464 * Web Services Proxy support. Available only on Mac OS X 10.2 or later.
465 * These constants should be added as attributes on the event that is
466 * being sent (not part of the direct object.)
467 }
468 const
469 { Automatically configure the proxy based on System Configuration }
470 kAEUseHTTPProxyAttr = FourCharCode('xupr'); { a typeBoolean. Defaults to true.}
471 { manually specify the proxy host and port. }
472 kAEHTTPProxyPortAttr = FourCharCode('xhtp'); { a typeSInt32}
473 kAEHTTPProxyHostAttr = FourCharCode('xhth'); { a typeChar}
474
475 {
476 * Web Services SOCKS support. kAEUseSocksAttr is a boolean that
477 * specifies whether to automatically configure SOCKS proxies by
478 * querying System Configuration.
479 }
480 const
481 kAESocks4Protocol = 4;
482 kAESocks5Protocol = 5;
483
484 const
485 kAEUseSocksAttr = FourCharCode('xscs'); { a typeBoolean. Defaults to true.}
486 { This attribute specifies a specific SOCKS protocol to be used }
487 kAESocksProxyAttr = FourCharCode('xsok'); { a typeSInt32}
488 { if version >= 4 }
489 kAESocksHostAttr = FourCharCode('xshs'); { a typeChar}
490 kAESocksPortAttr = FourCharCode('xshp'); { a typeSInt32}
491 kAESocksUserAttr = FourCharCode('xshu'); { a typeChar}
492 { if version >= 5 }
493 kAESocksPasswordAttr = FourCharCode('xshw'); { a typeChar}
494
495
496 { Constants used for specifying the factoring of AEDescLists. }
497 const
498 kAEDescListFactorNone = 0;
499 kAEDescListFactorType = 4;
500 kAEDescListFactorTypeAndSize = 8;
501
502 { Constants used creating an AppleEvent }
503 const
504 { Constant for the returnID param of AECreateAppleEvent }
505 kAutoGenerateReturnID = -1; { AECreateAppleEvent will generate a session-unique ID }
506 { Constant for transaction IDs }
507 kAnyTransactionID = 0; { no transaction is in use }
508
509 { Apple event manager data types }
510 type
511 DescType = ResType;
512 DescTypePtr = ^DescType;
513 AEKeyword = FourCharCode;
514 AEKeywordPtr = ^AEKeyword;
515 {$ifc OPAQUE_TOOLBOX_STRUCTS}
516 AEDataStorage = ^OpaqueAEDataStorage; { an opaque type }
517 OpaqueAEDataStorage = record end;
518 AEDataStoragePtr = ^AEDataStorage; { when a var xx:AEDataStorage parameter can be nil, it is changed to xx: AEDataStoragePtr }
519 {$elsec}
520 AEDataStorage = Handle;
521 {$endc} {OPAQUE_TOOLBOX_STRUCTS}
522
523 AEDescPtr = ^AEDesc;
524 AEDesc = record
525 descriptorType: DescType;
526 { No alignment dummy here for 64 bit, also compiled with m68k alignment in C! }
527 dataHandle: AEDataStorage;
528 end;
529 type
530 AEKeyDescPtr = ^AEKeyDesc;
531 AEKeyDesc = record
532 descKey: AEKeyword;
533 descContent: AEDesc;
534 end;
535 { a list of AEDesc's is a special kind of AEDesc }
536
537 type
538 AEDescList = AEDesc;
539 AEDescListPtr = ^AEDescList;
540 { AERecord is a list of keyworded AEDesc's }
541 type
542 AERecord = AEDescList;
543 AERecordPtr = ^AERecord;
544 { an AEDesc which contains address data }
545 type
546 AEAddressDesc = AEDesc;
547 AEAddressDescPtr = ^AEAddressDesc;
548 { an AERecord that contains an AppleEvent, and related data types }
549 type
550 AppleEvent = AERecord;
551 AppleEventPtr = ^AppleEvent;
552 AEReturnID = SInt16;
553 AETransactionID = SInt32;
554 AEEventClass = FourCharCode;
555 AEEventID = FourCharCode;
556 AEArrayType = SInt8;
557 const
558 kAEDataArray = 0;
559 kAEPackedArray = 1;
560 kAEDescArray = 3;
561 kAEKeyDescArray = 4;
562
563
564 const
565 kAEHandleArray = 2;
566
567 type
568 AEArrayDataPtr = ^AEArrayData;
569 AEArrayData = record
570 case SInt16 of
571 0: (
572 kAEDataArray: array [0..0] of SInt16;
573 );
574 1: (
575 kAEPackedArray: SInt8;
576 );
577 2: (
578 kAEHandleArray: array [0..0] of Handle;
579 );
580 3: (
581 kAEDescArray: array [0..0] of AEDesc;
582 );
583 4: (
584 kAEKeyDescArray: array [0..0] of AEKeyDesc;
585 );
586 end;
587 type
588 AEArrayDataPointer = ^AEArrayData;
589 AEArrayDataPointerPtr = ^AEArrayDataPointer;
590 {*************************************************************************
591 These constants are used by AEMach and AEInteraction APIs. They are not
592 strictly part of the data format, but are declared here due to layering.
593 *************************************************************************}
594 type
595 AESendPriority = SInt16;
596 const
597 kAENormalPriority = $00000000; { post message at the end of the event queue }
598 kAEHighPriority = $00000001; { post message at the front of the event queue (same as nAttnMsg) }
599
600
601 type
602 AESendMode = SInt32;
603 const
604 kAENoReply = $00000001; { sender doesn't want a reply to event }
605 kAEQueueReply = $00000002; { sender wants a reply but won't wait }
606 kAEWaitReply = $00000003; { sender wants a reply and will wait }
607 kAEDontReconnect = $00000080; { don't reconnect if there is a sessClosedErr from PPCToolbox }
608 kAEWantReceipt = $00000200; { (nReturnReceipt) sender wants a receipt of message }
609 kAENeverInteract = $00000010; { server should not interact with user }
610 kAECanInteract = $00000020; { server may try to interact with user }
611 kAEAlwaysInteract = $00000030; { server should always interact with user where appropriate }
612 kAECanSwitchLayer = $00000040; { interaction may switch layer }
613 kAEDontRecord = $00001000; { don't record this event - available only in vers 1.0.1 and greater }
614 kAEDontExecute = $00002000; { don't send the event for recording - available only in vers 1.0.1 and greater }
615 kAEProcessNonReplyEvents = $00008000; { allow processing of non-reply events while awaiting synchronous AppleEvent reply }
616 kAEDoNotAutomaticallyAddAnnotationsToEvent = $00010000; { if set, don't automatically add any sandbox or other annotations to the event }
617
618
619 { Constants for timeout durations }
620 const
621 kAEDefaultTimeout = -1; { timeout value determined by AEM }
622 kNoTimeOut = -2; { wait until reply comes back, however long it takes }
623
624
625 {*************************************************************************
626 These calls are used to set up and modify the coercion dispatch table.
627 *************************************************************************}
628 type
constnull629 AECoerceDescProcPtr = function( const (*var*) fromDesc: AEDesc; toType: DescType; handlerRefcon: SRefCon; var toDesc: AEDesc ): OSErr;
typeCodenull630 AECoercePtrProcPtr = function( typeCode: DescType; dataPtr: {const} UnivPtr; dataSize: Size; toType: DescType; handlerRefcon: SRefCon; var result: AEDesc ): OSErr;
631 AECoerceDescUPP = UniversalProcPtr;
632 AECoercePtrUPP = UniversalProcPtr;
633 {
634 * NewAECoerceDescUPP()
635 *
636 * Availability:
637 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
638 * CarbonLib: in CarbonLib 1.0 and later
639 * Non-Carbon CFM: available as macro/inline
640 }
NewAECoerceDescUPPnull641 function NewAECoerceDescUPP( userRoutine: AECoerceDescProcPtr ): AECoerceDescUPP; external name '_NewAECoerceDescUPP';
642 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
643
644 {
645 * NewAECoercePtrUPP()
646 *
647 * Availability:
648 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
649 * CarbonLib: in CarbonLib 1.0 and later
650 * Non-Carbon CFM: available as macro/inline
651 }
NewAECoercePtrUPPnull652 function NewAECoercePtrUPP( userRoutine: AECoercePtrProcPtr ): AECoercePtrUPP; external name '_NewAECoercePtrUPP';
653 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
654
655 {
656 * DisposeAECoerceDescUPP()
657 *
658 * Availability:
659 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
660 * CarbonLib: in CarbonLib 1.0 and later
661 * Non-Carbon CFM: available as macro/inline
662 }
663 procedure DisposeAECoerceDescUPP( userUPP: AECoerceDescUPP ); external name '_DisposeAECoerceDescUPP';
664 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
665
666 {
667 * DisposeAECoercePtrUPP()
668 *
669 * Availability:
670 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
671 * CarbonLib: in CarbonLib 1.0 and later
672 * Non-Carbon CFM: available as macro/inline
673 }
674 procedure DisposeAECoercePtrUPP( userUPP: AECoercePtrUPP ); external name '_DisposeAECoercePtrUPP';
675 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
676
677 {
678 * InvokeAECoerceDescUPP()
679 *
680 * Availability:
681 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
682 * CarbonLib: in CarbonLib 1.0 and later
683 * Non-Carbon CFM: available as macro/inline
684 }
InvokeAECoerceDescUPPnull685 function InvokeAECoerceDescUPP( const (*var*) fromDesc: AEDesc; toType: DescType; handlerRefcon: SRefCon; var toDesc: AEDesc; userUPP: AECoerceDescUPP ): OSErr; external name '_InvokeAECoerceDescUPP';
686 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
687
688 {
689 * InvokeAECoercePtrUPP()
690 *
691 * Availability:
692 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
693 * CarbonLib: in CarbonLib 1.0 and later
694 * Non-Carbon CFM: available as macro/inline
695 }
InvokeAECoercePtrUPPnull696 function InvokeAECoercePtrUPP( typeCode: DescType; dataPtr: {const} UnivPtr; dataSize: Size; toType: DescType; handlerRefcon: SRefCon; var result: AEDesc; userUPP: AECoercePtrUPP ): OSErr; external name '_InvokeAECoercePtrUPP';
697 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
698
699 { a AECoercionHandlerUPP is by default a AECoerceDescUPP. If you are registering a
700 Ptr based coercion handler you will have to add a cast to AECoerceDescUPP from
701 your AECoercePtrUPP type. A future release of the interfaces will fix this by
702 introducing seperate Desc and Ptr coercion handler installation/remove/query routines. }
703 type
704 AECoercionHandlerUPP = AECoerceDescUPP;
705 {
706 * AEInstallCoercionHandler()
707 *
708 * Summary:
709 * Installs a coercion handler in either the application or system
710 * coercion handler dispatch table.
711 *
712 * Discussion:
713 * Before using AEInstallCoercionHandler to install a handler for a
714 * particular descriptor type, you can use the AEGetCoercionHandler
715 * function to determine whether the table already contains a
716 * coercion handler for that type.
717 * Version Notes
718 * See the Version Notes section for the AECoercePtr function for
719 * information on when to use descriptor-based versus pointer-based
720 * coercion handlers starting in Mac OS X version 10.2.
721 * Your application should not install a coercion handler in a
722 * system coercion handler dispatch table with the goal that the
723 * handler will get called when other applications perform coercions
724 * - this won't work in Mac OS X. For more information, see "Writing
725 * and Installing Coercion Handlers" in Apple Events Programming
726 * Guide.
727 *
728 * Mac OS X threading:
729 * Thread safe since version 10.2
730 *
731 * Parameters:
732 *
733 * fromType:
734 * The descriptor type of the data coerced by the handler.
735 *
736 * toType:
737 * The descriptor type of the resulting data.
738 * If there was already an entry in the specified coercion handler
739 * table for the same source descriptor type and result descriptor
740 * type, the existing entry is replaced.
741 *
742 * handler:
743 * A universal procedure pointer to the coercion handler function
744 * to install.
745 *
746 * handlerRefcon:
747 * A reference constant. The Apple Event Manager passes this value
748 * to the handler each time it calls it. If your handler doesn't
749 * require a reference constant, pass 0 for this parameter.
750 *
751 * fromTypeIsDesc:
752 * Specifies the form of the data to coerce. Pass TRUE if the
753 * coercion handler expects the data as a descriptor or FALSE if
754 * the coercion handler expects a pointer to the data. The Apple
755 * Event Manager can provide a pointer to data more efficiently
756 * than it can provide a descriptor, so all coercion functions
757 * should accept a pointer to data if possible.
758 *
759 * isSysHandler:
760 * Specifies the coercion table to add the handler to. Pass TRUE
761 * to add the handler to the system coercion table or FALSE to add
762 * the handler to your application's coercion table. Use of the
763 * system coercion table is not recommended.
764 *
765 * Availability:
766 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
767 * CarbonLib: in CarbonLib 1.0 and later
768 * Non-Carbon CFM: in InterfaceLib 7.1 and later
769 }
AEInstallCoercionHandlernull770 function AEInstallCoercionHandler( fromType: DescType; toType: DescType; handler: AECoercionHandlerUPP; handlerRefcon: SRefCon; fromTypeIsDesc: Boolean; isSysHandler: Boolean ): OSErr; external name '_AEInstallCoercionHandler';
771 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
772
773
774 {
775 * AERemoveCoercionHandler()
776 *
777 * Discussion:
778 * Removes a coercion handler from a coercion handler dispatch table.
779 *
780 * Mac OS X threading:
781 * Thread safe since version 10.2
782 *
783 * Parameters:
784 *
785 * fromType:
786 * The descriptor type of the data coerced by the handler.
787 *
788 * toType:
789 * The descriptor type of the resulting data.
790 *
791 * handler:
792 * A universal procedure pointer to the coercion handler to
793 * remove. Although the parameters fromType and toType are
794 * sufficient to identify the handler, you can identify the
795 * handler explicitly as a safeguard. If you pass NULL for this
796 * parameter, the Apple Event Manager relies solely on the event
797 * class and event ID to identify the handler.
798 *
799 * isSysHandler:
800 * Specifies the coercion table to remove the handler from. Pass
801 * TRUE to remove the handler from the system coercion table or
802 * FALSE to remove the handler from your application's coercion
803 * table. Use of the system coercion table is not recommended.
804 *
805 * Availability:
806 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
807 * CarbonLib: in CarbonLib 1.0 and later
808 * Non-Carbon CFM: in InterfaceLib 7.1 and later
809 }
AERemoveCoercionHandlernull810 function AERemoveCoercionHandler( fromType: DescType; toType: DescType; handler: AECoercionHandlerUPP; isSysHandler: Boolean ): OSErr; external name '_AERemoveCoercionHandler';
811 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
812
813
814 {
815 * AEGetCoercionHandler()
816 *
817 * Discussion:
818 * Gets the coercion handler for a specified descriptor type.
819 *
820 * Mac OS X threading:
821 * Thread safe since version 10.2
822 *
823 * Parameters:
824 *
825 * fromType:
826 * The descriptor type of the data coerced by the handler.
827 *
828 * toType:
829 * The descriptor type of the resulting data.
830 *
831 * handler:
832 * A universal procedure pointer. On return, a pointer to the
833 * specified handler, if a coercion table entry exists that
834 * exactly matches the values supplied in the parameters fromType
835 * and toType. See AECoercionHandlerUPP.
836 *
837 * handlerRefcon:
838 * A pointer to a reference constant. On return, the reference
839 * constant from the coercion table entry for the specified
840 * coercion handler. The Apple Event Manager passes this reference
841 * constant to the handler each time it calls the handler. The
842 * reference constant may have a value of 0.
843 *
844 * fromTypeIsDesc:
845 * A pointer to a Boolean value. The AEGetCoercionHandler function
846 * returns a value of TRUE in this parameter if the coercion
847 * handler expects the data as a descriptor or FALSE, if the
848 * coercion handler expects a pointer to the data.
849 *
850 * isSysHandler:
851 * Specifies the coercion table to get the handler from. Pass TRUE
852 * to get the handler from the system coercion table or FALSE to
853 * get the handler from your application's coercion table. Use of
854 * the system coercion table is not recommended.
855 *
856 * Availability:
857 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
858 * CarbonLib: in CarbonLib 1.0 and later
859 * Non-Carbon CFM: in InterfaceLib 7.1 and later
860 }
AEGetCoercionHandlernull861 function AEGetCoercionHandler( fromType: DescType; toType: DescType; var handler: AECoercionHandlerUPP; var handlerRefcon: SRefCon; var fromTypeIsDesc: Boolean; isSysHandler: Boolean ): OSErr; external name '_AEGetCoercionHandler';
862 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
863
864
865 {*************************************************************************
866 The following calls provide for a coercion interface.
867 *************************************************************************}
868 {
869 * AECoercePtr()
870 *
871 * Discussion:
872 * Coerces data to a desired descriptor type and creates a
873 * descriptor containing the newly coerced data.
874 *
875 * Mac OS X threading:
876 * Thread safe since version 10.2
877 *
878 * Parameters:
879 *
880 * typeCode:
881 * The descriptor type of the source data.
882 *
883 * dataPtr:
884 * A pointer to the data to coerce.
885 *
886 * dataSize:
887 * The length, in bytes, of the data to coerce.
888 *
889 * toType:
890 * The desired descriptor type of the resulting descriptor.
891 *
892 * result:
893 * A pointer to a descriptor. On successful return, a descriptor
894 * containing the coerced data and matching the descriptor type
895 * specified in toType. On error, a null descriptor. If the
896 * function returns successfully, your application should call the
897 * AEDisposeDesc function to dispose of the resulting descriptor
898 * after it has finished using it. See AEDesc.
899 *
900 * Availability:
901 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
902 * CarbonLib: in CarbonLib 1.0 and later
903 * Non-Carbon CFM: in InterfaceLib 7.1 and later
904 }
AECoercePtrnull905 function AECoercePtr( typeCode: DescType; dataPtr: {const} UnivPtr; dataSize: Size; toType: DescType; var result: AEDesc ): OSErr; external name '_AECoercePtr';
906 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
907
908
909 {
910 * AECoerceDesc()
911 *
912 * Discussion:
913 * Coerces the data in a descriptor to another descriptor type and
914 * creates a descriptor containing the newly coerced data.
915 *
916 * Mac OS X threading:
917 * Thread safe since version 10.2
918 *
919 * Parameters:
920 *
921 * theAEDesc:
922 * A pointer to the descriptor containing the data to coerce.
923 *
924 * toType:
925 * The desired descriptor type of the resulting descriptor.
926 *
927 * result:
928 * A pointer to a descriptor. On successful return, a descriptor
929 * containing the coerced data and matching the descriptor type
930 * specified in toType. On error, a null descriptor. If the
931 * function returns successfully, your application should call the
932 * AEDisposeDesc function to dispose of the resulting descriptor
933 * after it has finished using it.
934 *
935 * Availability:
936 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
937 * CarbonLib: in CarbonLib 1.0 and later
938 * Non-Carbon CFM: in InterfaceLib 7.1 and later
939 }
AECoerceDescnull940 function AECoerceDesc( const (*var*) theAEDesc: AEDesc; toType: DescType; var result: AEDesc ): OSErr; external name '_AECoerceDesc';
941 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
942
943
944 {*************************************************************************
945 The following calls apply to any AEDesc. Every 'result' descriptor is
946 created for you, so you will be responsible for memory management
947 (including disposing) of the descriptors so created.
948 *************************************************************************}
949 { because AEDescs are opaque under Carbon, this AEInitializeDesc provides a
950 'clean' way of initializating them to be empty. }
951 {
952 * AEInitializeDesc()
953 *
954 * Discussion:
955 * The function sets the type of the descriptor to typeNull and sets
956 * the data handle to NULL. If you need to initialize a descriptor
957 * that already has some data in it, use AEDisposeDesc to deallocate
958 * the memory and initialize the descriptor.
959 *
960 * Mac OS X threading:
961 * Thread safe since version 10.2
962 *
963 * Parameters:
964 *
965 * desc:
966 * A pointer to a new descriptor.
967 *
968 * Availability:
969 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
970 * CarbonLib: in CarbonLib 1.4 and later
971 * Non-Carbon CFM: not available
972 }
973 procedure AEInitializeDesc( var desc: AEDesc ); external name '_AEInitializeDesc';
974 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
975
976 {
977 * AECreateDesc()
978 *
979 * Summary:
980 * Creates a new descriptor that incorporates the specified data.
981 *
982 * Discussion:
983 * While it is possible to create an Apple event descriptor or a
984 * descriptor list or a descriptor with the AECreateDesc function
985 * (assuming you have access to the raw data for an Apple event,
986 * list, or descriptor), you typically create these structured
987 * objects with their specific creation routines -
988 * AECreateAppleEvent, AECreateList, or AECreateDesc.
989 *
990 * Mac OS X threading:
991 * Thread safe since version 10.2
992 *
993 * Parameters:
994 *
995 * typeCode:
996 * The descriptor type for the new descriptor.
997 *
998 * dataPtr:
999 * A pointer to the data for the new descriptor. This data is
1000 * copied into a newly-allocated block of memory for the
1001 * descriptor that is created. To minimize copying overhead,
1002 * consider using AECreateDescFromExternalPtr.
1003 *
1004 * dataSize:
1005 * The length, in bytes, of the data for the new descriptor.
1006 *
1007 * result:
1008 * A pointer to a descriptor. On successful return, a descriptor
1009 * that incorporates the data specified by the dataPtr parameter.
1010 * On error, a null descriptor. If the function returns
1011 * successfully, your application should call the AEDisposeDesc
1012 * function to dispose of the resulting descriptor after it has
1013 * finished using it.
1014 *
1015 * Availability:
1016 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1017 * CarbonLib: in CarbonLib 1.0 and later
1018 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1019 }
AECreateDescnull1020 function AECreateDesc( typeCode: DescType; dataPtr: {const} UnivPtr; dataSize: Size; var result: AEDesc ): OSErr; external name '_AECreateDesc';
1021 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1022
1023
1024 {
1025 * AEDisposeDesc()
1026 *
1027 * Summary:
1028 * Deallocates the memory used by a descriptor.
1029 *
1030 * Discussion:
1031 * The AEDisposeDesc function deallocates the memory used by a
1032 * descriptor. After calling this method, the descriptor becomes an
1033 * empty descriptor with a type of typeNULL. Because all Apple event
1034 * structures (except for keyword-specified descriptors) are
1035 * descriptors, you can use AEDisposeDesc for any of them.
1036 * Do not call AEDisposeDesc on a descriptor obtained from another
1037 * Apple Event Manager function (such as the reply event from a call
1038 * to AESend) unless that function returns successfully.
1039 * Special Considerations
1040 * If the AEDesc might contain an OSL token, dispose of it with
1041 * AEDisposeToken.
1042 *
1043 * Mac OS X threading:
1044 * Thread safe since version 10.2
1045 *
1046 * Parameters:
1047 *
1048 * theAEDesc:
1049 * A pointer to the descriptor to deallocate. On return, a null
1050 * descriptor. If you pass a null descriptor in this parameter,
1051 * AEDisposeDesc returns noErr.
1052 *
1053 * Availability:
1054 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1055 * CarbonLib: in CarbonLib 1.0 and later
1056 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1057 }
AEDisposeDescnull1058 function AEDisposeDesc( var theAEDesc: AEDesc ): OSErr; external name '_AEDisposeDesc';
1059 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1060
1061
1062 {
1063 * AEDuplicateDesc()
1064 *
1065 * Summary:
1066 * Creates a copy of a descriptor.
1067 *
1068 * Discussion:
1069 * It is common for applications to send Apple events that have one
1070 * or more attributes or parameters in common. For example, if you
1071 * send a series of Apple events to the same application, the
1072 * address attribute is the same. In these cases, the most efficient
1073 * way to create the necessary Apple events is to make a template
1074 * Apple event that you can then copy - by calling the
1075 * AEDuplicateDesc function - as needed. You then fill in or change
1076 * the remaining parameters and attributes of the copy, send the
1077 * copy by calling the AESend function and, after AESend returns a
1078 * result code, dispose of the copy by calling AEDisposeDesc. You
1079 * can use this approach to prepare structures of type AEDesc,
1080 * AEDescList, AERecord, and AppleEvent.
1081 *
1082 * Mac OS X threading:
1083 * Thread safe since version 10.2
1084 *
1085 * Parameters:
1086 *
1087 * theAEDesc:
1088 * A pointer to the descriptor to duplicate. See AEDesc.
1089 *
1090 * result:
1091 * A pointer to a descriptor. On return, the descriptor contains a
1092 * copy of the descriptor specified by the theAEDesc parameter. If
1093 * the function returns successfully, your application should call
1094 * the AEDisposeDesc function to dispose of the resulting
1095 * descriptor after it has finished using it.
1096 *
1097 * Availability:
1098 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1099 * CarbonLib: in CarbonLib 1.0 and later
1100 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1101 }
AEDuplicateDescnull1102 function AEDuplicateDesc( const (*var*) theAEDesc: AEDesc; var result: AEDesc ): OSErr; external name '_AEDuplicateDesc';
1103 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1104
1105
1106 {
1107 * Create an AEDesc with memory "borrowed" from the application. The
1108 * data passed in *must* be immutable and not freed until the Dispose
1109 * callback is made.
1110 * The dispose callback may be made at any time, including during the
1111 * creation of the descriptor.
1112 * If possible, the descriptor will be copied to the address space of
1113 * any recipient process using virtual memory APIs and avoid an
1114 * actual memory copy.
1115 }
1116 type
1117 AEDisposeExternalProcPtr = procedure( dataPtr: {const} UnivPtr; dataLength: Size; refcon: SRefCon );
1118 AEDisposeExternalUPP = AEDisposeExternalProcPtr;
1119 {
1120 * AECreateDescFromExternalPtr()
1121 *
1122 * Summary:
1123 * Creates a new descriptor that uses a memory buffer supplied by
1124 * the caller.
1125 *
1126 * Discussion:
1127 * This function is different than AECreateDesc, in that it creates
1128 * a descriptor that uses the data block provided by the caller "in
1129 * place," rather than allocate a block of memory and copy the data
1130 * to it. This function can provide dramatically improved
1131 * performance if you're working with large chunks of data. It
1132 * attempts to copy the descriptor to the address space of any
1133 * recipient process using virtual memory APIs, avoiding an actual
1134 * memory copy. For example, you might want to use this function to
1135 * pass a large image in an Apple event.
1136 * You can use the AEGetDescDataRange function to access a specific
1137 * section of a large block of data.
1138 *
1139 * Mac OS X threading:
1140 * Thread safe since version 10.2
1141 *
1142 * Parameters:
1143 *
1144 * descriptorType:
1145 * The descriptor type for the new descriptor.
1146 *
1147 * dataPtr:
1148 * A pointer to the data for the new descriptor. The memory that
1149 * is pointed to cannot be a Handle (which may move in memory),
1150 * cannot be modified by the caller, and must be preserved in
1151 * place (and not freed), until the disposeCallback function is
1152 * called.
1153 * If possible, the descriptor will be mapped into the address
1154 * space of the recipient using shared memory, avoiding an actual
1155 * memory copy.
1156 * The pointer that is passed in does not need to be aligned to
1157 * any particular boundary, but is optimized to transfer data on a
1158 * page boundary. You can get the current page size (4096 on all
1159 * current Mac OS X systems) with the getpagesize(3) call. (Type
1160 * man 3 getpagesize in a Terminal window for documentation.)
1161 *
1162 * dataLength:
1163 * The length, in bytes, of the data for the new descriptor.
1164 *
1165 * disposeCallback:
1166 * A universal procedure pointer to a dispose callback function of
1167 * type AEDisposeExternalProcPtr. Your callback function will be
1168 * called when the block of memory provided by dataPtr is no
1169 * longer needed by the Apple Event Manager. The function can be
1170 * called at any time, including during creation of the descriptor.
1171 *
1172 * disposeRefcon:
1173 * A reference constant the Apple Event Manager passes to the
1174 * disposeCallback function whenever it calls the function. If
1175 * your dispose function doesn't require a reference constant,
1176 * pass 0 for this parameter.
1177 *
1178 * theDesc:
1179 * A pointer to a descriptor. On successful return, a descriptor
1180 * that incorporates the data specified by the dataPtr parameter.
1181 * On error, a null descriptor. If the function returns
1182 * successfully, your application should call the AEDisposeDesc
1183 * function to dispose of the resulting descriptor after it has
1184 * finished using it.
1185 *
1186 * Availability:
1187 * Mac OS X: in version 10.2 and later in ApplicationServices.framework
1188 * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
1189 * Non-Carbon CFM: not available
1190 }
AECreateDescFromExternalPtrnull1191 function AECreateDescFromExternalPtr( descriptorType: OSType; dataPtr: {const} UnivPtr; dataLength: Size; disposeCallback: AEDisposeExternalUPP; disposeRefcon: SRefCon; var theDesc: AEDesc ): OSStatus; external name '_AECreateDescFromExternalPtr';
1192 (* __OSX_AVAILABLE_STARTING( __MAC_10_2, __IPHONE_NA ) *)
1193
1194
1195
1196
1197 {
1198 * AECompareDesc()
1199 *
1200 * Discussion:
1201 * Compare two AEDesc descriptors and return whether they are
1202 * identical or not.
1203 *
1204 * Mac OS X threading:
1205 * Thread safe since version 10.8
1206 *
1207 * Parameters:
1208 *
1209 * desc1, desc2:
1210 * A pointer to an AEDesc to be compared.
1211 *
1212 * resultP:
1213 * If non-NULL, on a noErr return will be filled in with
1214 * true or false indicating whether the descriptors are
1215 * equilavent or not.
1216 *
1217 * Two descriptors are identical if they are the same type and have
1218 * the same data; typeAEList descriptors must contain the same number
1219 * of items and every item in each list must itself be identical;
1220 * typeAERecord descriptors must contain the same number of keys
1221 * and values and each key/value must match between the two.
1222 * typeAppleEvents match like typeAERecord and also require that
1223 * most attributes of the two events are identical.
1224 *
1225 * Availability:
1226 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1227 * CarbonLib: in CarbonLib 1.0 and later
1228 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1229 }
AECompareDescnull1230 function AECompareDesc( const (*var*) desc1: AEDesc; const (*var*) desc2: AEDesc; var resultP: Boolean ): OSStatus; external name '_AECompareDesc';
1231 (* __OSX_AVAILABLE_STARTING( __MAC_10_8, __IPHONE_NA ) *)
1232
1233 {*************************************************************************
1234 The following calls apply to AEDescList. Since AEDescList is a subtype of
1235 AEDesc, the calls in the previous section can also be used for AEDescList.
1236 All list and array indices are 1-based. If the data was greater than
1237 maximumSize in the routines below, then actualSize will be greater than
1238 maximumSize, but only maximumSize bytes will actually be retrieved.
1239 *************************************************************************}
1240 {
1241 * AECreateList()
1242 *
1243 * Discussion:
1244 * Creates an empty descriptor list or Apple event record.
1245 *
1246 * Mac OS X threading:
1247 * Thread safe since version 10.2
1248 *
1249 * Parameters:
1250 *
1251 * factoringPtr:
1252 * A pointer to the data at the beginning of each descriptor that
1253 * is the same for all descriptors in the list. If there is no
1254 * common data, or if you decide not to isolate the common data,
1255 * pass NULL as the value of this parameter.
1256 *
1257 * factoredSize:
1258 * The size of the common data. If there is no common data, or if
1259 * you decide not to isolate the common data, pass 0 as the value
1260 * of this parameter. (See the Discussion section for more
1261 * information.)
1262 *
1263 * isRecord:
1264 * A Boolean value that specifies the kind of list to create. Pass
1265 * a value of TRUE to create an Apple event record (a data
1266 * structure of type AERecord) or FALSE to create a descriptor
1267 * list.
1268 *
1269 * resultList:
1270 * A pointer to a descriptor list variable. On successful return,
1271 * the descriptor list or Apple event record that the AECreateList
1272 * function creates. On error, a null descriptor. See AEDescList.
1273 *
1274 * Availability:
1275 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1276 * CarbonLib: in CarbonLib 1.0 and later
1277 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1278 }
AECreateListnull1279 function AECreateList( factoringPtr: {const} UnivPtr; factoredSize: Size; isRecord: Boolean; var resultList: AEDescList ): OSErr; external name '_AECreateList';
1280 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1281
1282
1283 {
1284 * AECountItems()
1285 *
1286 * Discussion:
1287 * Counts the number of descriptors in a descriptor list.
1288 *
1289 * Mac OS X threading:
1290 * Thread safe since version 10.2
1291 *
1292 * Parameters:
1293 *
1294 * theAEDescList:
1295 * A pointer to the descriptor list to count
1296 *
1297 * theCount:
1298 * A pointer to a count variable. On return, the number of
1299 * descriptors in the specified descriptor list. Currently an
1300 * AEDescList is limited to 2^31 items.
1301 *
1302 * Availability:
1303 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1304 * CarbonLib: in CarbonLib 1.0 and later
1305 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1306 }
AECountItemsnull1307 function AECountItems( const (*var*) theAEDescList: AEDescList; var theCount: SIGNEDLONG ): OSErr; external name '_AECountItems';
1308 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1309
1310
1311 {
1312 * AEPutPtr()
1313 *
1314 * Discussion:
1315 * Puts data specified in a buffer to a descriptor list as a
1316 * descriptor, possibly replacing an existing descriptor in the list.
1317 *
1318 * Mac OS X threading:
1319 * Thread safe since version 10.2
1320 *
1321 * Parameters:
1322 *
1323 * theAEDescList:
1324 * A pointer to the descriptor list to add a descriptor to. See
1325 * AEDescList.
1326 *
1327 * index:
1328 * A one-based positive integer indicating the position to insert
1329 * the descriptor at. If there is already a descriptor in the
1330 * specified position, it is replaced. You can pass a value of
1331 * zero or count + 1 to add the descriptor at the end of the list.
1332 * AEPutPtr returns an error (AEIllegalIndex) if you pass a
1333 * negative number or a value that is out of range. Currently the
1334 * upper limit on index is 2^31 items.
1335 *
1336 * typeCode:
1337 * The descriptor type for the descriptor to be put into the list.
1338 *
1339 * dataPtr:
1340 * A pointer to the data for the descriptor to add.
1341 *
1342 * dataSize:
1343 * The length, in bytes, of the data for the descriptor to add.
1344 *
1345 * Availability:
1346 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1347 * CarbonLib: in CarbonLib 1.0 and later
1348 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1349 }
AEPutPtrnull1350 function AEPutPtr( var theAEDescList: AEDescList; index: SIGNEDLONG; typeCode: DescType; dataPtr: {const} UnivPtr; dataSize: Size ): OSErr; external name '_AEPutPtr';
1351 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1352
1353
1354 {
1355 * AEPutDesc()
1356 *
1357 * Discussion:
1358 * Adds a descriptor to any descriptor list, possibly replacing an
1359 * existing descriptor in the list.
1360 *
1361 * Mac OS X threading:
1362 * Thread safe since version 10.2
1363 *
1364 * Parameters:
1365 *
1366 * theAEDescList:
1367 * A pointer to the descriptor list to add a descriptor to. See
1368 * AEDescList.
1369 *
1370 * index:
1371 * A one-based positive integer indicating the position to insert
1372 * the descriptor at. If there is already a descriptor in the
1373 * specified position, it is replaced. You can pass a value of
1374 * zero or count + 1 to add the descriptor at the end of the list.
1375 * AEPutPtr returns an error (AEIllegalIndex) if you pass a
1376 * negative number or a value that is out of range. Currently the
1377 * upper limit on index is 2^31 items.
1378 *
1379 * theAEDesc:
1380 * A pointer to the descriptor to add to the list.
1381 *
1382 * Availability:
1383 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1384 * CarbonLib: in CarbonLib 1.0 and later
1385 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1386 }
AEPutDescnull1387 function AEPutDesc( var theAEDescList: AEDescList; index: SIGNEDLONG; const (*var*) theAEDesc: AEDesc ): OSErr; external name '_AEPutDesc';
1388 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1389
1390
1391 {
1392 * AEGetNthPtr()
1393 *
1394 * Discussion:
1395 * Gets a copy of the data from a descriptor at a specified position
1396 * in a descriptor list; typically used when your application needs
1397 * to work with the extracted data directly.
1398 *
1399 * Mac OS X threading:
1400 * Thread safe since version 10.2
1401 *
1402 * Parameters:
1403 *
1404 * theAEDescList:
1405 * A pointer to the descriptor list to add a descriptor to. See
1406 * AEDescList.
1407 *
1408 * index:
1409 * A one-based positive integer indicating the position in the
1410 * descriptor list of the descriptor to get the data from.
1411 * AEGetNthPtr returns an error if you pass zero, a negative
1412 * number, or a value that is out of range. Currently the upper
1413 * limit on index is 2^31 items.
1414 *
1415 * desiredType:
1416 * The desired descriptor type for the copied data. For a list of
1417 * AppleScript's predefined descriptor types. If the descriptor
1418 * specified by the index parameter is not of the desired type,
1419 * AEGetNthPtr attempts to coerce the data to this type. If you
1420 * pass a value of typeWildCard, no coercion is performed, and the
1421 * descriptor type of the copied data is the same as the
1422 * descriptor type of the original descriptor.
1423 *
1424 * theAEKeyword:
1425 * A pointer to a keyword or NULL. On return, the keyword for the
1426 * specified descriptor, if you are getting data from a list of
1427 * keyword-specified descriptors; otherwise, AEGetNthPtr returns
1428 * the value typeWildCard.
1429 *
1430 * typeCode:
1431 * A pointer to a descriptor type or NULL. On return, specifies
1432 * the descriptor type of the data pointed to by dataPtr.
1433 *
1434 * dataPtr:
1435 * A pointer to a buffer, local variable, or other storage
1436 * location created and disposed of by your application. The size
1437 * in bytes must be at least as large as the value you pass in the
1438 * maximumSize parameter. On return, contains the data from the
1439 * descriptor at the position in the descriptor list specified by
1440 * the index parameter.
1441 *
1442 * maximumSize:
1443 * The maximum length, in bytes, of the expected data. The
1444 * AEGetNthPtr function will not return more data than you specify
1445 * in this parameter.
1446 *
1447 * actualSize:
1448 * A pointer to a size variable or NULL. On return, the length, in
1449 * bytes, of the data for the specified descriptor. If this value
1450 * is larger than the value of the maximumSize parameter, the
1451 * buffer pointed to by dataPtr was not large enough to contain
1452 * all of the data for the descriptor, though AEGetNthPtr does not
1453 * write beyond the end of the buffer. If the buffer was too
1454 * small, you can resize it and call AEGetNthPtr again.
1455 *
1456 * Availability:
1457 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1458 * CarbonLib: in CarbonLib 1.0 and later
1459 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1460 }
AEGetNthPtrnull1461 function AEGetNthPtr( const (*var*) theAEDescList: AEDescList; index: SIGNEDLONG; desiredType: DescType; theAEKeyword: AEKeywordPtr { can be NULL }; typeCode: DescTypePtr { can be NULL }; dataPtr: UnivPtr; maximumSize: Size; actualSize: SizePtr { can be NULL } ): OSErr; external name '_AEGetNthPtr';
1462 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1463
1464
1465 {
1466 * AEGetNthDesc()
1467 *
1468 * Discussion:
1469 * Copies a descriptor from a specified position in a descriptor
1470 * list into a specified descriptor; typically used when your
1471 * application needs to pass the extracted data to another function
1472 * as a descriptor.
1473 *
1474 * Mac OS X threading:
1475 * Thread safe since version 10.2
1476 *
1477 * Parameters:
1478 *
1479 * theAEDescList:
1480 * A pointer to the descriptor list to add a descriptor to. See
1481 * AEDescList.
1482 *
1483 * index:
1484 * A one-based positive integer indicating the position in the
1485 * descriptor list of the descriptor to get the data from.
1486 * AEGetNthDesc returns an error if you pass zero, a negative
1487 * number, or a value that is out of range. Currently the upper
1488 * limit on index is 2^31 items.
1489 *
1490 * desiredType:
1491 * The desired descriptor type for the copied data. For a list of
1492 * AppleScript's predefined descriptor types. If the descriptor
1493 * specified by the index parameter is not of the desired type,
1494 * AEGetNthDesc attempts to coerce the data to this type. If you
1495 * pass a value of typeWildCard, no coercion is performed, and the
1496 * descriptor type of the copied data is the same as the
1497 * descriptor type of the original descriptor.
1498 *
1499 * theAEKeyword:
1500 * A pointer to a keyword or NULL. On return, the keyword for the
1501 * specified descriptor, if you are getting data from a list of
1502 * keyword-specified descriptors; otherwise, AEGetNthDesc returns
1503 * the value typeWildCard.
1504 *
1505 * result:
1506 * A pointer to a descriptor. On successful return, a copy of the
1507 * descriptor specified by the index parameter, coerced, if
1508 * necessary, to the descriptor type specified by the desiredType
1509 * parameter. On error, a null descriptor. If the function returns
1510 * successfully, your application should call the AEDisposeDesc
1511 * function to dispose of the resulting descriptor after it has
1512 * finished using it.
1513 *
1514 * Availability:
1515 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1516 * CarbonLib: in CarbonLib 1.0 and later
1517 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1518 }
AEGetNthDescnull1519 function AEGetNthDesc( const (*var*) theAEDescList: AEDescList; index: SIGNEDLONG; desiredType: DescType; theAEKeyword: AEKeywordPtr { can be NULL }; var result: AEDesc ): OSErr; external name '_AEGetNthDesc';
1520 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1521
1522
1523 {
1524 * AESizeOfNthItem()
1525 *
1526 * Discussion:
1527 * Gets the data size and descriptor type of the descriptor at a
1528 * specified position in a descriptor list.
1529 *
1530 * Mac OS X threading:
1531 * Thread safe since version 10.2
1532 *
1533 * Parameters:
1534 *
1535 * theAEDescList:
1536 * A pointer to the descriptor list to add a descriptor to. See
1537 * AEDescList.
1538 *
1539 * index:
1540 * A one-based positive integer indicating the position in the
1541 * descriptor list of the descriptor to get the data from.
1542 * AESizeOfNthItem returns an error if you pass zero, a negative
1543 * number, or a value that is out of range. Currently the upper
1544 * limit on index is 2^31 items.
1545 *
1546 * typeCode:
1547 * A pointer to a descriptor type or NULL. On return, specifies
1548 * the descriptor type of the descriptor.
1549 *
1550 * dataSize:
1551 * A pointer to a size variable or NULL. On return, the length (in
1552 * bytes) of the data in the descriptor.
1553 *
1554 * Availability:
1555 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1556 * CarbonLib: in CarbonLib 1.0 and later
1557 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1558 }
AESizeOfNthItemnull1559 function AESizeOfNthItem( const (*var*) theAEDescList: AEDescList; index: SIGNEDLONG; typeCode: DescTypePtr { can be NULL }; dataSize: SizePtr { can be NULL } ): OSErr; external name '_AESizeOfNthItem';
1560 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1561
1562
1563 {
1564 * AEGetArray()
1565 *
1566 * Discussion:
1567 * Extracts data from an Apple event array created with the
1568 * AEPutArray function and stores it as a standard array of fixed
1569 * size items in the specified buffer.
1570 *
1571 * Mac OS X threading:
1572 * Thread safe since version 10.2
1573 *
1574 * Parameters:
1575 *
1576 * theAEDescList:
1577 * A pointer to the descriptor list to add a descriptor to. See
1578 * AEDescList.
1579 *
1580 * arrayType:
1581 * The Apple event array type to convert. Pass one of the
1582 * constants: kAEDataArray, kAEPackedArray, kAEDescArray,
1583 * kAEKeyDescArray
1584 *
1585 * arrayPtr:
1586 * A pointer to a buffer, allocated and disposed of by your
1587 * application, for storing the array. The size in bytes must be
1588 * at least as large as the value you pass in the maximumSize
1589 * parameter. On return, the buffer contains the array of
1590 * fixed-size items.
1591 *
1592 * maximumSize:
1593 * The maximum length, in bytes, of the expected data. The
1594 * AEGetArray function will not return more data than you specify
1595 * in this parameter.
1596 *
1597 * itemType:
1598 * A pointer to a descriptor type. On return, for arrays of type
1599 * kAEDataArray, kAEPackedArray, or kAEHandleArray, the descriptor
1600 * type of the items in the returned array. The AEGetArray
1601 * function doesn't supply a value in itemType for arrays of type
1602 * kAEDescArray and kAEKeyDescArray because they may contain
1603 * descriptors of different types.
1604 *
1605 * itemSize:
1606 * A pointer to a size variable. On return, for arrays of type
1607 * kAEDataArray or kAEPackedArray, the size (in bytes) of each
1608 * item in the returned array. You don't get an item size for
1609 * arrays of type kAEDescArray, kAEKeyDescArray, or kAEHandleArray
1610 * because descriptors and handles (though not the data they point
1611 * to) have a known size.
1612 *
1613 * itemCount:
1614 * A pointer to a size variable. On return, the number of items in
1615 * the returned array. Currently the upper limit on the size of
1616 * an array is 2^31 items.
1617 *
1618 * Availability:
1619 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1620 * CarbonLib: in CarbonLib 1.0 and later
1621 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1622 }
AEGetArraynull1623 function AEGetArray( const (*var*) theAEDescList: AEDescList; arrayType: AEArrayType; arrayPtr: AEArrayDataPointer; maximumSize: Size; var itemType: DescType; var itemSize: Size; var itemCount: SIGNEDLONG ): OSErr; external name '_AEGetArray';
1624 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1625
1626
1627 {
1628 * AEPutArray()
1629 *
1630 * Discussion:
1631 * Extracts data from an Apple event array created with the
1632 * AEPutArray function and stores it as a standard array of fixed
1633 * size items in the specified buffer.
1634 *
1635 * Mac OS X threading:
1636 * Thread safe since version 10.2
1637 *
1638 * Parameters:
1639 *
1640 * theAEDescList:
1641 * A pointer to the descriptor list to add a descriptor to. See
1642 * AEDescList.
1643 *
1644 * arrayType:
1645 * The Apple event array type to convert. Pass one of the
1646 * constants: kAEDataArray, kAEPackedArray, kAEDescArray,
1647 * kAEKeyDescArray
1648 *
1649 * arrayPtr:
1650 * A pointer to a buffer, local variable, or other storage
1651 * location, created and disposed of by your application, that
1652 * contains the array to put into the descriptor list.
1653 *
1654 * itemType:
1655 * For arrays of type kAEDataArray, kAEPackedArray, or
1656 * kAEHandleArray, the descriptor type of the array items to
1657 * create. Use one of the constants such as typeLongInteger. You
1658 * don't need to specify an item type for arrays of type
1659 * kAEDescArray or kAEKeyDescArray because the data is already
1660 * stored in descriptors which contain a descriptor type.
1661 *
1662 * itemSize:
1663 * For arrays of type kAEDataArray or kAEPackedArray, the size (in
1664 * bytes) of the array items to create. You don't need to specify
1665 * an item size for arrays of type kAEDescArray, kAEKeyDescArray,
1666 * or kAEHandleArray because their descriptors (though not the
1667 * data they point to) have a known size.
1668 *
1669 * itemCount:
1670 * A pointer to a size variable. On return, the number of items in
1671 * the returned array. Currently the upper limit on the size of
1672 * an array is 2^31 items.
1673 *
1674 * Availability:
1675 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1676 * CarbonLib: in CarbonLib 1.0 and later
1677 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1678 }
AEPutArraynull1679 function AEPutArray( var theAEDescList: AEDescList; arrayType: AEArrayType; const (*var*) arrayPtr: AEArrayData; itemType: DescType; itemSize: Size; itemCount: SIGNEDLONG ): OSErr; external name '_AEPutArray';
1680 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1681
1682
1683 {
1684 * AEDeleteItem()
1685 *
1686 * Discussion:
1687 * Deletes a descriptor from a descriptor list, causing all
1688 * subsequent descriptors to move up one place.
1689 *
1690 * Mac OS X threading:
1691 * Thread safe since version 10.2
1692 *
1693 * Parameters:
1694 *
1695 * theAEDescList:
1696 * A pointer to the descriptor list to add a descriptor to. See
1697 * AEDescList.
1698 *
1699 * index:
1700 * A one-based positive integer indicating the position in the
1701 * descriptor list of the descriptor to delete. AEDeleteItem
1702 * returns an error if you pass zero, a negative number, or a
1703 * value that is out of range. Currently the upper limit on index
1704 * is 2^31 items.
1705 *
1706 * Availability:
1707 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1708 * CarbonLib: in CarbonLib 1.0 and later
1709 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1710 }
AEDeleteItemnull1711 function AEDeleteItem( var theAEDescList: AEDescList; index: SIGNEDLONG ): OSErr; external name '_AEDeleteItem';
1712 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1713
1714
1715 {*************************************************************************
1716 The following calls apply to AERecord. Since AERecord is a subtype of
1717 AEDescList, the calls in the previous sections can also be used for
1718 AERecord an AERecord can be created by using AECreateList with isRecord
1719 set to true.
1720 *************************************************************************}
1721 {************************************************************************
1722 AERecords can have an abitrary descriptorType. This allows you to
1723 check if desc is truly an AERecord
1724 ***********************************************************************}
1725 {
1726 * AECheckIsRecord()
1727 *
1728 * Mac OS X threading:
1729 * Thread safe since version 10.2
1730 *
1731 * Availability:
1732 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1733 * CarbonLib: in CarbonLib 1.4 and later
1734 * Non-Carbon CFM: not available
1735 }
AECheckIsRecordnull1736 function AECheckIsRecord( const (*var*) theDesc: AEDesc ): Boolean; external name '_AECheckIsRecord';
1737 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1738
1739 {*************************************************************************
1740 The following calls create and manipulate the AppleEvent data type.
1741 *************************************************************************}
1742 {
1743 * AECreateAppleEvent()
1744 *
1745 * Summary:
1746 * Creates an Apple event with several important attributes but no
1747 * parameters.
1748 *
1749 * Discussion:
1750 * The AECreateAppleEvent function creates an empty Apple event. You
1751 * can add parameters to the Apple event after you create it with
1752 * the functions described in "Adding Parameters and Attributes to
1753 * an Apple Event".
1754 *
1755 * Mac OS X threading:
1756 * Thread safe since version 10.2
1757 *
1758 * Parameters:
1759 *
1760 * theAEEventClass:
1761 * The event class of the Apple event to create. This parameter
1762 * becomes accessible through the keyEventClassAttr attribute of
1763 * the Apple event. Some event classes are described in "Event
1764 * Class Constants".
1765 *
1766 * theAEEventID:
1767 * The event ID of the Apple event to create. This parameter
1768 * becomes accessible through the keyEventIDAttr attribute of the
1769 * Apple event.
1770 *
1771 * target:
1772 * A pointer to an address descriptor. Before calling
1773 * AECreateAppleEvent, you set the descriptor to identify the
1774 * target (or server) application for the Apple event. This
1775 * parameter becomes accessible through the keyAddressAttr
1776 * attribute of the Apple event.
1777 *
1778 * returnID:
1779 * The return ID for the created Apple event. If you pass a value
1780 * of kAutoGenerateReturnID, the Apple Event Manager assigns the
1781 * created Apple event a return ID that is unique to the current
1782 * session. If you pass any other value, the Apple Event Manager
1783 * assigns that value for the ID. This parameter becomes
1784 * accessible through the keyReturnIDAttr attribute of the Apple
1785 * event. The return ID constant is described in "ID Constants for
1786 * the AECreateAppleEvent Function".
1787 *
1788 * transactionID:
1789 * The transaction ID for this Apple event. A transaction is a
1790 * sequence of Apple events that are sent back and forth between
1791 * the client and server applications, beginning with the client's
1792 * initial request for a service. All Apple events that are part
1793 * of a transaction must have the same transaction ID. You can
1794 * specify the kAnyTransactionID constant if the Apple event is
1795 * not one of a series of interdependent Apple events. This
1796 * parameter becomes accessible through the keyTransactionIDAttr
1797 * attribute of the Apple event.
1798 *
1799 * result:
1800 * A pointer to an Apple event. On successful return, the new
1801 * Apple event. On error, a null descriptor (one with descriptor
1802 * type typeNull). If the function returns successfully, your
1803 * application should call the AEDisposeDesc function to dispose
1804 * of the resulting Apple event after it has finished using it.
1805 * See the AppleEvent data type.
1806 *
1807 * Availability:
1808 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1809 * CarbonLib: in CarbonLib 1.0 and later
1810 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1811 }
AECreateAppleEventnull1812 function AECreateAppleEvent( theAEEventClass: AEEventClass; theAEEventID: AEEventID; const (*var*) target: AEAddressDesc; returnID: AEReturnID; transactionID: AETransactionID; var result: AppleEvent ): OSErr; external name '_AECreateAppleEvent';
1813 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1814
1815
1816 {*************************************************************************
1817 The following calls are used to pack and unpack parameters from records
1818 of type AppleEvent. Since AppleEvent is a subtype of AERecord, the calls
1819 in the previous sections can also be used for variables of type
1820 AppleEvent. The next six calls are in fact identical to the six calls
1821 for AERecord.
1822 *************************************************************************}
1823 {
1824 * AEPutParamPtr()
1825 *
1826 * Discussion:
1827 * Puts a pointer to data, a descriptor type, and a keyword into an
1828 * Apple event or Apple event record as an Apple event parameter.
1829 *
1830 * Mac OS X threading:
1831 * Thread safe since version 10.2
1832 *
1833 * Parameters:
1834 *
1835 * theAppleEvent:
1836 * A pointer to the Apple event to add a parameter to. See the
1837 * AppleEvent data type.
1838 *
1839 * theAEKeyword:
1840 * The keyword for the parameter to add. If the Apple event
1841 * already includes an parameter with this keyword, the parameter
1842 * is replaced.
1843 *
1844 * typeCode:
1845 * The descriptor type for the parameter to add.
1846 *
1847 * dataPtr:
1848 * A pointer to the data for the parameter to add.
1849 *
1850 * dataSize:
1851 * The length, in bytes, of the data for the parameter to add.
1852 *
1853 * Availability:
1854 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1855 * CarbonLib: in CarbonLib 1.0 and later
1856 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1857 }
AEPutParamPtrnull1858 function AEPutParamPtr( var theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; typeCode: DescType; dataPtr: {const} UnivPtr; dataSize: Size ): OSErr; external name '_AEPutParamPtr';
1859 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1860
1861
1862 {
1863 * AEPutParamDesc()
1864 *
1865 * Discussion:
1866 * Puts a descriptor and a keyword into an Apple event or Apple
1867 * event record as an Apple event parameter.
1868 *
1869 * Mac OS X threading:
1870 * Thread safe since version 10.2
1871 *
1872 * Parameters:
1873 *
1874 * theAppleEvent:
1875 * A pointer to the Apple event to add a parameter to.
1876 *
1877 * theAEKeyword:
1878 * The keyword specifying the parameter to add. If the Apple event
1879 * already has a parameter with this keyword, the parameter is
1880 * replaced.
1881 *
1882 * theAEDesc:
1883 * A pointer to the descriptor for the parameter to add. See
1884 * AEDesc.
1885 *
1886 * Availability:
1887 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1888 * CarbonLib: in CarbonLib 1.0 and later
1889 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1890 }
AEPutParamDescnull1891 function AEPutParamDesc( var theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; const (*var*) theAEDesc: AEDesc ): OSErr; external name '_AEPutParamDesc';
1892 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1893
1894
1895 {
1896 * AEGetParamPtr()
1897 *
1898 * Summary:
1899 * Gets a copy of the data for a specified Apple event parameter
1900 * from an Apple event or an Apple event record (type AERecord);
1901 * typically used when your application needs to work with the
1902 * extracted data directly.
1903 *
1904 * Discussion:
1905 * You should use this function only to extract data from value
1906 * descriptors such as typeUTF8Text.
1907 * Because this function allows you to specify a desired type, it
1908 * can result in coercion. When used correctly, this has the
1909 * positive effect of returning the data in the desired format.
1910 * However, it can have side effects you may not be expecting, such
1911 * as the overhead of calls to coercion handlers. See also the
1912 * Version Notes section below for possible problems with
1913 * coercion.
1914 * To get Apple event parameter data for your application to use
1915 * directly, call AEGetParamPtr. To get a descriptor for an Apple
1916 * event parameter to pass on to another Apple Event Manager
1917 * routine, call AEGetParamDesc.
1918 * Before calling AEGetParamPtr, you can call the AESizeOfParam
1919 * function to determine a size for the dataPtr buffer. However,
1920 * unless you specify typeWildCard for the desiredType parameter,
1921 * AEGetParamPtr may coerce the data, which may cause the size of
1922 * the data to change.
1923 * In some cases, you may get improved efficiency extracting
1924 * information from an Apple event with the AEGetDescDataRange
1925 * function.
1926 *
1927 * Mac OS X threading:
1928 * Thread safe since version 10.2
1929 *
1930 * Parameters:
1931 *
1932 * theAppleEvent:
1933 * A pointer to the Apple event to get the parameter data from.
1934 * See AppleEvent.
1935 *
1936 * theAEKeyword:
1937 * The keyword that specifies the desired Apple event parameter.
1938 *
1939 * desiredType:
1940 * The desired descriptor type for the copied data. If the
1941 * descriptor specified by the theAEKeyword parameter is not of
1942 * the desired type, AEGetParamPtr attempts to coerce the data to
1943 * this type. However, if the desired type is typeWildCard, no
1944 * coercion is performed. On return, you can determine the actual
1945 * descriptor type by examining the typeCode parameter.
1946 *
1947 * actualType:
1948 * A pointer to a descriptor type. On return, specifies the
1949 * descriptor type of the data pointed to by dataPtr. The returned
1950 * type is either the same as the type specified by the
1951 * desiredType parameter or, if the desired type was typeWildcard,
1952 * the true type of the descriptor. Specify NULL if you do not
1953 * care about this return value.
1954 *
1955 * dataPtr:
1956 * A pointer to a buffer, local variable, or other storage
1957 * location created and disposed of by your application. The size
1958 * in bytes must be at least as large as the value you pass in the
1959 * maximumSize parameter. On return, contains the parameter data.
1960 * Specify NULL if you do not care about this return value.
1961 *
1962 * maximumSize:
1963 * The maximum length, in bytes, of the expected Apple event
1964 * parameter data. The AEGetParamPtr function will not return more
1965 * data than you specify in this parameter.
1966 *
1967 * actualSize:
1968 * A pointer to a variable of type Size. On return, the length, in
1969 * bytes, of the data for the specified Apple event parameter. If
1970 * this value is larger than the value you passed in the
1971 * maximumSize parameter, the buffer pointed to by dataPtr was not
1972 * large enough to contain all of the data for the parameter,
1973 * though AEGetParamPtr does not write beyond the end of the
1974 * buffer. If the buffer was too small, you can resize it and call
1975 * AEGetParamPtr again. Specify NULL if you do not care about this
1976 * return value.
1977 *
1978 * Availability:
1979 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
1980 * CarbonLib: in CarbonLib 1.0 and later
1981 * Non-Carbon CFM: in InterfaceLib 7.1 and later
1982 }
AEGetParamPtrnull1983 function AEGetParamPtr( const (*var*) theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; desiredType: DescType; actualType: DescTypePtr { can be NULL }; dataPtr: UnivPtr; maximumSize: Size; actualSize: SizePtr { can be NULL } ): OSErr; external name '_AEGetParamPtr';
1984 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
1985
1986
1987 {
1988 * AEGetParamDesc()
1989 *
1990 * Summary:
1991 * Gets a copy of the descriptor for a keyword-specified Apple event
1992 * parameter from an Apple event or an Apple event record (type
1993 * AERecord); typically used when your application needs to pass the
1994 * extracted data to another function as a descriptor.
1995 *
1996 * Discussion:
1997 * To get Apple event parameter data for your application to use
1998 * directly, call AEGetParamPtr. To get a descriptor for an Apple
1999 * event parameter to pass on to another Apple Event Manager
2000 * routine, call AEGetParamDesc.
2001 * If the actual parameter you are getting with AEGetParamDesc is a
2002 * record, AEGetParamDesc will only allow you to request it as a
2003 * typeAERecord, typeAEList, or typeWildcard. For any other type, it
2004 * will return errAECoercionFail.
2005 *
2006 * Mac OS X threading:
2007 * Thread safe since version 10.2
2008 *
2009 * Parameters:
2010 *
2011 * theAppleEvent:
2012 * A pointer to the Apple event to get the parameter descriptor
2013 * from.
2014 *
2015 * theAEKeyword:
2016 * A keyword that specifies the desired Apple event parameter.
2017 *
2018 * desiredType:
2019 * The descriptor type for the desired Apple event parameter. If
2020 * the requested Apple event parameter is not of the desired type,
2021 * the Apple Event Manager attempts to coerce it to the desired
2022 * type. However, if you pass a value of typeWildCard, no coercion
2023 * is performed, and the descriptor type of the returned
2024 * descriptor is the same as the descriptor type of the Apple
2025 * event parameter.
2026 *
2027 * result:
2028 * A pointer to a descriptor. On successful return, a copy of the
2029 * descriptor for the specified Apple event parameter, coerced, if
2030 * necessary, to the descriptor type specified by the desiredType
2031 * parameter. On error, a null descriptor. If the function returns
2032 * successfully, your application should call the AEDisposeDesc
2033 * function to dispose of the resulting descriptor after it has
2034 * finished using it. See AEDesc.
2035 *
2036 * Availability:
2037 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2038 * CarbonLib: in CarbonLib 1.0 and later
2039 * Non-Carbon CFM: in InterfaceLib 7.1 and later
2040 }
AEGetParamDescnull2041 function AEGetParamDesc( const (*var*) theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; desiredType: DescType; var result: AEDesc ): OSErr; external name '_AEGetParamDesc';
2042 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2043
2044
2045 {
2046 * AESizeOfParam()
2047 *
2048 * Discussion:
2049 * Gets the size and descriptor type of an Apple event parameter
2050 * from a descriptor of type AERecord or AppleEvent.
2051 *
2052 * Mac OS X threading:
2053 * Thread safe since version 10.2
2054 *
2055 * Parameters:
2056 *
2057 * theAppleEvent:
2058 * A pointer to the Apple event to get the parameter data from.
2059 * See AppleEvent.
2060 *
2061 * theAEKeyword:
2062 * The keyword that specifies the desired parameter.
2063 *
2064 * typeCode:
2065 * A pointer to a descriptor type. On return, specifies the
2066 * descriptor type of the Apple event parameter.
2067 *
2068 * dataSize:
2069 * A pointer to a size variable. On return, the length, in bytes,
2070 * of the data in the Apple event parameter.
2071 *
2072 * Availability:
2073 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2074 * CarbonLib: in CarbonLib 1.0 and later
2075 * Non-Carbon CFM: in InterfaceLib 7.1 and later
2076 }
AESizeOfParamnull2077 function AESizeOfParam( const (*var*) theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; typeCode: DescTypePtr { can be NULL }; dataSize: SizePtr { can be NULL } ): OSErr; external name '_AESizeOfParam';
2078 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2079
2080
2081 {
2082 * AEDeleteParam()
2083 *
2084 * Discussion:
2085 * Deletes a keyword-specified parameter from an Apple event or
2086 * Apple event record.
2087 *
2088 * Mac OS X threading:
2089 * Thread safe since version 10.2
2090 *
2091 * Parameters:
2092 *
2093 * theAppleEvent:
2094 * A pointer to the Apple event or Apple event record to delete
2095 * the parameter from.
2096 *
2097 * theAEKeyword:
2098 * The keyword that specifies the parameter to delete.
2099 *
2100 * Availability:
2101 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2102 * CarbonLib: in CarbonLib 1.0 and later
2103 * Non-Carbon CFM: in InterfaceLib 7.1 and later
2104 }
AEDeleteParamnull2105 function AEDeleteParam( var theAppleEvent: AppleEvent; theAEKeyword: AEKeyword ): OSErr; external name '_AEDeleteParam';
2106 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2107
2108
2109 {*************************************************************************
2110 The following calls also apply to type AppleEvent. Message attributes are
2111 far more restricted, and can only be accessed through the following 5
2112 calls. The various list and record routines cannot be used to access the
2113 attributes of an event.
2114 *************************************************************************}
2115
2116 {
2117 * AEGetAttributePtr()
2118 *
2119 * Summary:
2120 * Gets a copy of the data for a specified Apple event attribute
2121 * from an Apple event; typically used when your application needs
2122 * to work with the data directly.
2123 *
2124 * Discussion:
2125 * To get Apple event attribute data for your application to use
2126 * directly, call AEGetAttributePtr. To get a descriptor for an
2127 * Apple event attribute to pass on to another Apple Event Manager
2128 * routine, call AEGetAttributeDesc.
2129 * Before calling AEGetAttributePtr, you can call the
2130 * AESizeOfAttribute function to determine a size for the dataPtr
2131 * buffer. However, unless you specify typeWildCard for the
2132 * desiredType parameter, AEGetAttributePtr may coerce the data,
2133 * which may cause the size of the data to change.
2134 *
2135 * Mac OS X threading:
2136 * Thread safe since version 10.2
2137 *
2138 * Parameters:
2139 *
2140 * theAppleEvent:
2141 * A pointer to the Apple event to get the attribute data from.
2142 *
2143 * theAEKeyword:
2144 * The keyword that specifies the desired attribute.
2145 *
2146 * desiredType:
2147 * The desired descriptor type for the copied data. If the
2148 * descriptor specified by the theAEKeyword parameter is not of
2149 * the desired type, AEGetAttributePtr attempts to coerce the data
2150 * to this type. However, if you pass a value of typeWildCard, no
2151 * coercion is performed, and the descriptor type of the returned
2152 * data is the same as the descriptor type of the Apple event
2153 * attribute. On return, you can determine the actual descriptor
2154 * type by examining the typeCode parameter.
2155 *
2156 * typeCode:
2157 * A pointer to a descriptor type. On return, specifies the
2158 * descriptor type of the attribute data pointed to by dataPtr.
2159 * The returned type is either the same as the type specified by
2160 * the desiredType parameter or, if the desired type was type
2161 * wildcard, the true type of the descriptor. For a list of
2162 * AppleScript's predefined descriptor types, see "Descriptor Type
2163 * Constants". See DescType.
2164 *
2165 * dataPtr:
2166 * A pointer to a buffer, local variable, or other storage
2167 * location, created and disposed of by your application. The size
2168 * in bytes must be at least as large as the value you pass in the
2169 * maximumSize parameter. On return, contains the attribute data.
2170 *
2171 * maximumSize:
2172 * The maximum length, in bytes, of the expected attribute data.
2173 * The AEGetAttributePtr function will not return more data than
2174 * you specify in this parameter.
2175 *
2176 * actualSize:
2177 * A pointer to a size variable. On return, the length, in bytes,
2178 * of the data for the specified Apple event attribute. If this
2179 * value is larger than the value you passed in the maximumSize
2180 * parameter, the buffer pointed to by dataPtr was not large
2181 * enough to contain all of the data for the attribute, though
2182 * AEGetAttributePtr does not write beyond the end of the buffer.
2183 * If the buffer was too small, you can resize it and call
2184 * AEGetAttributePtr again.
2185 *
2186 * Availability:
2187 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2188 * CarbonLib: in CarbonLib 1.0 and later
2189 * Non-Carbon CFM: in InterfaceLib 7.1 and later
2190 }
AEGetAttributePtrnull2191 function AEGetAttributePtr( const (*var*) theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; desiredType: DescType; typeCode: DescTypePtr { can be NULL }; dataPtr: UnivPtr; maximumSize: Size; actualSize: SizePtr { can be NULL } ): OSErr; external name '_AEGetAttributePtr';
2192 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2193
2194
2195 {
2196 * AEGetAttributeDesc()
2197 *
2198 * Summary:
2199 * Gets a copy of the descriptor for a specified Apple event
2200 * attribute from an Apple event; typically used when your
2201 * application needs to pass the descriptor on to another function.
2202 *
2203 * Discussion:
2204 * To get Apple event attribute data for your application to use
2205 * directly, call AEGetAttributePtr. To get a descriptor for an
2206 * Apple event attribute to pass on to another Apple Event Manager
2207 * routine, call AEGetAttributeDesc.
2208 *
2209 * Mac OS X threading:
2210 * Thread safe since version 10.2
2211 *
2212 * Parameters:
2213 *
2214 * theAppleEvent:
2215 * A pointer to the Apple event to get the attribute descriptor
2216 * from. See AppleEvent.
2217 *
2218 * theAEKeyword:
2219 * The keyword that specifies the desired attribute.
2220 *
2221 * desiredType:
2222 * The desired descriptor type for the copied data. If the
2223 * descriptor specified by the theAEKeyword parameter is not of
2224 * the desired type, AEGetAttributePtr attempts to coerce the data
2225 * to this type. However, if you pass a value of typeWildCard, no
2226 * coercion is performed, and the descriptor type of the returned
2227 * data is the same as the descriptor type of the Apple event
2228 * attribute. On return, you can determine the actual descriptor
2229 * type by examining the typeCode parameter.
2230 *
2231 * result:
2232 * A pointer to a descriptor. On successful return, a copy of the
2233 * specified Apple event attribute, coerced, if necessary, to the
2234 * descriptor type specified in desiredType. On error, a null
2235 * descriptor. If the function returns successfully, your
2236 * application should call the AEDisposeDesc function to dispose
2237 * of the resulting descriptor after it has finished using it. See
2238 * AEDesc.
2239 *
2240 * Availability:
2241 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2242 * CarbonLib: in CarbonLib 1.0 and later
2243 * Non-Carbon CFM: in InterfaceLib 7.1 and later
2244 }
AEGetAttributeDescnull2245 function AEGetAttributeDesc( const (*var*) theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; desiredType: DescType; var result: AEDesc ): OSErr; external name '_AEGetAttributeDesc';
2246 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2247
2248
2249 {
2250 * AESizeOfAttribute()
2251 *
2252 * Discussion:
2253 * Gets the size and descriptor type of an Apple event attribute
2254 * from a descriptor of type AppleEvent.
2255 *
2256 * Mac OS X threading:
2257 * Thread safe since version 10.2
2258 *
2259 * Parameters:
2260 *
2261 * theAppleEvent:
2262 * A pointer to the Apple event to get the attribute data from.
2263 *
2264 * theAEKeyword:
2265 * The keyword that specifies the attribute.
2266 *
2267 * typeCode:
2268 * A pointer to a descriptor type. On return, specifies the
2269 * descriptor type of the attribute. Can be NULL.
2270 *
2271 * dataSize:
2272 * A pointer to a size variable. On return, the length, in bytes,
2273 * of the data in the attribute. Can be NULL.
2274 *
2275 * Availability:
2276 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2277 * CarbonLib: in CarbonLib 1.0 and later
2278 * Non-Carbon CFM: in InterfaceLib 7.1 and later
2279 }
AESizeOfAttributenull2280 function AESizeOfAttribute( const (*var*) theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; typeCode: DescTypePtr { can be NULL }; dataSize: SizePtr { can be NULL } ): OSErr; external name '_AESizeOfAttribute';
2281 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2282
2283
2284 {
2285 * AEPutAttributePtr()
2286 *
2287 * Discussion:
2288 * Adds a pointer to data, a descriptor type, and a keyword to an
2289 * Apple event as an attribute.
2290 *
2291 * Mac OS X threading:
2292 * Thread safe since version 10.2
2293 *
2294 * Parameters:
2295 *
2296 * theAppleEvent:
2297 * A pointer to the Apple event to add an attribute to. See the
2298 * AppleEvent data type.
2299 *
2300 * theAEKeyword:
2301 * The keyword for the attribute to add. If the Apple event
2302 * already includes an attribute with this keyword, the attribute
2303 * is replaced.
2304 *
2305 * typeCode:
2306 * The descriptor type for the attribute to add.
2307 *
2308 * dataPtr:
2309 * A pointer to the data for the attribute to add.
2310 *
2311 * dataSize:
2312 * The length, in bytes, of the data for the attribute to add.
2313 *
2314 * Availability:
2315 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2316 * CarbonLib: in CarbonLib 1.0 and later
2317 * Non-Carbon CFM: in InterfaceLib 7.1 and later
2318 }
AEPutAttributePtrnull2319 function AEPutAttributePtr( var theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; typeCode: DescType; dataPtr: {const} UnivPtr; dataSize: Size ): OSErr; external name '_AEPutAttributePtr';
2320 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2321
2322
2323 {
2324 * AEPutAttributeDesc()
2325 *
2326 * Summary:
2327 * Adds a descriptor and a keyword to an Apple event as an attribute.
2328 *
2329 * Discussion:
2330 * The AEPutAttributeDesc function takes a descriptor and a keyword
2331 * and adds them to an Apple event as an attribute. If the
2332 * descriptor type required for the attribute is different from the
2333 * descriptor type of the descriptor, the Apple Event Manager
2334 * attempts to coerce the descriptor into the required type, with
2335 * one exception: the Apple Event Manager does not attempt to coerce
2336 * the data for an address attribute, thereby allowing applications
2337 * to use their own address types.
2338 *
2339 * Mac OS X threading:
2340 * Thread safe since version 10.2
2341 *
2342 * Parameters:
2343 *
2344 * theAppleEvent:
2345 * A pointer to the Apple event to add an attribute to. See the
2346 * AppleEvent data type.
2347 *
2348 * theAEKeyword:
2349 * The keyword for the attribute to add. If the Apple event
2350 * already includes an attribute with this keyword, the attribute
2351 * is replaced.
2352 *
2353 * theAEDesc:
2354 * A pointer to the descriptor to assign to the attribute. The
2355 * descriptor type of the specified descriptor should match the
2356 * defined descriptor type for that attribute.
2357 *
2358 * Availability:
2359 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2360 * CarbonLib: in CarbonLib 1.0 and later
2361 * Non-Carbon CFM: in InterfaceLib 7.1 and later
2362 }
AEPutAttributeDescnull2363 function AEPutAttributeDesc( var theAppleEvent: AppleEvent; theAEKeyword: AEKeyword; const (*var*) theAEDesc: AEDesc ): OSErr; external name '_AEPutAttributeDesc';
2364 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2365
2366
2367 {*************************************************************************
2368 AppleEvent Serialization Support
2369
2370 AESizeOfFlattenedDesc, AEFlattenDesc, AEUnflattenDesc
2371
2372 These calls will work for all AppleEvent data types and between different
2373 versions of the OS (including between Mac OS 9 and X)
2374
2375 Basic types, AEDesc, AEList and AERecord are OK, but AppleEvent records
2376 themselves may not be reliably flattened for storage.
2377 *************************************************************************}
2378 {
2379 * AESizeOfFlattenedDesc()
2380 *
2381 * Discussion:
2382 * Returns the amount of buffer space needed to flatten the AEDesc.
2383 * Call this before AEFlattenDesc to make sure your buffer has
2384 * enough room for the operation.
2385 *
2386 * Mac OS X threading:
2387 * Thread safe since version 10.2
2388 *
2389 * Parameters:
2390 *
2391 * theAEDesc:
2392 * A pointer to the descriptor to be flattened.
2393 *
2394 * Availability:
2395 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2396 * CarbonLib: in CarbonLib 1.4 and later
2397 * Non-Carbon CFM: not available
2398 }
AESizeOfFlattenedDescnull2399 function AESizeOfFlattenedDesc( const (*var*) theAEDesc: AEDesc ): Size; external name '_AESizeOfFlattenedDesc';
2400 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2401
2402
2403 {
2404 * AEFlattenDesc()
2405 *
2406 * Discussion:
2407 * Fills a buffer with a flattened representation of the AEDesc and
2408 * returns the amount of buffer used in actualSize. If bufferSize
2409 * was too small it returns errAEBufferTooSmall (-1741) and does not
2410 * fill in any of the buffer. The resulting buffer is only useful
2411 * with an AEUnflattenDesc call.
2412 * Note: if you pass a NULL buffer pointer it returns noErr but
2413 * fills in the actualSize field anyway.
2414 *
2415 * Mac OS X threading:
2416 * Thread safe since version 10.2
2417 *
2418 * Parameters:
2419 *
2420 * theAEDesc:
2421 * A pointer to the descriptor to be flattened.
2422 *
2423 * buffer:
2424 * A pointer to memory, allocated by the application, where the
2425 * flattened data will be stored. See the bufferSize parameter for
2426 * information on how large a buffer you should allocate.
2427 *
2428 * bufferSize:
2429 * The size of the buffer pointed to by buffer. Prior to calling
2430 * AEFlattenDesc, you call the AESizeOfFlattenedDesc function to
2431 * determine the required size of the buffer for the flatten
2432 * operation.
2433 * If bufferSize is too small, AEFlattenDesc returns
2434 * errAEBufferTooSmall and doesn't store any data in the buffer.
2435 *
2436 * actualSize:
2437 * A pointer to a size variable. On return, the variable contains
2438 * the actual size of the flattened data. You can specify NULL for
2439 * this parameter if you do not care about the returned size.
2440 *
2441 * Availability:
2442 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2443 * CarbonLib: in CarbonLib 1.4 and later
2444 * Non-Carbon CFM: not available
2445 }
AEFlattenDescnull2446 function AEFlattenDesc( const (*var*) theAEDesc: AEDesc; buffer: Ptr; bufferSize: Size; var actualSize: Size ): OSStatus; external name '_AEFlattenDesc';
2447 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2448
2449
2450 {
2451 * AEUnflattenDesc()
2452 *
2453 * Discussion:
2454 * Allocates an AEDesc (given a Null Desc) given a flattened data
2455 * buffer. It assumes it was given a good buffer filled in by
2456 * AEFlattenDesc. It returns paramErr if it discovers something
2457 * fishy about the buffer.
2458 *
2459 * Mac OS X threading:
2460 * Thread safe since version 10.2
2461 *
2462 * Parameters:
2463 *
2464 * buffer:
2465 * A pointer to memory, allocated by the application, that
2466 * contains flattened data produced by a previous call to
2467 * AEFlattenDesc.
2468 *
2469 * result:
2470 * A null descriptor. On successful completion, points to a
2471 * descriptor created from the flattened data. The caller is
2472 * responsible for disposing of the descriptor.
2473 *
2474 * Availability:
2475 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2476 * CarbonLib: in CarbonLib 1.4 and later
2477 * Non-Carbon CFM: not available
2478 }
AEUnflattenDescnull2479 function AEUnflattenDesc( buffer: {const} UnivPtr; var result: AEDesc ): OSStatus; external name '_AEUnflattenDesc';
2480 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2481
2482
2483 {*************************************************************************
2484 The following calls are necessary to deal with opaque data in AEDescs, because the
2485 traditional way of dealing with a basic AEDesc has been to dereference the dataHandle
2486 directly. This is not supported under Carbon.
2487 *************************************************************************}
2488 {
2489 AEGetDescData no longer supports automatic coercion. If you'd like to
2490 coerce the descriptor use AECoerceDesc.
2491 }
2492 {
2493 * AEGetDescData()
2494 *
2495 * Discussion:
2496 * Gets the data from the specified descriptor. AEGetDescData no
2497 * longer supports automatic coercion. If you'd like to coerce the
2498 * descriptor use AECoerceDesc.
2499 *
2500 * Mac OS X threading:
2501 * Thread safe since version 10.2
2502 *
2503 * Parameters:
2504 *
2505 * theAEDesc:
2506 * A pointer to the descriptor to get the data from.
2507 *
2508 * dataPtr:
2509 * A pointer to a buffer, local variable, or other storage
2510 * location created and disposed of by your application. The size
2511 * in bytes should be the same as the value you pass in the
2512 * maximumSize parameter. On return, contains the data from the
2513 * descriptor.
2514 *
2515 * maximumSize:
2516 * The length, in bytes, of the expected descriptor data. The
2517 * AEGetDescData function will not return more data than you
2518 * specify in this parameter. You typically determine the maximum
2519 * size by calling AEGetDescDataSize.
2520 *
2521 * Availability:
2522 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2523 * CarbonLib: in CarbonLib 1.0 and later
2524 * Non-Carbon CFM: in CarbonAccessors.o 1.0 and later
2525 }
AEGetDescDatanull2526 function AEGetDescData( const (*var*) theAEDesc: AEDesc; dataPtr: UnivPtr; maximumSize: Size ): OSErr; external name '_AEGetDescData';
2527 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2528
2529
2530 {
2531 * AEGetDescDataSize()
2532 *
2533 * Discussion:
2534 * Gets the size, in bytes, of the data in the specified descriptor.
2535 *
2536 * Mac OS X threading:
2537 * Thread safe since version 10.2
2538 *
2539 * Parameters:
2540 *
2541 * theAEDesc:
2542 * A pointer to the descriptor to obtain the data size for. See
2543 * AEDesc.
2544 *
2545 * Availability:
2546 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2547 * CarbonLib: in CarbonLib 1.0 and later
2548 * Non-Carbon CFM: in CarbonAccessors.o 1.0 and later
2549 }
AEGetDescDataSizenull2550 function AEGetDescDataSize( const (*var*) theAEDesc: AEDesc ): Size; external name '_AEGetDescDataSize';
2551 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2552
2553
2554 {
2555 * AEReplaceDescData()
2556 *
2557 * Discussion:
2558 * Copies the specified data into the specified descriptor,
2559 * replacing any previous data.
2560 *
2561 * Mac OS X threading:
2562 * Thread safe since version 10.2
2563 *
2564 * Parameters:
2565 *
2566 * typeCode:
2567 * Specifies the descriptor type of the data pointed to by dataPtr.
2568 *
2569 * dataPtr:
2570 * A pointer to the data to store in the specified descriptor.
2571 *
2572 * dataSize:
2573 * The size, in bytes, of the data pointed to by the dataSize
2574 * parameter.
2575 *
2576 * theAEDesc:
2577 * A pointer to a descriptor. On return, contains the copied data.
2578 *
2579 * Availability:
2580 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2581 * CarbonLib: in CarbonLib 1.0 and later
2582 * Non-Carbon CFM: in CarbonAccessors.o 1.0 and later
2583 }
AEReplaceDescDatanull2584 function AEReplaceDescData( typeCode: DescType; dataPtr: {const} UnivPtr; dataSize: Size; var theAEDesc: AEDesc ): OSErr; external name '_AEReplaceDescData';
2585 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2586
2587
2588 {
2589 * AEGetDescDataRange()
2590 *
2591 * Discussion:
2592 * Retrieve a range of bytes from an AEDesc. This obviates the need
2593 * to retrieve the entire data from the event using AEGetDescData.
2594 * This is only valid for data type AEDescs. If the requested
2595 * length and offset are such that they do not fit entirely with the
2596 * data of the desc, errAEBufferTooSmall is returned.
2597 *
2598 * Mac OS X threading:
2599 * Thread safe since version 10.2
2600 *
2601 * Parameters:
2602 *
2603 * dataDesc:
2604 * A pointer to the descriptor to get the data from.
2605 *
2606 * buffer:
2607 * A pointer to a buffer, local variable, or other storage
2608 * location created and disposed of by your application. The size
2609 * in bytes should be at least as large as the value you pass in
2610 * the length parameter. On return, contains the specified data
2611 * from the descriptor.
2612 *
2613 * offset:
2614 * The zero-based offset to the data to be retrieved from the
2615 * descriptor.
2616 *
2617 * length:
2618 * The number of bytes of contiguous data to retrieve.
2619 *
2620 * Availability:
2621 * Mac OS X: in version 10.2 and later in ApplicationServices.framework
2622 * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
2623 * Non-Carbon CFM: not available
2624 }
AEGetDescDataRangenull2625 function AEGetDescDataRange( const (*var*) dataDesc: AEDesc; buffer: UnivPtr; offset: Size; length: Size ): OSStatus; external name '_AEGetDescDataRange';
2626 (* __OSX_AVAILABLE_STARTING( __MAC_10_2, __IPHONE_NA ) *)
2627
2628
2629 {*************************************************************************
2630 A AEEventHandler is installed to process an AppleEvent
2631 *************************************************************************}
2632 type
constnull2633 AEEventHandlerProcPtr = function( const (*var*) theAppleEvent: AppleEvent; var reply: AppleEvent; handlerRefcon: SRefCon ): OSErr;
2634 AEEventHandlerUPP = AEEventHandlerProcPtr;
2635 {
2636 * NewAEDisposeExternalUPP()
2637 *
2638 * Availability:
2639 * Mac OS X: in version 10.2 and later in ApplicationServices.framework
2640 * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
2641 * Non-Carbon CFM: available as macro/inline
2642 }
NewAEDisposeExternalUPPnull2643 function NewAEDisposeExternalUPP( userRoutine: AEDisposeExternalProcPtr ): AEDisposeExternalUPP; external name '_NewAEDisposeExternalUPP';
2644 (* __OSX_AVAILABLE_STARTING( __MAC_10_2, __IPHONE_NA ) *)
2645
2646 {
2647 * NewAEEventHandlerUPP()
2648 *
2649 * Availability:
2650 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2651 * CarbonLib: in CarbonLib 1.0 and later
2652 * Non-Carbon CFM: available as macro/inline
2653 }
NewAEEventHandlerUPPnull2654 function NewAEEventHandlerUPP( userRoutine: AEEventHandlerProcPtr ): AEEventHandlerUPP; external name '_NewAEEventHandlerUPP';
2655 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2656
2657 {
2658 * DisposeAEDisposeExternalUPP()
2659 *
2660 * Availability:
2661 * Mac OS X: in version 10.2 and later in ApplicationServices.framework
2662 * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
2663 * Non-Carbon CFM: available as macro/inline
2664 }
2665 procedure DisposeAEDisposeExternalUPP( userUPP: AEDisposeExternalUPP ); external name '_DisposeAEDisposeExternalUPP';
2666 (* __OSX_AVAILABLE_STARTING( __MAC_10_2, __IPHONE_NA ) *)
2667
2668 {
2669 * DisposeAEEventHandlerUPP()
2670 *
2671 * Availability:
2672 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2673 * CarbonLib: in CarbonLib 1.0 and later
2674 * Non-Carbon CFM: available as macro/inline
2675 }
2676 procedure DisposeAEEventHandlerUPP( userUPP: AEEventHandlerUPP ); external name '_DisposeAEEventHandlerUPP';
2677 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2678
2679 {
2680 * InvokeAEDisposeExternalUPP()
2681 *
2682 * Availability:
2683 * Mac OS X: in version 10.2 and later in ApplicationServices.framework
2684 * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
2685 * Non-Carbon CFM: available as macro/inline
2686 }
2687 procedure InvokeAEDisposeExternalUPP( dataPtr: {const} UnivPtr; dataLength: Size; refcon: SRefCon; userUPP: AEDisposeExternalUPP ); external name '_InvokeAEDisposeExternalUPP';
2688 (* __OSX_AVAILABLE_STARTING( __MAC_10_2, __IPHONE_NA ) *)
2689
2690 {
2691 * InvokeAEEventHandlerUPP()
2692 *
2693 * Availability:
2694 * Mac OS X: in version 10.0 and later in ApplicationServices.framework
2695 * CarbonLib: in CarbonLib 1.0 and later
2696 * Non-Carbon CFM: available as macro/inline
2697 }
InvokeAEEventHandlerUPPnull2698 function InvokeAEEventHandlerUPP( const (*var*) theAppleEvent: AppleEvent; var reply: AppleEvent; handlerRefcon: SRefCon; userUPP: AEEventHandlerUPP ): OSErr; external name '_InvokeAEEventHandlerUPP';
2699 (* __OSX_AVAILABLE_STARTING( __MAC_10_0, __IPHONE_NA ) *)
2700
2701 {$endc} {TARGET_OS_MAC}
2702
2703 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
2704
2705 end.
2706 {$endc} {not MACOSALLINCLUDE}
2707