Carbon


HandToHand

Header: MacMemory.h Carbon status: Supported

Copies all of the data from one relocatable block to a new relocatable block.

OSErr HandToHand (
    Handle *theHndl
);
Parameter descriptions
theHndl

A handle to the relocatable block whose data HandToHand will copy. On return, theHndl contains a handle to a new relocatable block whose data duplicates the original.

function result

A result code. A result code.

DISCUSSION

The HandToHand function attempts to copy the information in the relocatable block to which theHndl is a handle; if successful, HandToHand sets theHndl to a handle pointing to the new relocatable block. HandToHand creates the new relocatable block in the same heap zone as the original block (which might not be the current heap zone).

If successful in creating a new relocatable block, the HandToHand function does not duplicate the properties of the original block. The new block is unlocked, unpurgeable, and not a resource. Call HLock, HPurge, or HSetRBit (or the combination of HGetState and HSetState) to adjust the properties of the new block.

To copy only part of a relocatable block into a new relocatable block, use the PtrToHand function. Before calling PtrToHand, lock and dereference the handle pointing to the relocatable block you want to copy.

Because HandToHand replaces its parameter with the new handle, you should retain the original parameter value somewhere else, otherwise you will not be able to access it. Here is an example:

Handle original, copy; OSErr myErr; ... copy = original; /*both handles access same block*/ myErr = HandToHand(copy); /*copy now points to copy of block*/

Because HandToHand allocates memory, you should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)