/**
 * @file    BufferElement.h
 * @brief   文件主要定义了Buffer中的元素类以及元素的类型
 * @author  dev
 * @date    2011-5-25
 */

#ifndef PAI_FRAME_MODULEAPI_BUFFERELEMENT_H
#define PAI_FRAME_MODULEAPI_BUFFERELEMENT_H
#include <string.h>
#include <iostream>
#include "Turtle.h"
namespace pai {
namespace module {
/**
 * @brief 指示数据在缓存之中的复制方式
 * DeepCopy 深度拷贝
 * ShallowCopy 浅拷贝
 */
enum CopyType
{
	DeepCopy,      /**< 深拷贝 */
	ShallowCopy    /**< 深拷贝 */
};

/**
 * @brief 指示缓存中每个元素数据类型
 * <li>TRACE 指示数据是道数据类型
 * <li>GATHER_ENDMARKER 指示数据是道集结尾，遇到这个标志位的element中的data为空，但是模块需要对他进行处理，传递到下一个模块
 * <li>LINE_ENDMARKER 指示数据是线结尾，遇到这个标志位的element中的data为空，但是模块需要对他进行处理，传递到下一个模块，此
 *                标志符号同时也是GATHER_ENDMARKER，一条线数据写完，附上LINE_ENDMARKER标志即可，不需要额外增加一个GATHER_ENDMARKER
 * <li>DATA_ENDMARKER   指示buffer中所有数据已经写完，它同时也兼任了LINE_ENDMARKER和 GATHER_ENDMARKER  ，所有数据写完，加上DATA_ENDMARKER，
 *                  不许要额外增加LINE_ENDMARKER和 GATHER_ENDMARKER
 *
 * @remark 一定不要修改ElementType的enum value,因为单索引机制通过flag=3来判断是DATA_ENDMARKER
 */
enum ElementType
{
    TRACE,               /**< 道数据标记 */
    GATHER_ENDMARKER,    /**< 道集结束标记 */
    LINE_ENDMARKER,      /**< 线结束标记 */
    DATA_ENDMARKER       /**< 数据结束标记 */
};
/**
 * @class CBufferElement
 * @brief buffer中的每个元素，是数据的容器，目前它的data字段只能够存放一个道的数据，或者为NULL
 */
class PAI_MODULE_EXPORT CBufferElement
{

private:
	CBufferElement(const CBufferElement& element);
	CBufferElement& operator=(const CBufferElement& element);
	/**
	 * Factory method must be used to create the BufferElements to avoid 
	 * memory leak and accidental object destruction
	 */
	CBufferElement();

	/**@brief copy constructor
	*
	*/
	CBufferElement(CBufferElement& element, CopyType type);
public:
	/**
	 * @brief 析构函数
	 */
	~CBufferElement();
    /**
     * @brief 创建一个缓存元素对象。
     * @param[in] data   放入元素中的数据，请放入一道数据
     * @param[in] length 数据长度，目前设定为sizeof(CTrace)
     * @return 返回指向创建的一个<code>CBufferElement</code>的指针
     **/
	static CBufferElement* CreateElement(void* data, int length) {
		CBufferElement* element = new CBufferElement();
		element->SetData(data, length);
		return element;
	}
    /**
     * @brief 根据源缓存元素创建一个新的缓存元素，用于缓存元素的拷贝。
     * @param[in] element 放入元素中的数据，请放入一道数据
     * @param[in] type    复制类型，请参考CopyType
     * @return 返回指向创建的一个<code>CBufferElement</code>的指针
     **/
	static CBufferElement* CreateElement(CBufferElement& element, CopyType type) {
	        CBufferElement* newElement = new CBufferElement(element,type);
	        return newElement;
	}
    /**
     * @brief 创建一个buffer结束标志元素，该元素必须放到缓存的最后一个对象，用于标志该<code>CBuffer</code>对象不再有新的数据写入。
     *        对数据读取的方法，遇到这个标志则不再读取
     * @return 返回创建的代表数据结束的<code>CBufferElement</code>指针
     **/
	static CBufferElement* CreateEndElement() {
	    return CreateElement(DATA_ENDMARKER,0,0);
	}
    /**
     * @brief 创建一个道集分割标志元素，该元素必须放到道集与下一个道集之间，是两个道集的分割标志。
     * @return 返回创建的代表道集结束的<code>CBufferElement</code>指针
     **/
	static CBufferElement* CreateGatherEndMarker() {
		return CreateElement(GATHER_ENDMARKER,0,0);
	}
    /**
     * @brief 创建一个线分割标志元素，该元素必须放到一条线数据与下一条线数据之间，是两条线数据的分割标志。
     * @return 返回创建的代表线结束的<code>CBufferElement</code>指针
     **/
    static CBufferElement* CreateLineEndMarker() {
        return CreateElement(LINE_ENDMARKER,0,0);
    }
    /**
     * @brief 创建一个缓存元素对象
     * @param[in] type 希望获得的元素类型，请参考ElementType枚举类型说明
     * @param[in] data 放入元素中的数据，请放入一道数据
     * @param[in] length 数据长度，目前设定为sizeof(CTrace)
     * @return 返回创建的<code>CBufferElement</code>指针
     **/
	static CBufferElement* CreateElement(ElementType type,void* data=NULL, int length=0) {
        CBufferElement* element = CreateElement(data,length);
        element->elementType = type;
        if(type==TRACE)
        {
            element->m_bTraceElement = true;
            element->isEnd = false;
        }
        if(type==DATA_ENDMARKER)
        {
        	element->m_bTraceElement = false;
            element->isEnd = true;
        }
        return element;
    }
    /**
     * @brief 得到一个缓存元素中包含的数据，当元素的<code>Elementype</code>是TRACE时，得到道数据，其他时候应该是空值.
     * @return 缓存元素中包含的数据指针
     **/
	void* GetData(){ return m_pData; }
    /**
     * @brief 对缓存元素中放的数据进行设置。
     * @param[in] data   放入元素中的数据，请放入一道数据
     * @param[in] length 数据长度，目前设定为sizeof(CTrace)
     **/
	void SetData(void* data, int length);
    /**
     * @brief 获得缓存元素中放的数据的长度。
     * @return 数据的长度.对于元素的<code>Elementype</code>是TRACE时，得到sizeof(CTrace)
     **/
	unsigned int GetDataLength() const{ return m_nLength; }
    /**
     * @brief 判断当前元素是否是数据结束标志。
     * @return true是数据结束标志, false不是数据结束标志
     **/
	bool IsEndMarker() const{ return elementType==DATA_ENDMARKER ? true:false; }
    /**
     * @brief 判断当前元素是否是道集分割标志。
     * @return true是道集分割标志, false不是道集分割标志.注意如果该元素是线分割标志或者数据结束标志，本方法也返回true
     **/
	bool IsGatherSplitMarker() { return elementType!=TRACE; }
    /**
     * @brief 判断当前元素是否是线分割标志。
     * @return true是线分割标志, false不是线分割标志，注意如果该元素是线分割标志或者数据结束标志，本方法也返回true
     **/
	bool IsLineSplitMarker() { return elementType==LINE_ENDMARKER||elementType==DATA_ENDMARKER; }

    /**
     * @brief 获取当前元素的类型。
     * @return 返回元素存放的数据类型<code>ElementType</code>
     **/
	ElementType GetElementType(){return elementType;}
    /**
     * @deprecated
     * @brief 获取当前元素是否是道数据。
     * @return true是道数据, false不是道数据
     **/
	bool IsTraceElement(){ return elementType==TRACE ? true:false;}
    /**
     * @deprecated 请使用SetElementType(TRACE)
     * @brief 设置当前元素是否是道数据。
     * @param[in] bTraceElment 是否道数据
     **/
	void SetTraceElment(bool bTraceElment){ this->m_bTraceElement = bTraceElment;}
    /**
     * @deprecated 请暂时不要使用
     * @brief 获取当前元素是否是n道数据。
     * @return 若是则返回true，否则返回false
     **/
    bool IsNewArrayElement(){ return m_bNewArrayElement;}
    /**
     * @deprecated 请暂时不要使用
     * @brief
     **/
    void SetNewArrayElement(bool bNewArrayElement){ this->m_bNewArrayElement = bNewArrayElement;}
	/**
	 * @brief 清空<code>CBufferElement</code>中存放的数据
	 */
	void Reset();

private:
	void SetAsEndMarker();

	ElementType elementType;    /** 元素的数据类型 */
public:
	bool m_bTraceElement;       /**< 元素中存放的数据是否是道数据 */
	bool m_bNewArrayElement;    /**< 元素中存放的数据是否是数组 */
	void* m_pData;              /**< 元素中存放的数据 */
	unsigned int m_nLength;     /**< 元素中数据的长度 */
	bool isEnd;                 /**< 是否是道集、线、数据的结束 */

	friend	class CBuffer;      /**< 友元类 */
};

}
}

#endif