/*
 * zMemory.h
 * 
 * The Zen API 
 * Copyright (C) 2009 by LMI Technologies Inc.
 * 
 * Licensed under The MIT License.
 * Redistributions of files must retain the above copyright notice.
 */
#ifndef LMITECH_ZMEMORY_H_INCLUDED
#define LMITECH_ZMEMORY_H_INCLUDED

#include <zApi.h>
#include <zApiBegin.h>

typedef zHandle zMemory;        // Represents a memory stream.

ZAPI_EXPORT(zStatus) zMemory_Construct(zMemory* memory); //
//
//  Description:
//      Constructs a zMemory object.
//  Arguments:
//      memory - Destination for the constructed object handle. 
//  Remarks: 
//      By default, an auto-sizing, internally-managed buffer is used. 

ZAPI_EXPORT(zStatus) zMemory_Destroy(zMemory memory); //
//
//  Description:
//      Destroys a zMemory object. 
//  Arguments:
//      memory - The zMemory object to be destroyed.

ZAPI_EXPORT(zStatus) zMemory_Attach(zMemory memory, void* buffer, zUIntPtr position, zUIntPtr length, zUIntPtr capacity); //
//
//  Description:
//      Specifies the buffer associated with the memory stream. 
//  Arguments:
//      memory - zMemory object.
//      buffer - Data buffer.
//      position - Current read/write position, relative to start of buffer.
//      length - Length of valid data contained in the buffer, in bytes.
//      capacity - Total size of the buffer, in bytes.

ZAPI_EXPORT(zStatus) zMemory_Allocate(zMemory memory, zUIntPtr initialCapacity); //
//
//  Description:
//      Allocates an auto-sizing, internally-managed buffer for the memory stream. 
//  Arguments:
//      memory - zMemory object.
//      initialCapacity - Initial capacity of the buffer, in bytes.

ZAPI_EXPORT(zStatus) zMemory_Read(zMemory memory, void* buffer, zUIntPtr size); //
//
//  Description:
//      Reads all requested bytes, if available. 
//  Arguments:
//      memory - zMemory object.
//      buffer - Buffer to receive bytes.
//      size - The number of bytes to return.

ZAPI_EXPORT(zStatus) zMemory_Write(zMemory memory, const void* buffer, zUIntPtr size); //
//
//  Description:
//      Writes the specified bytes. 
//  Arguments:
//      memory - zMemory object.
//      buffer - Buffer of bytes to write. 
//      size - The number of bytes to write.

ZAPI_EXPORT(zStatus) zMemory_Seek(zMemory memory, z64s offset, zSeekOrigin origin); //
//
//  Description:
//      Moves the read/write pointer position to the specified location.
//  Arguments:
//      memory - Memory stream object. 
//      offset - Offset by which to adjust the read/write pointer.
//      origin - Origin to which movement is relative (i.e. begin, current, end). 

ZAPI_EXPORT(z64u) zMemory_Length(zMemory memory); //
//
//  Description:
//      Returns the current length of the memory buffer. 
//  Arguments:
//      memory - zMemory object.

ZAPI_EXPORT(z64u) zMemory_Position(zMemory memory); //
//
//  Description:
//      Returns the current position of the read/write pointer, relative to the beginning of the buffer. 
//  Arguments:
//      memory - zMemory object.

ZAPI_EXPORT(zUIntPtr) zMemory_Capacity(zMemory memory); //
//
//  Description:
//      Returns the current capacity of the memory buffer. 
//  Arguments:
//      memory - zMemory object.

ZAPI_EXPORT(zStatus) zMemory_SetLength(zMemory memory, zUIntPtr length); //
//
//  Description:
//      Sets the reported length of the memory buffer. 
//  Arguments:
//      memory - zMemory object.

ZAPI_EXPORT(void*) zMemory_At(zMemory memory, zUIntPtr offset); //
//
//  Description:
//      Returns a pointer to the memory buffer at the specified position. 
//  Arguments:
//      memory - Memory stream object. 
//      offset - Position of interest, in bytes.

#include <zApiEnd.h>

#endif          /* #ifndef LMITECH_ZMEMORY_H_INCLUDED */
