typedef cmHandle_t cmMmH_t;   // cmMm handle type. 
typedef cmRC_t     cmMmRC_t;  // cmMm result code types.

// cmMm result codes 
enum
{
  kOkMmRC = cmOkRC,
  kObjAllocFailMmRC,
  kTrkAllocFailMmRC,
  kAllocFailMmRC,
  kFreeFailMmRC,
  kMissingRecdMmRC,
  kGuardCorruptMmRC,
  kWriteAfterFreeMmRC,
  kLeakDetectedMmRC,
  kDblFreeDetectedMmRC,
  kParamErrMmRC
};

// All cmMmH_t variables should be initialized with this value prior to calling cmMmInitialize().
extern cmMmH_t cmMmNullHandle;

// Function signature for data allocation routine client provided to cmMmInitialize().
// Return NULL if byteCnt == 0.
typedef void* (*cmAllocMmFunc_t)(void* funcArgPtr, unsigned byteCnt);

// Function signature for data release routine client provided to cmMmInitialize().
// Return true on success and false on failure.  Return true if ptr==NULL.
typedef bool  (*cmFreeMmFunc_t)( void* funcArgPtr, void* ptr);

// Flags for use with cmMmInitialize()
enum
{
  kTrackMmFl      = 0x01,    // Track alloc's and free's for use by cmMmReport().
  kDeferFreeMmFl  = 0x02,    // Defer memory release until cmMmFinalize() (ignored unless kTrackMmFl is set.) Allows checks for 'write after release'.
  kFillUninitMmFl = 0x04,    // Fill uninitialized (non-zeroed) memory with a 0x55 upon allocation
  kFillFreedMmFl  = 0x08     // Fill freed memory with 0x33. This allow checks for wite-after-free.
};

// Create a new cmMm object.
// If *hp was not initalized by an earlier call to cmMmInitialize() then it should 
// be set to cmMmNullHandle prior to calling this function. If *hp is a valid handle
// then it is automatically finalized by an internal call to cmMmFinalize() prior to
// being re-iniitalized.
cmMmRC_t cmMmInitialize( 
cmMmH_t*        hp,            // Pointer to a client provided cmMmH_t handle to recieve the handle of the new object.
cmAllocMmFunc_t allocFunc,     // The memory allocation function equivalent to malloc().
cmFreeMmFunc_t  freeFunc,      // The memory release function equivalent to free().
void*           funcArgPtr,    // An application supplied data value sent with call backs to allocFunc() and freeFunc().
unsigned        guardByteCnt,  // Count of guardBytes to precede and follow each allocated block.
unsigned        alignByteCnt,  // Address alignment to provide for each allocated block.
unsigned        flags,         // Configuration flags (See cmXXXMmFl).
cmRpt_t*        rptPtr         // Pointer to an error reporting object.
);

// Release a cmMm object created by an earlier call to cmMmInitialize(). Upon successful completion *hp is set to cmMmNullHandle.
cmMmRC_t cmMmFinalize( cmMmH_t* hp );

unsigned cmMmGuardByteCount(  cmMmH_t h );  // Return the count of guard bytes this cmMm object is applying.
unsigned cmMmAlignByteCount(  cmMmH_t h );  // Return the byte alignment this cmMm object is applying.
unsigned cmMmInitializeFlags( cmMmH_t h );  // Return the configuration flags this cmMm object was initialized with.

// Return true if 'h' is a valid handle for an existing cmMm object.
bool     cmMmIsValid(  cmMmH_t h );

// flags for use with cmMmAllocate()
enum cmMmAllocFlags_t
{
  kZeroMmFl     = 0x01,  // Initialize new memory area to zero.
  kAlignMmFl    = 0x02,  // Align the returned memory according to the alignByteCnt set in cmMmInitialize().
  kPreserveMmFl = 0x04   // Preserve existing memory contents during reallocation (orgDataPtr!=NULL). 
}; 

// Allocate a block of memory.
// Calling this function results in a call to the function named in allocFunc() in cmMmInitialize(). 
void* cmMmAllocate(     
cmMmH_t     h,                   // Handle for this cmMm object returned from an earlier successful call to cmMmInitialize().
void*       orgDataPtr,          // If this is a re-allocation then this pointer should point to the original allocation otherwise it should be NULL.
unsigned    newEleCnt,           // Count of elmements in this allocation.
unsigned    newEleByteCnt,       // Bytes per element in this allocation. The total memory request is newEleCnt*newEleByteCnt.
enum cmMmAllocFlags_t    flags,  // See cmMmAllocFlags_t.
const char* fileName,            // Name of the C file from which the allocation request is being made. 
const char* funcName,            // Name of the C function from which the allocation request is being made.
unsigned    fileLine             // Line in the C file on which the allocation request is being made.
);

// Free memory pointed to by dataPtr.  
// If dataPtr==NULL then the functon does nothing and returns.
// Calling this function results in a call to the function named in freeFunc() in cmMmInitialize().
// This is the release mode memory free routine. See cmMmFreeDebug() for the debug mode memory release routine. 
//  See \ref debug_mode for more about debug vs. release mode.
cmMmRC_t cmMmFree( cmMmH_t h, void* dataPtr );

// Debug mode version of cmMmFree(). See cmMmFree() for the release mode memory free routine. 
// See debug_mode for more about debug vs. release mode.  
// This routine is functionally identical to the cmMmFree() but takes the calling
// location information for use in tracking the block of memory.
cmMmRC_t cmMmFreeDebug( cmMmH_t h, void* dataPtr, const char* fileName, const char* funcName, unsigned fileLine );

// This function is identical to cmMmFree() but takes the address of the pointer
// to the block of memory to free. Upon successful completion *dataPtrPtr is
// set to NULL. In general this should be the preferred version of the free routine
// because it helps to eliminate problems of reusing deallocated memory blocks.
// Note that although dataPtrPtr must  point to a valid address  *dataPtrPtr may be NULL.
// This routine is generally only used in the release compile mode.
//  See cmMmFreePtrDebug() for the debug mode version.  See \ref debug_mode for more
//  about compile vs. release mode.
cmMmRC_t cmMmFreePtr(  cmMmH_t h, void** dataPtrPtr );

// Debug compile mode version of cmMmFreePtr(). 
// This function is functionally identical to cmMmFreePtr() but accepts information
// on the location of the call to aid in debuging.
cmMmRC_t cmMmFreePtrDebug( cmMmH_t h, void* dataPtr, const char* fileName, const char* funcName, unsigned fileLine );

// Return the size of a memory block returned from cmMmAllocate().
unsigned cmMmByteCount( cmMmH_t h, const void* dataPtr );

// Return the unique id associated with an address returned from cmMmAllocate().
unsigned cmMmDebugId( cmMmH_t h, const void* dataPtr);

// Flags for use with cmMmReport().
enum 
{
  kSuppressSummaryMmFl = 0x01,  // Do not print a memory use summary report.
  kIgnoreNormalMmFl    = 0x02,  // Do not print information for non-leaked,non-corrupt memory blocks. 
  kIgnoreLeaksMmFl     = 0x04   // Do not print information for leaked blocks. 
  
};

// Report on the memory tracking data. 
// Returns kMmOkRC if no errors were found otherwise returns the error of the
// last anomoly reported. 
cmMmRC_t cmMmReport(   cmMmH_t h, unsigned flags );

// Analyze the memory assoc'd with a specific tracking record for corruption.
// Returns: kOkMmRC,kGuardCorruptMmRC,kWriteAfterFreeMmRc, or kMissingRecdMmRC.
// This function is only useful if kTrackMmFl was set in cmMmInitialize().
// Write-after-free errors are only detectable if kDeferFreeMmFl was set in cmMmInitialize().
cmMmRC_t cmMmIsGuardCorrupt( cmMmH_t h, unsigned id );

// Check all tracking records by calling cmMmmIsGuardCorrupt() on each record.
cmMmRC_t cmMmCheckAllGuards( cmMmH_t h );