/**************************************************************************
 *
 * Copyright (c) 2000-2003 Intel Corporation 
 * All rights reserved. 
 * Copyright (c) 2012 France Telecom All rights reserved. 
 *
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions are met: 
 *
 * - Redistributions of source code must retain the above copyright notice, 
 * this list of conditions and the following disclaimer. 
 * - Redistributions in binary form must reproduce the above copyright notice, 
 * this list of conditions and the following disclaimer in the documentation 
 * and/or other materials provided with the distribution. 
 * - Neither name of Intel Corporation nor the names of its contributors 
 * may be used to endorse or promote products derived from this software 
 * without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 **************************************************************************/


#ifndef IXML_MEMBUF_H
#define IXML_MEMBUF_H


/*!
 * \file
 */


#include "ixml.h"


#include <stdlib.h> /* for size_t */


#define MINVAL(a, b) ( (a) < (b) ? (a) : (b) )
#define MAXVAL(a, b) ( (a) > (b) ? (a) : (b) )


#define MEMBUF_DEF_SIZE_INC 20u


/*!
 * \brief The ixml_membuf type.
 */
typedef struct
{
	char *buf;	
	size_t length;
	size_t capacity;
	size_t size_inc;
} ixml_membuf;


/*!
 * \brief ixml_membuf initialization routine.
 */
void ixml_membuf_init(
	/*! [in,out] The memory buffer to initializa. */
	ixml_membuf *m);


/*!
 * \brief ixml_membuf clearing routine.
 *
 * The internal buffer is deleted and ixml_membuf_init() is called in the end
 * to reinitialize the buffer.
 */
void ixml_membuf_destroy(
	/*! [in,out] The memory buffer to clear. */
	ixml_membuf *m);


/*!
 * \brief Copies the contents o a buffer to the designated ixml_membuf.
 *
 * The previous contents of the ixml_membuf are destroyed.
 *
 * \return IXML_SUCCESS if successfull, or the error code returned
 * by ixml_membuf_set_size().
 *
 * \sa ixml_membuf_assign_str().
 */
int ixml_membuf_assign(
	/*! [in,out] The memory buffer on which to operate. */
	ixml_membuf *m,
	/*! [in] The input buffer to copy from. */
	const void *buf, 
	/*! [in] The number of bytes to copy from the input buffer. */
	size_t buf_len);

/*!
 * \brief Copies a \b NULL terminated string to the ixml_buffer.
 *
 * This is a convenience function that internally uses ixml_membuf_assign().
 *
 * \return The return value of ixml_membuf_assign().
 *
 * \sa ixml_membuf_assign().
 */
int ixml_membuf_assign_str(
	/*! [in,out] The memory buffer on which to operate. */
	ixml_membuf *m,
	/*! [in] The input string to copy from. */
	const char *c_str);

/*!
 * \brief Appends one byte to the designated ixml_membuffer.
 *
 * This is a convenience function that internally uses ixml_membuf_insert().
 *
 * \return The return value of ixml_membuf_insert().
 *
 * \sa ixml_membuf_insert()
 */
int ixml_membuf_append(
	/*! [in,out] The memory buffer on which to operate. */
	ixml_membuf *m,
	/*! [in] The pointer to the byte to append. */
	const void *buf);

/*!
 * \brief Appends the contents of a \b NULL terminated string to the designated
 * ixml_membuf.
 *
 * This is a convenience function that internally uses ixml_membuf_insert().
 *
 * \return The return value of ixml_membuf_insert().
 *
 * \sa ixml_membuf_insert().
 */
int ixml_membuf_append_str(
	/*! [in,out] The memory buffer on which to operate. */
	ixml_membuf *m,
	/*! [in] The input string to copy from. */
	const char *c_str);

/*!
 * \brief 
 *
 * \return
 * 	\li 0 if successfull.
 * 	\li IXML_INDEX_SIZE_ERR if the index parameter is out of range.
 * 	\li Or the return code of ixml_membuf_set_size()
 *
 * \sa ixml_membuf_set_size()
 */
int ixml_membuf_insert(
	/*! [in,out] The memory buffer on which to operate. */
	ixml_membuf *m,
	/*! [in] The pointer to the input buffer. */
	const void *buf, 
	/*! [in] The buffer length. */
	size_t buf_len,
	/*! [in] The point of insertion relative to the beggining of the
	 * ixml_membuf internal buffer. */
	size_t index);


#endif /* IXML_MEMBUF_H */