Apple Event Manager Reference
Total Page：16
File Type：pdf, Size：1020Kb
Apple Event Manager Reference 2006-09-05 Simultaneously published in the United Apple Computer, Inc. States and Canada. © 1993, 2006 Apple Computer, Inc. Even though Apple has reviewed this document, All rights reserved. APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS No part of this publication may be DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A reproduced, stored in a retrieval system, or PARTICULAR PURPOSE. AS A RESULT, THIS transmitted, in any form or by any means, DOCUMENT IS PROVIDED “AS IS,” AND mechanical, electronic, photocopying, YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND recording, or otherwise, without prior ACCURACY. written permission of Apple Computer, Inc., IN NO EVENT WILL APPLE BE LIABLE FOR with the following exceptions: Any person DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES is hereby authorized to store documentation RESULTING FROM ANY DEFECT OR on a single computer for personal use only INACCURACY IN THIS DOCUMENT, even if and to print copies of documentation for advised of the possibility of such damages. personal use provided that the THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN documentation contains Apple’s copyright LIEU OF ALL OTHERS, ORAL OR WRITTEN, notice. EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any The Apple logo is a trademark of Apple modification, extension, or addition to this Computer, Inc. warranty. Some states do not allow the exclusion or Use of the “keyboard” Apple logo limitation of implied warranties or liability for (Option-Shift-K) for commercial purposes incidental or consequential damages, so the above limitation or exclusion may not apply to without the prior written consent of Apple you. This warranty gives you specific legal may constitute trademark infringement and rights, and you may also have other rights which vary from state to state. unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, AppleScript, AppleTalk, Carbon, Cocoa, FireWire, LocalTalk, Logic, Mac, Mac OS, Macintosh, OpenDoc, QuickDraw, and SANE are trademarks of Apple Computer, Inc., registered in the United States and other countries. eMac, Finder, and Spotlight are trademarks of Apple Computer, Inc. NuBus is a trademark of Texas Instruments. Contents Apple Event Manager Reference 13 Introduction 13 Functions by Task 14 Adding Items to Descriptor Lists 14 Adding Parameters and Attributes to an Apple Event 14 Coercing Descriptor Types 14 Counting the Items in Descriptor Lists 15 Creating an Apple Event 15 Creating and Duplicating Descriptors 15 Creating, Calling, and Deleting Universal Procedure Pointers 15 Creating Descriptor Lists and Apple Event Records 17 Creating Object Specifiers 18 Deallocating Memory for Descriptors 18 Deallocating Memory for Tokens 18 Deleting Descriptors 18 Dispatching Apple Events 18 Getting, Calling, and Removing Object Accessor Functions 19 Getting Data or Descriptors From Apple Events 19 Getting Information About the Apple Event Manager 19 Getting Items From Descriptor Lists 19 Getting the Sizes and Descriptor Types of Descriptors 20 Initializing the Object Support Library 20 Locating Processes on Remote Computers 20 Managing Apple Event Dispatch Tables 21 Managing Coercion Handler Dispatch Tables 21 Managing Special Handler Dispatch Tables 21 Operating On Descriptor Data 21 Requesting More Time to Respond to Apple Events 22 Requesting User Interaction 22 Resolving Object Specifiers 22 Sending an Apple Event 22 Creating Apple Event Structures in Memory 22 Creating Apple Event Structures Using Streams 23 Working With Lower Level Apple Event Functions 24 Serializing Apple Event Data 24 Suspending and Resuming Apple Event Handling 24 Miscellaneous 25 3 2006-09-05 | © 1993, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Functions 25 AEBuildAppleEvent 25 AEBuildDesc 27 AEBuildParameters 28 AECallObjectAccessor 29 AECheckIsRecord 30 AECoerceDesc 30 AECoercePtr 31 AECountItems 32 AECreateAppleEvent 33 AECreateDesc 34 AECreateDescFromExternalPtr 35 AECreateList 37 AECreateRemoteProcessResolver 38 AEDecodeMessage 39 AEDeleteItem 39 AEDeleteParam 40 AEDisposeDesc 41 AEDisposeRemoteProcessResolver 41 AEDisposeToken 42 AEDuplicateDesc 43 AEFlattenDesc 43 AEGetArray 45 AEGetAttributeDesc 46 AEGetAttributePtr 47 AEGetCoercionHandler 48 AEGetDescData 50 AEGetDescDataRange 50 AEGetDescDataSize 51 AEGetEventHandler 52 AEGetInteractionAllowed 53 AEGetNthDesc 53 AEGetNthPtr 55 AEGetObjectAccessor 56 AEGetParamDesc 58 AEGetParamPtr 59 AEGetRegisteredMachPort 60 AEGetSpecialHandler 61 AEGetTheCurrentEvent 62 AEInitializeDesc 63 AEInstallCoercionHandler 63 AEInstallEventHandler 65 AEInstallObjectAccessor 66 AEInstallSpecialHandler 67 AEInteractWithUser 69 AEManagerInfo 70 4 2006-09-05 | © 1993, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS AEObjectInit 71 AEPrintDescToHandle 72 AEProcessAppleEvent 72 AEProcessMessage 74 AEPutArray 75 AEPutAttributeDesc 76 AEPutAttributePtr 77 AEPutDesc 78 AEPutParamDesc 78 AEPutParamPtr 79 AEPutPtr 80 AERemoteProcessResolverGetProcesses 81 AERemoteProcessResolverScheduleWithRunLoop 82 AERemoveCoercionHandler 83 AERemoveEventHandler 83 AERemoveObjectAccessor 85 AERemoveSpecialHandler 86 AEReplaceDescData 87 AEResetTimer 87 AEResolve 88 AEResumeTheCurrentEvent 89 AESend 91 AESendMessage 93 AESetInteractionAllowed 94 AESetObjectCallbacks 95 AESetTheCurrentEvent 97 AESizeOfAttribute 97 AESizeOfFlattenedDesc 98 AESizeOfNthItem 99 AESizeOfParam 99 AEStreamClose 100 AEStreamCloseDesc 101 AEStreamCloseList 101 AEStreamCloseRecord 102 AEStreamCreateEvent 102 AEStreamOpen 104 AEStreamOpenDesc 104 AEStreamOpenEvent 105 AEStreamOpenKeyDesc 105 AEStreamOpenList 106 AEStreamOpenRecord 106 AEStreamOptionalParam 107 AEStreamSetRecordType 108 AEStreamWriteAEDesc 108 AEStreamWriteData 109 AEStreamWriteDesc 110 5 2006-09-05 | © 1993, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS AEStreamWriteKey 110 AEStreamWriteKeyDesc 111 AESuspendTheCurrentEvent 112 AEUnflattenDesc 113 CreateCompDescriptor 114 CreateLogicalDescriptor 115 CreateObjSpecifier 116 CreateOffsetDescriptor 116 CreateRangeDescriptor 117 DisposeAECoerceDescUPP 118 DisposeAECoercePtrUPP 118 DisposeAEDisposeExternalUPP 119 DisposeAEEventHandlerUPP 119 DisposeAEFilterUPP 119 DisposeAEIdleUPP 120 DisposeOSLAccessorUPP 120 DisposeOSLAdjustMarksUPP 120 DisposeOSLCompareUPP 121 DisposeOSLCountUPP 121 DisposeOSLDisposeTokenUPP 121 DisposeOSLGetErrDescUPP 122 DisposeOSLGetMarkTokenUPP 122 DisposeOSLMarkUPP 122 InvokeAECoerceDescUPP 123 InvokeAECoercePtrUPP 123 InvokeAEDisposeExternalUPP 124 InvokeAEEventHandlerUPP 124 InvokeAEFilterUPP 125 InvokeAEIdleUPP 125 InvokeOSLAccessorUPP 126 InvokeOSLAdjustMarksUPP 126 InvokeOSLCompareUPP 127 InvokeOSLCountUPP 127 InvokeOSLDisposeTokenUPP 128 InvokeOSLGetErrDescUPP 128 InvokeOSLGetMarkTokenUPP 128 InvokeOSLMarkUPP 129 NewAECoerceDescUPP 129 NewAECoercePtrUPP 130 NewAEDisposeExternalUPP 130 NewAEEventHandlerUPP 130 NewAEFilterUPP 131 NewAEIdleUPP 131 NewOSLAccessorUPP 132 NewOSLAdjustMarksUPP 132 NewOSLCompareUPP 132 6 2006-09-05 | © 1993, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS NewOSLCountUPP 133 NewOSLDisposeTokenUPP 133 NewOSLGetErrDescUPP 133 NewOSLGetMarkTokenUPP 134 NewOSLMarkUPP 134 vAEBuildAppleEvent 135 vAEBuildDesc 136 vAEBuildParameters 137 Callbacks by Task 138 Callbacks When Resolving Remote Processes 138 Callbacks When Creating Apple Events 139 Callbacks When Sending Apple Events 139 Coercing Apple Event Data Callbacks 139 Handling Apple Events Callbacks 139 Object Accessor Callbacks 139 Object Callback Functions 140 Callbacks 140 AECoerceDescProcPtr 140 AECoercePtrProcPtr 142 AEDisposeExternalProcPtr 143 AEEventHandlerProcPtr 144 AEFilterProcPtr 146 AEIdleProcPtr 147 AERemoteProcessResolverCallback 148 OSLAccessorProcPtr 149 OSLAdjustMarksProcPtr 151 OSLCompareProcPtr 152 OSLCountProcPtr 154 OSLDisposeTokenProcPtr 155 OSLGetErrDescProcPtr 156 OSLGetMarkTokenProcPtr 158 OSLMarkProcPtr 159 Data Types 160 AEArrayData 160 AEBuildError 161 AEDesc 161 AEKeyDesc 162 AERemoteProcessResolverContext 163 ccntTokenRecord 163 IntlText 164 OffsetArray 164 TextRange 164 TextRangeArray 165 TScriptingSizeResource 165 WritingCode 165 AEAddressDesc 165 7 2006-09-05 | © 1993, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS AEArrayDataPointer 166 AEArrayType 166 AECoerceDescUPP 166 AECoercePtrUPP 166 AECoercionHandlerUPP 167 AEDataStorage 167 AEDataStorageType 167 AEDescList 168 AEEventSource 168 AEDisposeExternalUPP 169 AEEventClass 169 AEEventHandlerUPP 169 AEEventID 169 AEFilterUPP 170 AEIdleUPP 170 AEKeyword 170 AERecord 170 AERemoteProcessResolverRef 171 AEReturnID 171 AESendOptions 171 AESendPriority 171 AEStreamRef 172 AETransactionID 172 AppleEvent 172 DescType 173 OffsetArrayHandle 173 OSLAccessorUPP 173 OSLAdjustMarksUPP 173 OSLCompareUPP 174 OSLCountUPP 174 OSLDisposeTokenUPP 174 OSLGetErrDescUPP