ObjDoRelocation()

Boolean	ObjDoRelocation( /* returns true if error */
        ObjRelocationType		type,				/* type of relocation */
        MemHandle		block,				/* handle of info block */
        void		* sourceData,				/* source of relocation */
        void		* destData);				/* relocated value */

This routine relocates a given word or dword argument and is used for resolving handles and pointers to movable objects. Most often, relocation and unrelocation occur when resources are loaded, swapped, or saved, and this is in most cases taken care of by the kernel.

ObjDoRelocation() takes four parameters:

type: The type of relocation to be performed (RelocationType ). This can be one of the three values shown below.
block: The handle of the block containing the relocation.
sourceData: A pointer to the source of the relocation; this pointer should be cast to the proper type (word or dword) when calling the routine.
destData: A pointer to the value to be returned; this pointer should be cast appropriately when the routine is called. The exact type of return value depends on sourceData and type , above.

The type of relocation to be done affects the type of data passed in sourceData and destData . The relocation type is passed in the type parameter and must be one of the following enumerations of RelocationType :

RELOC_RELOC_HANDLE: The relocation will be from a resource ID to a handle. The sourceData pointer should be cast to type word, and the destData pointer should be cast to type Handle.
RELOC_RELOC_SEGMENT: The relocation will be from a resource ID to a segment address. The sourceData pointer should be cast to type word, and the destData pointer should be cast to type Segment.
RELOC_RELOC_ENTRY_POINT: The relocation will be from either a resource ID or an entry number to an entry point. Both the sourceData pointer and the destData pointer should be cast to type dword.

ObjDoRelocation() returns an error flag that will be true if an error occurs, false otherwise.

The relocation done by this routine can be undone with ObjDoUnRelocation() .

Include: object.h

ObjDoUnRelocation()

Boolean	ObjDoUnRelocation( /* returns true if error */
        ObjRelocationType		type,				/* type of relocation */
        MemHandle		block,				/* handle of info block */
        void		* sourceData,				/* source of relocation */
        void		* destData);				/* relocated value */

This routine unrelocates a given word or dword. It translates a handle, a segment address, or an entry point back into a resource ID. The translation done is the exact reverse of that done by ObjDoRelocation() . See that routine (above) for more information.

ObjDoUnRelocation() returns an error flag that will be true if an error occurs and false if the unrelocation is successful. The unrelocated resource ID will be returned pointed to by the destData pointer.

Include: object.h

See Also: ObjDoRelocation().

ObjDuplicateResource()

MemHandle ObjDuplicateResource(
        MemHandle		blockToDup,					/* handle of resource; must
								 * not be loaded */

        GeodeHandle		owner,					/* owner of duplicate */
        ThreadHandle		burdenThread);					/* burden thread of duplicate */

This routine duplicates an entire object resource block. The new block will be put on the "saved blocks" list so it gets saved to the geode's state file. Usually this is used by the UI to make editable copies of an application's UI resources to ensure the proper state information gets saved. This routine takes three parameters:

blockToDup: The handle of the block to be duplicated. The block must not be resident in memory when ObjDuplicateResource() is called. Also, it can only be a "template" resource--a resource that does not get used by the UI or the application directly, but only gets copied via this routine.
owner: The owner geode of the new block. This should be the geode handle of the owning geode or zero to have the calling geode own it. If you pass an owner of -1, the new block will be owned by the same geode that owns the original.
burdenThread: The thread that will run the block and handle its messages. This should be a thread handle or zero to have the calling thread run the block. Passing a burdenThread of -1 makes the new resource have the same burden thread as the original.

ObjDuplicateResource() returns the handle of the newly created block, which will be unlocked and may or may not be resident in memory.

Include: object.h

See Also: ObjFreeDuplicate(), MSG_META_BLOCK_FREE, ObjLockObjBlock().

ObjEnableDetach()

void	ObjEnableDetach(
        optr	obj);		/* object calling this routine */

This routine acts as an object's handler for MSG_META_ACK . This handler decrements the acknowledgment count (incremented with ObjIncDetach() ) and, if the count is zero, enables the detach mechanism so the object can be fully detached. Because the detach mechanism is implemented in MetaClass , it is highly unlikely you will ever call this routine.

The lone parameter of this routine is the optr of the calling object (or, in the case of MSG_META_ACK , the object sending acknowledgment).

Warnings: This routine may resize and/or move chunks and object blocks, thereby invalidating all pointers and segment addresses.

Include: metaC.goh

See Also: MSG_META_DETACH, ObjInitDetach(), ObjIncDetach(), MSG_META_ACK.

ObjDoRelocation()

ObjDoUnRelocation()

ObjDuplicateMessage()

ObjDuplicateResource()

ObjEnableDetach()