kglist.h

来自「AMLOGIC DPF source code」· C头文件 代码 · 共 736 行 · 第 1/2 页

/** \file 
This file defines the KGallery list classes. These consist of a base class
	and a number of derived classes.
*/

#ifndef KG_LIST_H
#define KG_LIST_H

#include "KGConfig.h"
#include "KGDefs.h"
#include "KGAgTypes.h"

#ifndef AVOS
/** \brief The base class for KGallery list classes. 

	I looked at several 
	alternatives for platform-specific base classes including std:list, the SD RMlist 
	and gsoap. std::list is "heavier" than we need; RMlist does not appear to be used 
	in the SD code (but theoretically is thread-safe); gsoap does not have a list class. 
	Bottom line is I'm rolling my own.

	The base class implements a bidirection linked list, which derived classes specialize
	for storage of specific object types.

	Any list class that may be included in the object stored by another list class (list
	of lists) should 
	overload the assignment operator to InsertEntry() elements from the source list into
	itself. Otherwise, the assignment operator does a simple element by element copy,
	which has resulted in putting automatic variables into persistent lists, followed
	at some future time by a crash. CKGServiceList has a sample implementation.

*/
class CKGList
{
public:
	CKGList(void);
	virtual	~CKGList(void); 

/** \brief returns the number of entries in the list. */
	kg_size	Count();

/** \brief Removes all entries and releases all resources. */
	void	removeAll(void);

protected:
/** the linkage structure */
	class entry_s {
		friend class CKGList;
		entry_s * pPrev;
		entry_s * pNext;
	public:
	protected:
		entry_s(): pPrev((entry_s *)NULL), pNext((entry_s *)NULL){}
	}; 
/** called by derived classes */

/** \brief Called by a derived class to insert the given entry in the list. */
	bool InsertEntry(entry_s *  pWhere, entry_s * pEntry);

/** \brief Removes the entry specified by the given handle from the list and destroys it. */
	KGListHandle RemoveEntry(KGListHandle handle);

/** \brief Destroy entry, which is specific to derived class - i.e. must be overridden. */
	virtual void DestroyEntry(KGListHandle handle) = 0;

/** \brief Reports if the given handles corresponds to an entry in this list. */
	bool CKGList::IsValid(KGListHandle handle, entry_s * * ppEntry = NULL) const;

/** \brief If the given handle is in the list and not at the end,
	returns true and optionally, sets retPtr to the following entry. 
	If the given handle is NULL, returns true unless the list is
	empty and, optionally, sets *ppNext to the first entry in the list.
	*/
	bool CKGList::NextValidEntry(KGListHandle handle, entry_s * * ppNext = NULL) const;

/** \brief if the given handle is in the list and not at the beginning,
	returns true and optionally, sets retPtr to the previous entry.
	If the given handle is NULL, returns true unless the list is
	empty and, optionally, sets *ppPrev to the last entry in the list.
	*/
	bool CKGList::PrevValidEntry(KGListHandle handle, entry_s * * ppPrev = NULL) const;

/** \brief the ends of the list */
	entry_s * m_pHead;
	entry_s * m_pTail;

};

/** Derived list classes */

/** Derived list classes CKGAddressBookGroupMemberList,KGAddressBookGroupMemberSpec */

/** List of Address book group members (Friends & Groups). */


class CKGAddressBookGroupMemberList : public CKGList
{
public:
	CKGAddressBookGroupMemberList(void);

/** \brief Inserts a new element in front of the one specified by "handle".
	Appends to the list if "handle" == NULL. Returns the handle of the
	new item or NULL if an error occurred. */
	KGListHandle InsertEntry (KGListHandle handle, const KGAddressBookGroupMemberSpec & elem);

/** \brief Returns the handle of the first entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle FirstEntry (KGAddressBookGroupMemberSpec & elem) const;

/** \brief Returns the handle of the last entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle LastEntry (KGAddressBookGroupMemberSpec & elem) const;

/** \brief Returns the handle of the list entry that succeeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle NextEntry (KGListHandle handle, KGAddressBookGroupMemberSpec & elem) const;

/** \brief Returns the handle of the list entry that preceeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle PrevEntry (KGListHandle handle, KGAddressBookGroupMemberSpec & elem) const;

/** \brief Remove the entry specified by the given handle and free any associated
	resources. The second form fills in the supplied list element with the data 
	associated with the given handle. Returns the handle of the next entry if it
	exists or the previous entry if it exists or NULL if neither exists or if an 
	error occurred. */
	KGListHandle RemoveEntry (KGListHandle handle);
	KGListHandle RemoveEntry (KGListHandle handle, KGAddressBookGroupMemberSpec & elem);
	
/** \brief Assignment. The given list is copied to this list. Any entries
	already in this list are deleted. */
	CKGAddressBookGroupMemberList  & operator = (const CKGAddressBookGroupMemberList & membersList);


	virtual	~CKGAddressBookGroupMemberList(void); 

protected:
	class addressGroupMemberEntry_s : public entry_s
	{
	public:
		KGAddressBookGroupMemberSpec element;
	}; 

	virtual void DestroyEntry(KGListHandle handle);
};

//////////////////////////////////////////////////////////////////


/** List of strings */


class CKGStringList : public CKGList
{
public:
	CKGStringList(void);

/** \brief Inserts a new element in front of the one specified by "handle".
	Appends to the list if "handle" == NULL. Returns the handle of the
	new item or NULL if an error occurred. */
	KGListHandle InsertEntry (KGListHandle handle, const CKGString & elem);

/** \brief Returns the handle of the first entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle FirstEntry (CKGString & elem) const;

/** \brief Returns the handle of the last entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle LastEntry (CKGString & elem) const;

/** \brief Returns the handle of the list entry that succeeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle NextEntry (KGListHandle handle, CKGString & elem) const;

/** \brief Returns the handle of the list entry that preceeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle PrevEntry (KGListHandle handle, CKGString & elem) const;

/** \brief Remove the entry specified by the given handle and free any associated
	resources. The second form fills in the supplied list element with the data 
	associated with the given handle. Returns the handle of the next entry if it
	exists or the previous entry if it exists or NULL if neither exists or if an 
	error occurred. */
	KGListHandle RemoveEntry (KGListHandle handle);
	KGListHandle RemoveEntry (KGListHandle handle, CKGString & elem);
	
/** \brief Assignment. The given list is copied to this list. Any entries
	already in this list are deleted. */
	CKGStringList  & operator = (const CKGStringList & membersList);


	virtual	~CKGStringList(void); 

protected:
	class stringEntry_s : public entry_s
	{
	public:
		CKGString element;
	}; 

	virtual void DestroyEntry(KGListHandle handle);
};
//////////////////////////////////////////////////////////////////
/** List of services available at a given site */

class CKGServiceList : public CKGList
{
public:
	CKGServiceList(void);

/** \brief Inserts a new element in front of the one specified by "handle".
	Appends to the list if "handle" == NULL. 
	
	Copies the data from the given 'elem' into the new list element. 

	\retval	Returns the handle of the new item or NULL if an error occurred. */
	KGListHandle InsertEntry (KGListHandle handle, const KGServiceSpec & elem);

/** \brief Returns the handle of the first entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle FirstEntry (KGServiceSpec & elem) const;

/** \brief Returns the handle of the last entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle LastEntry (KGServiceSpec & elem) const;

/** \brief Returns the handle of the list entry that succeeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle NextEntry (KGListHandle handle, KGServiceSpec & elem) const;

/** \brief Returns the handle of the list entry that preceeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle PrevEntry (KGListHandle handle, KGServiceSpec & elem) const;

/** \brief Remove the entry specified by the given handle and free any associated
	resources. The second form fills in the supplied list element with the data 
	associated with the given handle. Returns the handle of the next entry if it
	exists or the previous entry if it exists or NULL if neither exists or if an 
	error occurred. */
	KGListHandle RemoveEntry (KGListHandle handle);
	KGListHandle RemoveEntry (KGListHandle handle, KGServiceSpec & elem);
	
/** \brief Assignment. Any entries already in this list are deleted.

	Places each element in the given list into this list using InsertEntry(). 
*/
	CKGServiceList  & operator = (const CKGServiceList & servicesList);


	virtual	~CKGServiceList(void); 

protected:
	class servicesEntry_s : public entry_s
	{
	public:
		KGServiceSpec element;
	}; 

	virtual void DestroyEntry(KGListHandle handle);
};

// **************************************************************************
/** List of countries to which the Gallery ships */

class CKGCountryList : public CKGList
{
public:
	CKGCountryList(void);

/** \brief Inserts a new element in front of the one specified by "handle".
	Appends to the list if "handle" == NULL. 
	
	Copies the data from the given 'elem' into the new list element. 

	\retval	Returns the handle of the new item or NULL if an error occurred. */
	KGListHandle InsertEntry (KGListHandle handle, const KGCountrySpec & elem);

/** \brief Returns the handle of the first entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle FirstEntry (KGCountrySpec & elem) const;

/** \brief Returns the handle of the last entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle LastEntry (KGCountrySpec & elem) const;

/** \brief Returns the handle of the list entry that succeeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle NextEntry (KGListHandle handle, KGCountrySpec & elem) const;

/** \brief Returns the handle of the list entry that preceeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle PrevEntry (KGListHandle handle, KGCountrySpec & elem) const;

/** \brief Remove the entry specified by the given handle and free any associated
	resources. The second form fills in the supplied list element with the data 
	associated with the given handle. Returns the handle of the next entry if it
	exists or the previous entry if it exists or NULL if neither exists or if an 
	error occurred. */
	KGListHandle RemoveEntry (KGListHandle handle);
	KGListHandle RemoveEntry (KGListHandle handle, KGCountrySpec & elem);
	
/** \brief Assignment. Any entries already in this list are deleted.

	Places each element in the given list into this list using InsertEntry(). 
*/
	CKGCountryList  & operator = (const CKGCountryList & countryList);


	virtual	~CKGCountryList(void); 

protected:
	class CountryEntry_s : public entry_s
	{
	public:
		KGCountrySpec element;
	}; 

	virtual void DestroyEntry(KGListHandle handle);
};
// *****************************************************************************

// define class for CKGInventoryList in KGList.cpp
// ()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()
class CKGInventoryList : public CKGList
{
public:
	CKGInventoryList(void);

/** \brief Inserts a new element in front of the one specified by "handle".
	Appends to the list if "handle" == NULL. 
	
	Copies the data from the given 'elem' into the new list element. 

	\retval	Returns the handle of the new item or NULL if an error occurred. */
	KGListHandle InsertEntry (KGListHandle handle, const KGInventoryItemSpec & elem);

/** \brief Returns the handle of the first entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle FirstEntry (KGInventoryItemSpec & elem) const;

/** \brief Returns the handle of the last entry in the list and fills in
	the supplied list element with the data associated with the returned handle. */
	KGListHandle LastEntry (KGInventoryItemSpec & elem) const;

/** \brief Returns the handle of the list entry that succeeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle NextEntry (KGListHandle handle, KGInventoryItemSpec & elem) const;

/** \brief Returns the handle of the list entry that preceeds the given handle and 
	fills in the supplied list element with the data associated with the returned handle. */
	KGListHandle PrevEntry (KGListHandle handle, KGInventoryItemSpec & elem) const;

/** \brief Remove the entry specified by the given handle and free any associated
	resources. The second form fills in the supplied list element with the data 
	associated with the given handle. Returns the handle of the next entry if it
	exists or the previous entry if it exists or NULL if neither exists or if an 
	error occurred. */
	KGListHandle RemoveEntry (KGListHandle handle);
	KGListHandle RemoveEntry (KGListHandle handle, KGInventoryItemSpec & elem);
	
/** \brief Assignment. Any entries already in this list are deleted.

	Places each element in the given list into this list using InsertEntry(). 
*/
	CKGInventoryList  & operator = (const CKGInventoryList & inventoryItemList);


	virtual	~CKGInventoryList(void);