TweetFollow Us on Twitter

MACINTOSH C CARBON
MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
© 2001 K. J. Bricknell
Go to Contents Go to Program Listing

CHAPTER 19

MORE ON RESOURCES, AND CORE FOUNDATION PREFERENCES

Introduction

Chapter 1 covered the basics of creating standard resources for an application's resource file and with reading in standard resources from application files and the system. In addition, the demonstration programs in preceding chapters have all involved the reading in of standard resources from those files.

This chapter is concerned with aspects of resources not covered at Chapter 1, including search paths, detaching and copying resources, creating, opening, and closing resource files, and reading from and writing to resource files. In addition, the accompanying demonstration program demonstrates the creation of custom resources, together with reading such resources from, and writing them to, the resource forks of files other than application and System files.

This chapter also addresses the matter of storing and retrieving application preferences using Core Foundation Preferences Services.

Search Path for Resources

Preamble

The Resource Manager follows a defined search path to find a resource when you use a Resource Manager function to read, or perform an operation on, a resource,. The different files whose resource forks may constitute the search path are therefore of some relevance. The following summarises the typical locations of resources used by an application:

Resource Fork of:

Typical Resources Therein

Comments

System file

Sounds, icons, cursors, etc.

On startup, the Resource Manager creates a special zone within the system heap, creates a resource map which points to system-resident resources, opens the resource fork of the System file, and reads its resource map into memory.

Application file

Descriptions of menus, windows, controls, icons, etc.

Text used in dialogs or help balloons.

When a user opens an application, system software automatically opens the application's resource fork.

Application's preferences file

The user's global preferences for the application.

An application should typically open the preferences file at application launch, and leave it open.

Application's document file

Information specific only to this document, such as its window's last size and location.

When an application opens a document file, it should typically opens the file's resource fork as well as its data fork.

Current Resource File

When your application opens the resource fork of a file, that file becomes the current resource file. However, your application can change the current resource file, if necessary, using the function UseResFile.

The resource fork of a file is also called the resource file because, in some respects, you can treat it as if it were a separate file.

The current resource file is always the first file in the search path. It is also the file on which most Resource Manager functions assume they should operate.

Default Search Order

During its search for a resource, if the Resource Manager cannot find the resource in the current resource file, it continues searching until it either finds the resource or has searched all files in the search path.

The Resource Manager normally looks first in the resource map in memory of the last resource fork your application opened. If the resource is not found there, the resource maps of each resource file open to your application are searched in reverse order of opening. If the resource is not found there, your application's resource map is searched. If the resource has still not been found, the searches continues in the System file's resource map.

Implications of the Default Search Order

The implications of this search order are that it allows your application to:

  • Access resources in the System file.

  • Override resources in the System file.

  • Override your application's resources with document-specific resources.

  • Share a resource amongst multiple files by storing it in the application's resource fork.

Setting the Current Resource File To Dictate the Search Order

You can, of course, rely on the Resource Manager's search order to find a particular resource; however, it is best to set the current resource file to the file containing the desired resource before reading and writing resource data. This ensures that that file will be searched first, thus possibly obviating unnecessary searches of other files.

As previously stated, the function UseResFile is used to set the current resource file. Note that UseResFile takes as its single parameter a file reference number, which identifies an access path to the resource fork. The Resource Manager assigns a resource file a file reference number when it opens that file.

You can get the file reference number of the current resource file using the function CurResFile.

Restricting the Search to the Current Resource File

The search path may be restricted to the current resource file by using Resource Manager functions (such as Get1Resource) which look only in the current resource file's resource map when searching for a specific resource.

Releasing and Detaching Resources

When you have finished using a resource, you typically call ReleaseResource, which releases the memory associated with that resource and sets the handle's master pointer to NULL, thus making your application's handle to the resource invalid. If the application needs the resource later, it must get a valid handle to the resource by reading the resource into memory again using a function such as GetResource.

Your application can use DetachResource to replace a resource's handle in the resource map with NULL without releasing the associated memory. DetachResource may thus be used when you want your application to access the resource's data directly, without the aid of the Resource Manager, or when you need to pass the handle to a function which does not accept a resource handle. For example, the AddResource function, which makes arbitrary data in memory into a resource, requires a handle to data, not a handle to a resource.

DetachResource is useful when you want to copy a resource. The procedure is to read in the resource using GetResource, detach the resource to disassociate it from its resource file, and then copy the resource to a destination file using AddResource.

Creating, Opening and Closing Resource Forks

Opening an Application's Resource Fork

As previously stated, the system software automatically opens your application's resource fork at application launch. The only action required by your application at launch is to call CurResFile to save the file reference number for the application's resource fork.

Creating and Opening a Resource Fork

Creating a Resource Fork

If your application needs to save resources to the resource fork of a file, and assuming the resource fork does not already exist, it must first create the resource fork.. A call to FSpCreateResFile will create the resource fork. FSpCreateResFile requires four parameters: a file system specification structure; the application's signature; the file type; the script code. The effect of FSpCreateResFile varies as follows:

  • If the file specified by the file system specification structure does not already exist (that is, the file has neither a data fork nor a resource fork), the function:

    • Creates a file with an empty resource fork and resource map.

    • Sets the creator, type, and script code fields of the file's catalog information structure to the specified values.

  • If the data fork of the file specified by the file system specification structure already exists but the file has a zero-length resource fork, the function:

    • Creates an empty resource fork and resource map.

    • Changes the creator, type, and script code fields of the catalog information structure of the file to the specified values.

  • If the file specified by the file system specification structure already exists and includes a resource fork with a resource map, the function does nothing.

Opening a Resource Fork

After creating a resource fork, and before attempting to write to it, you must open it using FSpOpenResFile. FSpOpenResFile returns a file reference number which, as previously stated, may be used to change or limit the Resource Manager's search order.

Note that, although the file reference number for the data fork and the resource fork usually match, you should not assume that this is always the case.

As previously stated, when you open a resource fork, the Resource Manager resets the search path so that the file whose resource fork you just opened becomes the current resource file.

After opening a resource fork, you can use Resource Manager functions to write resources to it.

It is possible to write to the resource fork using File Manager functions. However, in general, you should always use Resource Manager functions.

Closing a Resource Fork

When you are finished using a resource fork that your application explicitly opened, you should close it using CloseResFile. Note that the Resource Manager automatically closes any resource forks opened by your application that are still open when your application calls ExitToShell.

Reading and Manipulating Resources

Depending on which Resource Manager function is used to read resources from a resource fork, you specify the resource to be read by either its resource type and resource ID or its resource type and resource name.

Reading From the Resource Map Without Loading the Resource

Those Resource Manager functions that return handles to resources normally read the resource data into memory if it is not already there. Sometimes, however, you may want to read, say, resource types and attributes from the resource map without reading the resource data into memory. Calling SetResLoad with the load parameter set to false causes subsequent calls to those functions which return handles to resources to not load the resource data to memory. (To read the resource data into memory after a call to SetResLoad with the load parameter set to false, call LoadResource.)

If you call SetResLoad with the load parameter set to false, be sure to call it again with the parameter set to true as soon as possible. Other parts of the system software that call the Resource Manager rely on the default setting (that is, the load parameter set to true), and some functions will not work properly if resources are not loaded automatically.

Indexing Through Resources

The Resource Manager provides functions which let you index through all resources of a given type (for example, using CountResources and GetIndResource). This can be useful when you want to read all resources of a given type.

Writing Resources

When you have opened a resource fork, you can write resources to it (assuming it is the current resource file).

A call to AddResource creates a new entry for a resource in the resource map in memory (but not on the disk) and sets that entry's location to refer to that resource's data. A call to either UpdateResFile or WriteResFile will then write the resource to disk. Note that you usually need to set the current resource file to the desired file before calling AddResource because AddResource always adds the resource to the resource map in memory which corresponds to the current resource file.

When you change a resource referenced through the resource map in memory, you should call ChangedResource to set the resChanged attribute of that resource's resource map entry. ChangedResource reserves enough disk space to contain the changed resource. Immediately after calling ChangedResource, you should call UpdateResFile or WriteResFile to write the changed resource data to disk.

The difference between UpdateResFile and WriteResFile is as follows:

  • UpdateResFile writes those resources which have been added or changed to disk. It also writes the entire resource map to disk, overwriting its previous contents.

  • WriteResFile writes only the resource data of a single resource to disk and does not update the resource's entry in the resource map on disk.

Care with Purgeable Resources

If you are changing purgeable resources, you should use the Memory Manager function HNoPurge to ensure that the Resource Manager does not purge the resource while your application is in the process of changing it.

Partial Resources

Some resources, such as 'snd ' (Mac OS 8/9) and 'sfnt' resources, can be too large to fit into available memory. In these cases, you can read a portion of the resource into memory, or alter a section of the resource while it is still on disk, using the functions ReadPartialResource and WritePartialResource.

Application Preferences

Many applications allow the user to set application preferences, which the application stores in a preferences file and retrieves when the application is launched. On Mac OS 8/9, your Preferences file should be located in the special folder titled Preferences provided by the operating system. The Preferences folder is located in the System folder. On Mac OS X, preferences are stored in the Preferences folder in the Library folder in each user's home directory (~/Library/Preferences).

You can save your application's preferences as a custom resource to the resource fork of your preferences file. Alternatively, and more correctly in the Mac OS X era, you can use the methodology provided by Core Foundation Preferences Services.

Using Core Foundation Preferences Services

Using Core Foundation Preferences Services involves storing values associated with a key, the key being used to later retrieve the value. The concept is similar to that applying to the key/value pairs used in information property lists (see Chapter 9).

Application ID

The name of the file in which Preference Services stores preferences information is specified by an application ID. For Mac OS X, this should be the same as the name associated with the CFBundleIdentifier key in the information property list in your application's 'plst' resource. It thus takes the form of a Java package name, that is, a unique domain name followed by the application's name (for example, com.MyCompany.MyApplication). For Mac OS 8/9, it is sufficient to simply use the application's name. (Indeed, this abbreviation will be essential if the application ID in Java package form exceeds the 31-character limit for Mac OS 8/9 file names.)

Setting, Storing and Retrieving a Preference

You use the function CFPreferencesSetAppValue to set a preferences value. The following example sets a value which specifies that the application should use a full screen display:

     CFStringRef applicationID = CFSTR("com.MyCompany.MyApplication");
     CFStringRef fullScreenKey = CFSTR("fullScreen");
     CFStringRef yes           = CFSTR("yes");
     CFStringRef no            = CFSTR("no");

     CFPreferencesSetAppValue(fullScreenKey,yes,applicationID);

CFPreferencesSetAppValue stores the value in a cache owned by your application. To flush the cache to permananent storage, you must call the function CFPreferencesAppSynchronize, passing in the application ID.

You would use the function CFPreferencesGetAppBooleanValue to retrieve the value, as in the following example:

     CFStringRef applicationID = CFSTR("com.MyCompany.MyApplication");
     CFStringRef fullScreenKey = CFSTR("fullScreen");
     Boolean     booleanValue, success;

     booleanValue = CFPreferencesGetAppBooleanValue(fullScreenKey,applicationID,&success);

You can use CFPreferencesGetAppIntegerValue to retrieve integer values (which are stored as strings) in the same way.

Preference Domains

Preference Services uses the concept of domains when creating or searching for a preference. User name, host name, and application ID identify a domain. CFPreferencesSetAppValue uses the current user and "any host" domain qualifiers as the default, which is why only the application ID is passed in the function call. Alternative low-level Preferences Services functions are available to specify an exact domain.

Main Resource Manager Constants, Data Types and Functions

Constants

Resource Attributes

resSysHeap    = 64  System or application heap?
resPurgeable  = 32  Purgeable resource?
resLocked     = 16  Load it in locked?
resProtected  = 8  Protected?
resPreload    = 4  Load in on OpenResFile?
resChanged    = 2  Resource changed?

Data Types

typedef unsigned long  FourCharCode;
typedef FourCharCode   ResType;

Functions

Initialising the Resource Manager

short  InitResources(void);

Checking for Errors

short  ResError(void);

Creating an Empty Resource Fork

void  FSpCreateResFile(const FSSpec *spec,OSType creator,OSType fileType,ScriptCode
      scriptTag);

Opening Resource Forks

short  FSpOpenResFile(const FSSpec *spec,SignedByte permission);

Getting and Setting the Current Resource File

void   UseResFile(short refNum);
short  CurResFile(void);
short  HomeResFile(Handle theResource);

Reading Resources Into Memory

Handle  GetResource(ResType theType,short theID);
Handle  Get1Resource(ResType theType,short theID);
Handle  GetNamedResource(ResType theType,ConstStr255Param name);
Handle  Get1NamedResource(ResType theType,ConstStr255Param name);
void    SetResLoad(Boolean load);
void    LoadResource(Handle theResource);

Getting and Setting Resource Information

void   GetResInfo(Handle theResource,short *theID,ResType *theType,Str255 name);
void   SetResInfo(Handle theResource,short theID,ConstStr255Param name);
short  GetResAttrs(Handle theResource);
void   SetResAttrs(Handle theResource,short attrs);

Modifying Resources

void  ChangedResource(Handle theResource);
void  AddResource(Handle theResource,ResType theType,short theID,ConstStr255Param name);

Writing to Resource Forks

void  UpdateResFile(short refNum);
void  WriteResource(Handle theResource);

Getting a Unique Resource ID

short  UniqueID(ResType theType);
short  Unique1ID(ResType theType);

Counting and Listing Resource Types

short   CountResources(ResType theType);
short   Count1Resources(ResType theType);
Handle  GetIndResource(ResType theType,short index);
Handle  Get1IndResource(ResType theType,short index);
short   CountTypes(void);
short   Count1Types(void);
void    GetIndType(ResType *theType,short index);
void    Get1IndType(ResType *theType,short index);

Getting Resource Sizes

long  GetResourceSizeOnDisk(Handle theResource);
long  GetMaxResourceSize(Handle theResource);

Disposing of Resources and Closing Resource Forks

void  ReleaseResource(Handle theResource);
void  DetachResource(Handle theResource);
void  RemoveResource(Handle theResource);
void  CloseResFile(short refNum);

Getting and Setting Resource Fork Attributes

short  GetResFileAttrs(short refNum);
void   SetResFileAttrs(short refNum,short attrs);

Main Core Foundation Preferences Services Functions

void    CFPreferencesSetAppValue(CFStringRef key,CFPropertyListRef value,
        CFStringRef applicationID);
void    CFPreferencesSetValue(CFStringRef key,CFPropertyListRef value,
        CFStringRef applicationID,CFStringRef userName,CFStringRef hostName);
Boolean CFPreferencesAppSynchronize(CFStringRef applicationID);
Boolean CFPreferencesSynchronize(CFStringRef applicationID,CFStringRef userName,
        CFStringRef hostName);
Boolean CFPreferencesGetAppBooleanValue(CFStringRef key,CFStringRef applicationID,
        Boolean *keyExistsAndHasValidFormat);
CFIndex CFPreferencesGetAppIntegerValue(CFStringRef key,CFStringRef applicationID,
        Boolean *keyExistsAndHasValidFormat);

 
AAPL
$112.65
Apple Inc.
+3.24
MSFT
$47.52
Microsoft Corpora
+1.78
GOOG
$511.10
Google Inc.
+6.21

MacTech Search:
Community Search:

Software Updates via MacUpdate

Mellel 3.3.7 - Powerful word processor w...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
ScreenFlow 5.0.1 - Create screen recordi...
Save 10% with the exclusive MacUpdate coupon code: AFMacUpdate10 Buy now! ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your... Read more
Simon 4.0 - Monitor changes and crashes...
Simon monitors websites and alerts you of crashes and changes. Select pages to monitor, choose your alert options, and customize your settings. Simon does the rest. Keep a watchful eye on your... Read more
BBEdit 11.0.2 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
ExpanDrive 4.2.1 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Adobe After Effects CC 2014 13.2 - Creat...
After Effects CC 2014 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous After Effects customer). After Effects CS6 is still available... Read more
Command-C 1.1.7 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Tidy Up 4.0.2 - Find duplicate files and...
Tidy Up is a complete duplicate finder and disk-tidiness utility. With Tidy Up you can search for duplicate files and packages by the owner application, content, type, creator, extension, time... Read more
Typinator 6.3 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
GraphicConverter 9.5 - Graphics editor w...
GraphicConverter is an all-purpose image-editing program that can import 200 different graphic-based formats, edit the image, and export it to any of 80 available file formats. The high-end editing... Read more

Latest Forum Discussions

See All

Shift - Photo Filters Designed By You (...
Shift - Photo Filters Designed By You 1.0 Device: iOS Universal Category: Photography Price: $.99, Version: 1.0 (iTunes) Description: | Read more »
Elastic Drums (Music)
Elastic Drums 1.0 Device: iOS iPhone Category: Music Price: $3.99, Version: 1.0 (iTunes) Description: *** Introduction price 3,99$ instead of 7,99$ *** Elastic Drums is a music app with 6 channels of synthesized drum sounds, a step... | Read more »
Fireworks Simulator (Games)
Fireworks Simulator 1.0.8 Device: iOS Universal Category: Games Price: $.99, Version: 1.0.8 (iTunes) Description: *** 50% discount – For a short time only *** You can play Fireworks Simulator on these devices: - iPhone 5, 5s, 5c, 6,... | Read more »
Nicky's Gift (Games)
Nicky's Gift 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Everybody! Merry Christmas! There's 48 levels in the game. Let's go! Nicky's Gift | Read more »
The Hit List — Simply Powerful Tasks, To...
The Hit List — Simply Powerful Tasks, To-Dos, Projects, & Reminders 2.0 Device: iOS iPhone Category: Productivity Price: $9.99, Version: 2.0 (iTunes) Description: >> LAUNCH SPECIAL: The Hit List 2 for iPhone is ONLY $9.99... | Read more »
Mahjong Journey Review
Mahjong Journey Review By Jennifer Allen on December 18th, 2014 Our Rating: :: STEADY MATCHINGiPad Only App - Designed for the iPad Aimed at the more laid back gamer, Mahjong Journey isn’t for everyone, but those looking for some... | Read more »
Emoji Type - custom keyboard with predic...
Emoji Type - custom keyboard with predictive emojis 0.4.0 Device: iOS iPhone Category: Utilities Price: $.99, Version: 0.4.0 (iTunes) Description: Emoji Type is custom keyboard for iOS 8 that auto suggests emojis as you type. ABOUT... | Read more »
Game of the Year 2014 – 148Apps Staff Pi...
The end of 2014 is almost here, which can only mean one thing. Okay it can mean a lot of things, but in this specific context it means Game of the Year lists! Which is why the 148Apps staff have all picked their favorites from the past year. And why... | Read more »
UponPixels Review
UponPixels Review By Jennifer Allen on December 18th, 2014 Our Rating: :: CREATIVE TYPOGRAPHYUniversal App - Designed for iPhone and iPad Add cool typography and objects to your photos with the easy to use UponPixels.   | Read more »
The Vikings are Coming! CastleStorm’s Ne...
The Vikings are Coming! CastleStorm’s New Update Adds a Survival Mode Posted by Jessica Fisher on December 18th, 2014 [ permalink ] | Read more »

Price Scanner via MacPrices.net

Save up to $400 on MacBooks with Apple Certif...
The Apple Store has Apple Certified Refurbished 2014 MacBook Pros and MacBook Airs available for up to $400 off the cost of new models. An Apple one-year warranty is included with each model, and... Read more
Save up to $300 on Macs, $30 on iPads with Ap...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
iOS and Android OS Targeted by Man-in-the-Mid...
Cloud services security provider Akamai Technologies, Inc. has released, through the company’s Prolexic Security Engineering & Research Team (PLXsert), a new cybersecurity threat advisory. The... Read more
KMI MIDI K-Board Great Gift for Amateur &...
The K-Board is a MIDI Nano keyboard for music creation for iPad, Android, And computers; the easiest way to make music with iPads & Android tablets, and Mac, Windows, or Linux computers. Ultra-... Read more
Amazon offers 15-inch 2.2GHz Retina MacBook P...
 Amazon.com has the 15″ 2.2GHz Retina MacBook Pro on sale for $1699 including free shipping. Their price is $300 off MSRP. Stock is limited, so act now if you’re interested. Read more
Holiday sales continue: MacBook Pros for up t...
 B&H Photo has new MacBook Pros on sale for up to $300 off MSRP as part of their Holiday pricing. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1699... Read more
Holiday sale: Mac minis available for up to $...
 B&H Photo has new 2014 Mac minis on sale for up to $80 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 1.4GHz Mac mini: $459 $40 off MSRP - 2.6GHz Mac mini: $629 $70 off... Read more
Google Search App For iOS Gets A Major Makeov...
Google has given iOS users an early Christmas present with a substantial update of it’s not-very-often-upgraded Google Search app. Google Search has been my go-to tool for Web searches since it was... Read more
ShopKeep Apple Pay And Chip Card Reader Avail...
ShopKeep, a cloud-based technology provider to more than 10,000 small business owners to manage retail shops and restaurants with iPads, has released its new Apple Pay and chip card reader. This... Read more
Holiday sale! 27-inch 5K iMac for $2299, save...
 B&H Photo has the 27″ 3.5GHz 5K iMac in stock today and on sale for $2299 including free shipping plus NY sales tax only. Their price is $200 off MSRP, and it’s the lowest price available for... Read more

Jobs Board

Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.