Mac OS For QuickTime Programmers Apple Computer, Inc. Technical Publications April, 1998 Apple Computer, Inc. Apple, the Apple logo, Mac, LIMITED WARRANTY ON MEDIA © 1998 Apple Computer, Inc. Macintosh, QuickDraw, and AND REPLACEMENT All rights reserved. QuickTime are trademarks of Apple ALL IMPLIED WARRANTIES ON THIS No part of this publication or the Computer, Inc., registered in the MANUAL, INCLUDING IMPLIED software described in it may be United States and other countries. WARRANTIES OF reproduced, stored in a retrieval The QuickTime logo is a trademark MERCHANTABILITY AND FITNESS system, or transmitted, in any form of Apple Computer, Inc. FOR A PARTICULAR PURPOSE, ARE or by any means, mechanical, Adobe, Acrobat, Photoshop, and LIMITED IN DURATION TO NINETY electronic, photocopying, recording, PostScript are trademarks of Adobe (90) DAYS FROM THE DATE OF or otherwise, without prior written Systems Incorporated or its DISTRIBUTION OF THIS PRODUCT. permission of Apple Computer, Inc., subsidiaries and may be registered in Even though Apple has reviewed this except in the normal use of the certain jurisdictions. manual, APPLE MAKES NO software or to make a backup copy Helvetica and Palatino are registered WARRANTY OR REPRESENTATION, of the software or documentation. trademarks of Linotype-Hell AG EITHER EXPRESS OR IMPLIED, WITH The same proprietary and copyright and/or its subsidiaries. RESPECT TO THIS MANUAL, ITS notices must be affixed to any ITC Zapf Dingbats is a registered QUALITY, ACCURACY, permitted copies as were affixed to trademark of International Typeface MERCHANTABILITY, OR FITNESS the original. This exception does not Corporation. FOR A PARTICULAR PURPOSE. AS A allow copies to be made for others, RESULT, THIS MANUAL IS Simultaneously published in the whether or not sold, but all of the DISTRIBUTED “AS IS,” AND YOU United States and Canada. material purchased (with all backup ARE ASSUMING THE ENTIRE RISK copies) may be sold, given, or loaned Printed in the United States of AS TO ITS QUALITY AND to another person. Under the law, America. ACCURACY. copying includes translating into another language or format. You IN NO EVENT WILL APPLE BE LIABLE may use the software on any FOR DIRECT, INDIRECT, SPECIAL, computer owned by you, but extra INCIDENTAL, OR CONSEQUENTIAL copies cannot be made for this DAMAGES RESULTING FROM ANY purpose. DEFECT OR INACCURACY IN THIS The Apple logo is a trademark of MANUAL, even if advised of the Apple Computer, Inc. Use of the possibility of such damages. “keyboard” Apple logo THE WARRANTY AND REMEDIES (Option-Shift-K) for commercial SET FORTH ABOVE ARE EXCLUSIVE purposes without the prior written AND IN LIEU OF ALL OTHERS, ORAL consent of Apple may constitute OR WRITTEN, EXPRESS OR IMPLIED. trademark infringement and unfair No Apple dealer, agent, or employee is competition in violation of federal authorized to make any modification, and state laws. extension, or addition to this warranty. No licenses, express or implied, are Some states do not allow the exclusion or granted with respect to any of the limitation of implied warranties or technology described in this book. liability for incidental or consequential Apple retains all intellectual damages, so the above limitation or property rights associated with the exclusion may not apply to you. This technology described in this book. warranty gives you specific legal rights, Every effort has been made to ensure and you may also have other rights that the information in this manual is which vary from state to state. accurate. Apple is not responsible for printing or clerical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Contents Figures, Tables, and Listings 13 Preface About This Book 19 Sources of Material 19 Conventions Used in This Book 19 Special Fonts 20 Types of Notes 20 Chapter 1 Overview and Summary 21 Component Management 22 Finding Components 22 Opening and Closing Components 23 Getting Information About a Component 23 Retrieving Component Errors 23 Component Functions 23 Registering Components 24 Dispatching to Component Routines 24 Managing Component Connections 24 Miscellaneous Component Functions 25 Component Manager Data Structures 25 Component Resources 26 Component Manager Constants 26 Mac OS File System 26 Memory Management 27 Mac OS Events 28 Window Management 28 QuickDraw 28 Drawing Environment 29 Graphics Devices 29 QuickDraw Operations Offscreen 29 Pictures 30 Chapter 2 Component Manager 31 Introduction to Components 31 About the Component Manager 33 Using the Component Manager 34 Opening Connections to Components 35 3 Opening a Connection to a Default Component 35 Finding a Specific Component 36 Opening a Connection to a Specific Component 38 Getting Information About a Component 38 Using a Component 39 Closing a Connection to a Component 40 Creating Components 41 The Structure of a Component 41 Handling Requests for Service 46 Responding to the Open Request 47 Responding to the Close Request 49 Responding to the Can Do Request 50 Responding to the Version Request 50 Responding to the Register Request 51 Responding to the Unregister Request 52 Responding to the Target Request 52 Responding to Component-Specific Requests 54 Reporting an Error Code 56 Defining a Component’s Interfaces 56 Managing Components 58 Registering a Component 58 Creating a Component Resource 60 Establishing and Managing Connections 62 Component Manager Reference 65 Data Structures for Applications 65 The Component Description Record 65 Component Identifiers and Component Instances 68 Routines for Applications 69 Finding Components 70 Opening and Closing Components 72 Getting Information About Components 75 Retrieving Component Errors 79 Data Structures for Components 80 The Component Description Record 80 The Component Parameters Record 82 Routines for Components 84 Registering Components 85 Dispatching to Component Routines 91 Managing Component Connections 93 Setting Component Errors 97 Working With Component Reference Constants 98 Accessing a Component’s Resource File 99 Calling Other Components 101 Capturing Components 102 Targeting a Component Instance 104 Changing the Default Search Order 105 4 Application-Defined Routine 106 Resources 107 The Component Resource 107 Constants 114 Result Codes 115 Chapter 3 Introduction to File Management 117 About Files 118 File Forks 118 File Size 120 File Access Characteristics 122 The Hierarchical File System 123 Identifying Files and Directories 126 Using Files 126 Testing for File Management Routines 128 Defining a Document Record 129 Creating a New File 130 Opening a File 132 Reading File Data 136 Writing File Data 137 Saving a File 140 Reverting to a Saved File 144 Closing a File 146 Opening Files at Application Startup Time 148 Using a Preferences File 150 Adjusting the File Menu 151 File Management Reference 152 Data Structures 153 File System Specification Record 153 Standard File Reply Records 153 Application Files Records 155 File Specification Routines 156 File Access Routines 157 Reading, Writing, and Closing Files 158 Manipulating the File Mark 160 Manipulating the End-of-File 162 File and Directory Manipulation Routines 163 Opening, Creating, and Deleting Files 163 Exchanging the Data in Two Files 167 Creating File System Specifications 168 Volume Access Routines 169 Updating Volumes 169 Obtaining Volume Information 170 Application Launch File Routines 171 Result Codes 174 5 Chapter 4 Standard File Package 177 About the Standard File Package 178 Standard User Interfaces 179 Opening Files 179 Saving Files 180 Keyboard Equivalents 182 Customized User Interfaces 182 Saving Files 182 Opening Files 184 Selecting Volumes and Directories 184 User Interface Guidelines 187 Using the Standard File Package 188 Presenting the Standard User Interface 189 Customizing the User Interface 191 Customizing Dialog Boxes 192 Writing a File Filter Function 195 Writing a Dialog Hook Function 196 Writing a Modal-Dialog Filter Function 203 Writing an Activation Procedure 205 Setting the Current Directory 206 Selecting a Directory 209 Selecting a Volume 213 Using the Original Procedures 215 Standard File Package Reference 216 Data Structures 216 Enhanced Standard File Reply Record 217 Original Standard File Reply Record 218 Standard File Package Routines 219 Saving Files 219 Opening Files 224 Application-Defined Routines 230 File Filter Functions 230 Dialog Hook Functions 231 Modal-Dialog Filter Functions 232 Activation Procedures 234 Chapter 5 Introduction to Memory Management 235 About Memory 236 Organization of Memory by the Operating System 236 The System Heap 238 The System Global Variables 238 Organization of Memory in an Application Partition 239 The Application Stack 240 The Application Heap 241 6 The Application Global Variables and A5 World 244 Temporary Memory 245 Virtual Memory 247 Addressing Modes 247 Heap Management 248 Relocatable and Nonrelocatable Blocks 248 Properties of Relocatable Blocks 252 Locking and Unlocking Relocatable Blocks 252 Purging and Reallocating Relocatable Blocks 253 Memory Reservation 254 Heap Purging and Compaction 255 Heap Fragmentation 256 Deallocating Nonrelocatable Blocks 257 Reserving Memory 257 Locking Relocatable Blocks 258 Allocating Nonrelocatable Blocks 259 Summary of Preventing Fragmentation 260 Dangling Pointers 261 Compiler Dereferencing 261 Loading Code Segments 263 Callback Routines 264 Invalid Handles 265 Disposed Handles 265 Empty Handles 266 Fake Handles 267 Low-Memory Conditions 268 Memory Cushions 268 Memory Reserves 269 Grow-Zone