Resource Manager Reference May 23, 2003 IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, Apple Computer, Inc. MERCHANTABILITY, OR FITNESS FOR A © 2004 Apple Computer, Inc. PARTICULAR PURPOSE. AS A RESULT, THIS MANUAL IS SOLD ªAS IS,º AND YOU, THE All rights reserved. PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. No part of this publication may be IN NO EVENT WILL APPLE BE LIABLE FOR reproduced, stored in a retrieval system, or DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES transmitted, in any form or by any means, RESULTING FROM ANY DEFECT OR mechanical, electronic, photocopying, INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages. recording, or otherwise, without prior THE WARRANTY AND REMEDIES SET written permission of Apple Computer, Inc., FORTH ABOVE ARE EXCLUSIVE AND IN with the following exceptions: Any person LIEU OF ALL OTHERS, ORAL OR WRITTEN, is hereby authorized to store documentation EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any on a single computer for personal use only modification, extension, or addition to this and to print copies of documentation for warranty. personal use provided that the Some states do not allow the exclusion or limitation of implied warranties or liability for documentation contains Apple’s copyright incidental or consequential damages, so the notice. above limitation or exclusion may not apply to you. This warranty gives you specific legal The Apple logo is a trademark of Apple rights, and you may also have other rights which Computer, Inc. vary from state to state. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and 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, Carbon, Mac, and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries. Finder is a trademark of Apple Computer, Inc. Simultaneously published in the United States and Canada. Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR Contents Chapter 1 Resource Manager Reference 7 Resource Manager Functions 7 Checking for Errors 8 Closing Resource Forks 8 Counting and Listing Resource Types 9 Creating an Empty Resource Fork 14 Disposing of Resources 17 Getting a Unique Resource ID 19 Getting and Setting Resource Fork Attributes 21 Getting and Setting Resource Information 22 Getting and Setting the Current Resource File 26 Getting Resource Sizes 28 Modifying Resources 29 Opening Resource Forks 33 Reading and Writing Partial Resources 38 Reading Resources Into Memory 42 Writing to Resource Forks 48 Working With Universal Procedure Pointers for Resource Manager Callback Functions 51 Miscellaneous 51 Deprecated Functions 59 Resource Manager Callbacks 67 Miscellaneous 67 Resource Manager Data Types 68 ResAttributes 68 ResErrUPP 68 ResFileAttributes 68 ResFileRefNum 68 ResID 68 Resource Manager Constants 68 Resource Manager Result Codes 72 Document Revision History 75 3 © 2004 Apple Computer, Inc. All Rights Reserved. CONTENTS 4 © 2004 Apple Computer, Inc. All Rights Reserved. Tables Document Revision History 75 Table RH-1 Document revision history 75 5 © 2004 Apple Computer, Inc. All Rights Reserved. TABLES 6 © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Resource Manager Reference Framework: CoreServices/CoreServices.h Header: Resources.h The Resource Manager provides routines that allow your application to create, delete, open, read, modify, and write resources get information about them and alter the Resource Manager's search path. A resource is data of any kind stored in a defined format in a file's resource fork. The Resource Manager keeps track of resources in memory. You typically use resources to store the descriptions for user interface elements such as menus, windows, controls, dialog boxes, and icons. In addition, your application can store variable settings, such as the location of a window at the time the user closes the window, in a resource. When the user opens the document again, your application can read the information in the resource and restore the window to its previous location. Carbon supports the Resource Manager, with the following exceptions, which primarily involve ROM resource functions and functions that access the resource map: ■ There is no ROM in Mac OS X, so the ROM-related functions RGetResource and TempInsertROMMap are not supported. ■ There is no way to directly walk the resource chain. Instead, Carbon supplies a small number of new functions for proper management of the resource chain. ■ The function RsrcMapEntry, which provides an interface to the map handle format, is not supported. ■ The low-memory global variables JCheckLoad, TopMapHndl, CurMap, and SysMapHndl are not supported. Note also that you should not attempt to store resources in the system heap, since you will not have the same access to the system heap as you do in previous versions of the Mac OS. Resource Manager Functions Function descriptions are grouped by the tasks for which you use the functions. For an alphabetical list of functions, go to the API index at the end of the document. Resource Manager Functions 7 © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Resource Manager Reference Checking for Errors ResError Determines what error occurred, if any, after calling a Resource Manager function. OSErr ResError (); function result A result code. See ªResource Manager Result Codesº (page 72). If no error occurred, the function returns noErr. If an error occurs at the Resource Manager level, the function returns one of the result codes specific to the Resource Manager. If an error occurs at the Operating System level, the function returns an Operating System result code. In certain cases, the ResError function returns noErr even though a Resource Manager function was unable to perform the requested operation. See the individual function descriptions for details about the circumstances under which this happens. Discussion Resource Manager functions do not report error information directly. Instead, after calling a Resource Manager function, your application should call this function to determine whether an error occurred. You also can use this function to check for an error after application startup (system software opens the resource fork of your application during application startup). Resource Manager functions usually return NULL or ±1 as the function result when there's an error. For Resource Manager functions that return ±1, your application can call the ResError function to determine the specific error that occurred. For Resource Manager functions that return handles, your application should always check whether the value of the returned handle is NULL. If it is, your application can use this function to obtain specific information about the nature of the error. Note, however, that in some cases ResError returns noErr even though the value of the returned handle is NULL. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: Resources.h Closing Resource Forks CloseResFile Closes a resource fork before your application terminates. void CloseResFile ( short refNum ); 8 Resource Manager Functions © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Resource Manager Reference Parameter Descriptions refNum The file reference number for the resource fork to close. If this parameter does not contain a file reference number for a file whose resource fork is open, the function does nothing, and the ResError (page 8) function returns the result code resFNotFound. If the value of this parameter is 0, it represents the System file and is ignored. You cannot close the System file's resource fork. Discussion This function performs four tasks. First, it updates the file by calling the UpdateResFile (page 49) function. Second, it releases the memory occupied by each resource in the resource fork by calling the DisposeHandle function. Third, it releases the memory occupied by the resource map. The fourth task is to close the resource fork. When your application terminates, the Resource Manager automatically closes every resource fork open to your application except the System file's resource fork. You need to call this function only if you want to close a resource fork before your application terminates. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: Resources.h Counting and Listing Resource Types Count1Resources Returns the total number of resources of a given type in the current resource file. short Count1Resources ( ResType theType ); Parameter Descriptions theType A resource type. function result The total number of resources of the given type in the current resource file only. Discussion To check for errors, call the ResError (page 8) function. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: Resources.h Resource Manager Functions 9 © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Resource Manager Reference Count1Types Returns the number of resource types in the current resource file. short Count1Types (); function result The total number of unique resource types in the current resource file. Discussion To check for errors, call the ResError (page 8) function.