MOA Developer's Guide
MOA Interfaces | MOA Methods | MOA Types and Misc API

IMoaHandle

Interface ID: IID_IMoaHandle
Pointer type: PIMoaHandle
Inheritance: IMoaUnknown
Header file: moastdif.h

Description

This standard MOA interface is implemented by every application's callback object for the use of Xtras. It provides methods for use in allocating handle-based, relocatable memory.

This interface is preferable to the IMoaCalloc interface for use in allocating larger chunks of memory, such as those required for sound buffers and bitmap data.

You can access this interface by calling the QueryInterface() method of IMoaCallback interface, provided by the pCallback instance variable of all MOA objects.

Methods

Allocating

Alloc()
ZeroAlloc()

Freeing

Free()

Sizing

GetSize()
Resize()
GetLargestFreeBlock()

Accessing

Lock()
Unlock()

Alloc()

Syntax

Alloc(MoaLong cb)

Parameters

cb
Integer representing size of memory block to allocate

Returns

MoaHandle

Description

Allocates and returns a relocatable memory block of at least cb bytes in size. The memory isn't necessarily zeroed out. If the request cannot be satisfied,NULL is returned.

Free()

Syntax

Free(MoaHandle h)

Parameters

h
Previously allocated handle to be freed

Returns

void

Description

Frees a handle passed in. It is OK to pass NULL, or a locked handle, to this method.

GetLargestFreeBlock()

Syntax

GetLargestFreeBlock()

Parameters

Returns

Size of largest free block

Description

The method GetLargestFreeBlock() returns the amount of free space that could be quickly allocated via the Alloc method (i.e., how large a handle could be allocated without purging, compacting, etc.). A return value of -1 means that this function isn't implemented.

GetSize()

Syntax

GetSize(MoaHandle h)

Parameters

h
Previously allocated handle

Returns

Size of handle h

Description

Returns the logical size of the handle h. The value returned will always be the exact value passed when the handle was allocated or resized using the Alloc(), ZeroAlloc(), or Resize() methods.

Lock()

Syntax

Lock(MoaHandle h)

Parameters

h
Previously allocated handle to lock

Returns

Pointer to start of handle's storage area

Description

Call this method to lock the handle h in memory. This routine never returns NULL; it always return a valid pointer (unless the handle passed in was invalid). The pointer will be aligned to at least a two-byte boundary (but not necessarily to a four-byte boundary). Note that this method doesn't provide lock counting, so nested calls to Lock() have no cumulative effect: the first call of Unlock() will unlock the handle.

Resize()

Syntax

Resize(MoaHandle h, MoaLong newSize)

Parameters

h
Previously allocated handle
newSize
New size to allocated for handle

Returns

TRUE if resized, FALSE if not

Description

Attempts to resize the handle h to be at least newSize bytes long. If the request can be satisfied, this method resizes the handle and returns TRUE. Returns FALSE if the handle h can't be resized or is locked.

Unlock()

Syntax

Unlock(MoaHandle h)

Parameters

h
Previously allocated handle

Returns

void

Description

Unlocks the given handle and invalidates any pointers to it.

ZeroAlloc()

Syntax

ZeroAlloc(MoaLong cb)

Parameters

cb
Integer representing size of memory block to allocate

Returns

Handle to newly allocated memory

Description

Allocates and returns a relocatable memory block of at least cb bytes in size. The memory is zeroed out. If the request cannot be satisfied, NULL is returned.

Copyright © 1995-2007 Adobe Macromedia Software LLC, Inc.