Legacy Document

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 macro	Selector
_ResourceDispatch	$7001

RESULT CODES

noErr	0	No error
resourceInMemory	-188	Resource already in memory
inputOutOfBounds	-190	Offset or count out of bounds
resNotFound	-192	Resource 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.