Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: More Macintosh Toolbox /
Chapter 1 - Resource Manager / Resource Manager Reference
Resource Manager Routines / Reading and Writing Partial Resources


ReadPartialResource

You can use the ReadPartialResource procedure to read part of a resource into memory and work with a small subsection of a large resource.

PROCEDURE ReadPartialResource (theResource: Handle; 
                               offset: LongInt; buffer: UNIV Ptr;
                               count: LongInt);
theResource
A handle to a resource.
offset
The beginning of the resource subsection to be read, measured in bytes from the beginning of the resource.
buffer
A pointer to the buffer into which the partial resource is to be read.
count
The length of the resource subsection.
DESCRIPTION
The ReadPartialResource procedure reads the resource subsection identified by the theResource, offset, and count parameters into a buffer specified by the buffer parameter. Your application is responsible for the buffer's memory management. You cannot use the ReleaseResource procedure to release the memory the buffer occupies.

The ReadPartialResource procedure always tries to read resources from disk. If a resource is already in memory, the Resource Manager still reads it from disk, and the ResError function returns the result code resourceInMemory. If you try to read past the end of a resource or the value of the offset parameter is out of bounds, ResError returns the result code inputOutOfBounds. If the handle in the parameter theResource doesn't refer to a resource in an open resource fork, ResError returns the result code resNotFound.

When using partial resource routines, you should call the SetResLoad procedure, specifying FALSE for the load parameter, before you call GetResource. Using the SetResLoad procedure prevents the Resource Manager from reading the entire resource into memory. Be sure to restore the normal state by calling SetResLoad again, with the load parameter set to TRUE, immediately after you call GetResource. Then use ReadPartialResource to read a portion of the resource into a buffer.

Note
If the entire resource is in memory and you want only part of its data, it's faster to use the Memory Manager procedure BlockMove instead of the ReadPartialResource procedure. If you read a partial resource into memory and then change its size, you can use SetResourceSize to change the entire resource's size on disk as necessary.
SPECIAL CONSIDERATIONS
The ReadPartialResource procedure may move or purge memory blocks in the application heap. Your application should not call this procedure at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine se.lector for ReadPartialResource are
Trap macroSelector
_ResourceDispatch$7001

RESULT CODES
noErr0No error
resourceInMemory-188Resource already in memory
inputOutOfBounds-190Offset or count out of bounds
resNotFound-192Resource not found
SEE ALSO
To check for errors, call the ResError function as described on page 1-47.

For an example of the use of the ReadPartialResource procedure, see Listing 1-12 on page 1-35.

For descriptions of the GetResource, SetResLoad, and ReleaseResource routines, see page 1-68, page 1-74, and page 1-101, respectively. For a description of the SetResourceSize procedure, see page 1-109.

For information about the Memory Manager procedure BlockMove, see Inside Macintosh: Memory.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996