#ifndef AEEQOSLIST_H
#define AEEQOSLIST_H
/*======================================================
FILE:  AEEQoSList.h

SERVICES:  BREW QoS List Interface.

GENERAL DESCRIPTION:
   Interface definition of Quality of service List.

        Copyright © 1999-2004 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
=====================================================*/

#include "AEECLSID_QOSLIST.bid"
#include "AEE.h"

/*
   Quality Of Service List Interface
*/

typedef struct IQoSList IQoSList;

AEEINTERFACE(IQoSList)
{
   INHERIT_IQueryInterface(IQoSList);
   int    (*Add)(IQoSList* po, IQueryInterface* pIQueryInterface);
   int    (*Remove)(IQoSList* po, IQueryInterface* pIQueryInterface);
   uint32 (*Size)(IQoSList* po);
   int    (*AddAt)(IQoSList* po, uint32 index, IQueryInterface* pIQueryInterface);
   int    (*RemoveAt)(IQoSList* po, uint32 index);
   int    (*GetAt)(IQoSList* po, uint32 index, IQueryInterface** ppIQueryInterface);
   int    (*Find)(IQoSList* po, IQueryInterface* pIQueryInterface);
   void   (*Clear)(IQoSList* po);
   int    (*ExtFunc)(IQoSList* po, int nOption, uint32 dwVal);
};


#define IQOSLIST_AddRef(p)             AEEGETPVTBL(p,IQoSList)->AddRef((p))
#define IQOSLIST_Release(p)            AEEGETPVTBL(p,IQoSList)->Release((p))
#define IQOSLIST_QueryInterface(p,i,o) AEEGETPVTBL(p,IQoSList)->QueryInterface((p),(i),(o))
#define IQOSLIST_Add(p,i)              AEEGETPVTBL(p,IQoSList)->Add((p),(i))
#define IQOSLIST_Remove(p,i)           AEEGETPVTBL(p,IQoSList)->Remove((p),(i))
#define IQOSLIST_Size(p)               AEEGETPVTBL(p,IQoSList)->Size(p)
#define IQOSLIST_AddAt(p,i,o)          AEEGETPVTBL(p,IQoSList)->AddAt((p),(i),(o))
#define IQOSLIST_RemoveAt(p,i)         AEEGETPVTBL(p,IQoSList)->RemoveAt((p),(i))
#define IQOSLIST_GetAt(p,i,o)          AEEGETPVTBL(p,IQoSList)->GetAt((p),(i),(o))
#define IQOSLIST_Find(p,i)             AEEGETPVTBL(p,IQoSList)->Find((p),(i))
#define IQOSLIST_Clear(p)              AEEGETPVTBL(p,IQoSList)->Clear((p))


/*=======================================================================
  INTERFACES   DOCUMENTATION
=========================================================================
Interface Name: IQoSList

This interface represents a generic single linked list.

The following header file is required:~
AEEQoSList.h

=============================================================================

IQOSLIST_AddRef()
Description:
   This function is inherited from IBASE_AddRef().

See Also:
   IQOSLIST_Release()

=============================================================================

IQOSLIST_Release()

Description:
   This function is inherited from IBASE_Release().

See Also:
   IQOSLIST_AddRef()

==============================================================================

IQOSLIST_QueryInterface()

Description:
   This function is inherited from IQI_QueryInterface().

See Also:
   None.

==============================================================================

IQOSLIST_Add()

Description:
   This function adds new entry at the end of the list.

Prototype:
   int CQoSList_Add(IQoSList *pme, IQueryInterface* pIQueryInterface);

Parameters:
   pme: the interface pointer
   pIQueryInterface: the pointer to the new entry that will be added to the list.

Return Value:
   EBADPARM: the entry pointer is not valid.
   SUCCESS: the entry was added correctly to the list.
   EFAILED: other failure.   

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSLIST_AddAt().
=======================================================================

IQOSLIST_Remove()

Description:
   This function removes the entry pointed by the parameter pIQueryInterface.

Prototype:
   int CQoSList_Remove(IQoSList *pme, IQueryInterface* pIQueryInterface);

Parameters:
   pme: the interface pointer
   pIQueryInterface: the pointer to the entry that will be removed from the list.

Return Value:
   SUCCESS: the entry was removed from the list.
   EBADPARM: the entry wasn't not found in the list.
   EFAILED: other failure.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSLIST_RemoveAt().
=======================================================================

IQOSLIST_Size()

Description:
   This function returns the number of the entries in the list.

Prototype:
   uint32 CQoSList_Size(IQoSList* pme);

Parameters:
   pme: the interface pointer   

Return Value:
   returns the number of entries in the list.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   None.
=======================================================================

IQOSLIST_AddAt()

Description:
   This function adds new entry at the index that was send in "index" parameter.

Prototype:
   int CQoSList_AddAt(IQoSList* pme, uint32 index, IQueryInterface* pIQueryInterface);

Parameters:
   pme: the interface pointer
   index: the index were the entry will be added.
   pIQueryInterface: the entry that will be added to the list.

Return Value:
   EBADPARM: the index is not valid.
   SUCCESS: the entry was added to the list.
   EFAILED: other failure.   

Comments:
   The index is zero based, if the index is greater than or equal to
   the list size then the new entry will be added at the end of the list.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSLIST_Add().  
=======================================================================

IQOSLIST_RemoveAt()

Description:
   This function removes the entry from the list, in index "index"

Prototype:
   int CQoSList_RemoveAt(IQoSList* pme, uint32 index);

Parameters:
   pme: the interface pointer
   index: the index of the entry that will be removed from the list.

Return Value:
   EBADPARM: the index is not valid.
   SUCCESS: the entry in index "index" was removed from the list.
   EFAILED: other failure.   

Comments:
   The index is zero based, if the index is greater than or equal to
   the list size then EBADPARM is returned.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSLIST_Remove()
=======================================================================

IQOSLIST_GetAt()

Description:
   This function returns the entry of the list at the index "index"

Prototype:
   int CQoSList_GetAt(IQoSList* pme, uint32 index, IQueryInterface** ppIQueryInterface);

Parameters:
   pme: the interface pointer
   index: the index of the entry that will be returned.
   ppIQueryInterface: pointer to pointer that will point to the entry in the index "index"

Return Value:
   EMEMPTR: the entry pointer is not valid.
   EBADPARM: the index is not valid.
   SUCCESS: the ppIQueryInterface points at the entry in the index "index".  

Comments:
   The index is zero based, if the index is greater than or equal to
   the list size then EBADPARM is returned.

Version:
   Introduced BREW Client <3.1>

See Also:
   None.
=======================================================================

IQOSLIST_Find()

Description:
   This function returns the index of a entry in the list.

Prototype:
   int CQoSList_Find(IQoSList* pme, IQueryInterface* pIQueryInterface);

Parameters:
   pme: the interface pointer   
   pIQueryInterface: pointer to the entry that the function has to find in the list.

Return Value:
   Index or -1
   
Comments:
   The index that will be returned is zero based, if the function doesn't find
   entry in the list, then -1 will be returned.

Version:
   Introduced BREW Client <3.1>

See Also:
   None.
=======================================================================

IQOSLIST_Clear()

Description:
   This function clears the list, and frees the memory.

Prototype:
   void CQoSList_Clear(IQoSList* pme);

Parameters:
   pme: the interface pointer   

Return Value:
   None.
   
Comments:
   None.
Version:
   Introduced BREW Client <3.1>

See Also:
   None.
=======================================================================*/

#endif      // AEEQOSLIST_H
