#ifndef AEEQOSSPEC_H
#define AEEQOSSPEC_H
/*======================================================
FILE:  AEEQoSSpec.h

SERVICES:  BREW QoS Spec and QoS Error Spec Interfaces

GENERAL DESCRIPTION:
	Interface definitions, data structures, etc. for BREW Quality Of Service
   Spec and Quality Of Service Error Spec Interfaces

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

#include "AEECLSID_QOSSPEC.bid"
#include "AEE.h"
#include "AEEQoSList.h"

/*
   Quality Of Service Spec Interface
*/

typedef struct IQoSSpec IQoSSpec;

AEEINTERFACE(IQoSSpec)
{
   INHERIT_IQueryInterface(IQoSSpec);

   // set accessors
   int   (*SetRxFlowSpec)(IQoSSpec* po, IQoSList* pIQoSFlowList);
   int   (*SetTxFlowSpec)(IQoSSpec* po, IQoSList* pIQoSFlowList);
   int   (*SetRxFilterSpec)(IQoSSpec* po, IQoSList* pIQoSFilterList);
   int   (*SetTxFilterSpec)(IQoSSpec* po, IQoSList* pIQoSFilterList);
   // get accessors
   int   (*GetRxFlowSpec)(IQoSSpec* po, IQoSList** ppIQoSFlowList);
   int   (*GetTxFlowSpec)(IQoSSpec* po, IQoSList** ppIQoSFlowList);
   int   (*GetRxFilterSpec)(IQoSSpec* po, IQoSList** ppIQoSFilterList);
   int   (*GetTxFilterSpec)(IQoSSpec* po, IQoSList** ppIQoSFilterList);

   int   (*LoadFlowSpecByProfile)(IQoSSpec* po, uint32 profile_rule_id, 
                                  uint32 profile_id);
   int   (*ExtFunc)(IQoSSpec* po, int nOption, uint32 dwVal);
};

#define IQOSSPEC_AddRef(p)             AEEGETPVTBL(p,IQoSSpec)->AddRef((p))
#define IQOSSPEC_Release(p)            AEEGETPVTBL(p,IQoSSpec)->Release((p))
#define IQOSSPEC_QueryInterface(p,i,o) AEEGETPVTBL(p,IQoSSpec)->QueryInterface((p),(i),(o))
#define IQOSSPEC_SetRxFlowSpec(p,i)    AEEGETPVTBL(p,IQoSSpec)->SetRxFlowSpec((p),(i))
#define IQOSSPEC_SetTxFlowSpec(p,i)    AEEGETPVTBL(p,IQoSSpec)->SetTxFlowSpec((p),(i))
#define IQOSSPEC_SetRxFilterSpec(p,i)  AEEGETPVTBL(p,IQoSSpec)->SetRxFilterSpec((p),(i))
#define IQOSSPEC_SetTxFilterSpec(p,i)  AEEGETPVTBL(p,IQoSSpec)->SetTxFilterSpec((p),(i))
#define IQOSSPEC_GetRxFlowSpec(p,i)    AEEGETPVTBL(p,IQoSSpec)->GetRxFlowSpec((p),(i))
#define IQOSSPEC_GetTxFlowSpec(p,i)    AEEGETPVTBL(p,IQoSSpec)->GetTxFlowSpec((p),(i))
#define IQOSSPEC_GetRxFilterSpec(p,i)  AEEGETPVTBL(p,IQoSSpec)->GetRxFilterSpec((p),(i))
#define IQOSSPEC_GetTxFilterSpec(p,i)  AEEGETPVTBL(p,IQoSSpec)->GetTxFilterSpec((p),(i))
#define IQOSSPEC_LoadFlowSpecByProfile(p,pri,pi) AEEGETPVTBL(p,IQoSSpec)->LoadFlowSpecByProfile((p),(pri),(pi))

/*
   Quality Of Service Error Spec Interface
*/

typedef struct IQoSErrorSpec IQoSErrorSpec;

AEEINTERFACE(IQoSErrorSpec)
{
   INHERIT_IQueryInterface(IQoSErrorSpec);

   // get accessors
   int   (*GetErrorRxFlowSpec)(IQoSErrorSpec* po, IQoSList** ppIQoSFlowList);
   int   (*GetErrorTxFlowSpec)(IQoSErrorSpec* po, IQoSList** ppIQoSFlowList);
   int   (*GetErrorRxFilterSpec)(IQoSErrorSpec* po, IQoSList** ppIQoSFilterList);
   int   (*GetErrorTxFilterSpec)(IQoSErrorSpec* po, IQoSList** ppIQoSFilterList);
   int   (*ExtFunc)(IQoSErrorSpec* po, int nOption, uint32 dwVal);
};

#define IQOSERRORSPEC_AddRef(p)                    AEEGETPVTBL(p,IQoSErrorSpec)->AddRef((p))
#define IQOSERRORSPEC_Release(p)                   AEEGETPVTBL(p,IQoSErrorSpec)->Release((p))
#define IQOSERRORSPEC_QueryInterface(p,i,o)        AEEGETPVTBL(p,IQoSErrorSpec)->QueryInterface((p),(i),(o))
#define IQOSERRORSPEC_GetErrorRxFlowSpec(p,i)      AEEGETPVTBL(p,IQoSErrorSpec)->GetErrorRxFlowSpec(((p),(i))
#define IQOSERRORSPEC_GetErrorTxFlowSpec(p,i)      AEEGETPVTBL(p,IQoSErrorSpec)->GetErrorTxFlowSpec((p),(i))
#define IQOSERRORSPEC_GetErrorRxFilterSpec(p,i)    AEEGETPVTBL(p,IQoSErrorSpec)->GetErrorRxFilterSpec((p),(i))
#define IQOSERRORSPEC_GetErrorTxFilterSpec(p,i)    AEEGETPVTBL(p,IQoSErrorSpec)->GetErrorTxFilterSpec((p),(i))

/*=====================================================================
  DATA STRUCTURE DOCUMENTATION
======================================================================= 
  
=======================================================================
  INTERFACES   DOCUMENTATION
=======================================================================

Interface Name: IQoSSpec

This interface represents a complete QoS specification.
QoS specification is composed of four lists of specs:
- List of Rx Flow spec
- List of Tx Flow spec
- List of Rx Filter spec
- List of Tx Filter spec

The two lists of flow spec contains IQoSFlow objects and specify the treatment
required for an IP flow for the Rx direction and for the Tx direction 
respectively.
The order of IQoSFlow objects in these lists is significant. The first object
is the most suitable flow for the client (req_flow) while the last object is
the minimum required flow by the client (min_req_flow). If only one object 
exists in the list, it is handled as the req_flow.

The two lists of filter spec contains IQoSFilter objects and specify the IP 
flow itself for the Rx direction and for the Tx direction respectively.
The order of IQoSFilter objects in these lists is insignificant.

IQoSSpec provides Set and Get accessors to each one of the above four lists. In
addition, IQOSSPEC_LoadFlowSpecByProfile() is used to populate the object with 
Rx and Tx flow specs from a pre-configured profile.

The IQoSSpec is created without any spec lists.
When setting any of the spec lists (thru the Set methods), IQoSSpec doesn't
copy the given list but rather stores a reference to it.
The given IQoSList object replaces the stored one and IQoSSpec takes 
responsibility of it. This means that the stored IQoSList is Release()'d while
the given IQoSList is AddRef()'d.
  
The following header file is required:~
AEEQoSSession.h

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

IQOSSPEC_AddRef()

Description:
   This function is inherited from IBASE_AddRef().

See Also:
   IQOSSPEC_Release()

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

IQOSSPEC_Release()

Description:
   This function is inherited from IBASE_Release().

See Also:
   IQOSSPEC_AddRef()

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

IQOSSPEC_QueryInterface()

Description:
   This function is inherited from IQI_QueryInterface().

See Also:
   None

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

IQOSSPEC_SetRxFlowSpec()

Description:
   This function sets the list of Rx Flow specs that is stored in the IQoSSpec
   object.
   This function doesn't copy the given IQoSList object but rather stores a
   reference to it.
   The given IQoSList object replaces the stored one, if one actually exists.
   The stored IQoSList is Release()'d and the given IQoSList is AddRef()'d.

   No validation is done on the content of the given IQoSList object.
   Validation is only done later when the object is used in operations such
   as IQOSSESSION_Open() and IQOSSESSION_Modify().

Prototype:
   int IQOSSPEC_SetRxFlowSpec(IQoSSpec* po, IQoSList* pIQoSFlowList)

Parameters:
   po: the interface pointer
   pIQoSFlowList: list of IQoSFlow objects to be used as the list of Rx Flow
                  specs. May be NULL.
                  The order of IQoSFlow objects in the list is significant. The
                  first object is the most suitable flow for the client 
                  (req_flow) while the last object is the minimum required flow
                  by the client (min_req_flow). If only one object exists in 
                  the list, it is handled as the req_flow.

Return Value:
   SUCCESS

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSPEC_GetRxFlowSpec()
   IQOSSESSION_Open()
   IQOSSESSION_Modify()

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

IQOSSPEC_SetTxFlowSpec()

Description:
   This function sets the list of Tx Flow specs that is stored in the IQoSSpec
   object.
   This function doesn't copy the given IQoSList object but rather stores a
   reference to it.
   The given IQoSList object replaces the stored one, if one actually exists.
   The stored IQoSList is Release()'d and the given IQoSList is AddRef()'d.

   No validation is done on the content of the given IQoSList object.
   Validation is only done later when the object is used in operations such
   as IQOSSESSION_Open() and IQOSSESSION_Modify().

Prototype:
   int IQOSSPEC_SetTxFlowSpec(IQoSSpec* po, IQoSList* pIQoSFlowList)

Parameters:
   po: the interface pointer
   pIQoSFlowList: list of IQoSFlow objects to be used as the list of Tx Flow
                  specs. May be NULL.
                  The order of IQoSFlow objects in the list is significant. The
                  first object is the most suitable flow for the client 
                  (req_flow) while the last object is the minimum required flow
                  by the client (min_req_flow). If only one object exists in 
                  the list, it is handled as the req_flow.

Return Value:
   SUCCESS

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSPEC_GetTxFlowSpec()
   IQOSSESSION_Open()
   IQOSSESSION_Modify()

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

IQOSSPEC_SetRxFilterSpec()

Description:
   This function sets the list of Rx Filter specs that is stored in the IQoSSpec
   object.
   This function doesn't copy the given IQoSList object but rather stores a
   reference to it.
   The given IQoSList object replaces the stored one, if one actually exists.
   The stored IQoSList is Release()'d and the given IQoSList is AddRef()'d.

   No validation is done on the content of the given IQoSList object.
   Validation is only done later when the object is used in operations such
   as IQOSSESSION_Open() and IQOSSESSION_Modify().

Prototype:
   int IQOSSPEC_SetRxFilterSpec(IQoSSpec* po, IQoSList* pIQoSFilterList)

Parameters:
   po: the interface pointer
   pIQoSFilterList: list of IQoSFilter objects to be used as the list of
                    Rx Filter specs. May be NULL.
                    The order of IQoSFilter objects in the list is 
                    insignificant.

Return Value:
   SUCCESS

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSPEC_GetRxFilterSpec()
   IQOSSESSION_Open()
   IQOSSESSION_Modify()

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

IQOSSPEC_SetTxFilterSpec()

Description:
   This function sets the list of Tx Filter specs that is stored in the IQoSSpec
   object.
   This function doesn't copy the given IQoSList object but rather stores a
   reference to it.
   The given IQoSList object replaces the stored one, if one actually exists.
   The stored IQoSList is Release()'d and the given IQoSList is AddRef()'d.

   No validation is done on the content of the given IQoSList object.
   Validation is only done later when the object is used in operations such
   as IQOSSESSION_Open() and IQOSSESSION_Modify().

Prototype:
   int IQOSSPEC_SetTxFilterSpec(IQoSSpec* po, IQoSList* pIQoSFilterList)

Parameters:
   po: the interface pointer
   pIQoSFilterList: list of IQoSFilter objects to be used as the list of
                    Tx Filter specs. May be NULL.
                    The order of IQoSFilter objects in the list is 
                    insignificant.

Return Value:
   SUCCESS

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSPEC_GetTxFilterSpec()
   IQOSSESSION_Open()
   IQOSSESSION_Modify()

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

IQOSSPEC_GetRxFlowSpec()

Description:
   This function gets the list of Rx Flow specs that is stored in the IQoSSpec
   object.
   This function doesn't copy the stored IQoSList object but rather supplies a
   reference to it.

Prototype:
   int IQOSSPEC_GetRxFlowSpec(IQoSSpec* po, IQoSList** ppIQoSFlowList)

Parameters:
   po: the interface pointer
   ppIQoSFlowList: returns the stored list of Rx Flow specs. If the IQoSSpec
                   object doesn't currently contain a list of Rx Flow specs,
                   *ppIQoSFlowList is set to NULL.

Return Value:
   SUCCESS: The list was returned successfully.
   EBADPARM: ppIQoSFlowList is NULL.

Comments:
   If the client wishes to use the returned IQoSList object beyond the scope of
   this function call, it should AddRef() it.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSPEC_SetRxFlowSpec()

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

IQOSSPEC_GetTxFlowSpec()

Description:
   This function gets the list of Tx Flow specs that is stored in the IQoSSpec
   object.
   This function doesn't copy the stored IQoSList object but rather supplies a
   reference to it.

Prototype:
   int IQOSSPEC_GetTxFlowSpec(IQoSSpec* po, IQoSList** ppIQoSFlowList)

Parameters:
   po: the interface pointer
   ppIQoSFlowList: returns the stored list of Tx Flow specs. If the IQoSSpec
                   object doesn't currently contain a list of Tx Flow specs,
                   *ppIQoSFlowList is set to NULL.

Return Value:
   SUCCESS: The list was returned successfully.
   EBADPARM: ppIQoSFlowList is NULL.

Comments:
   If the client wishes to use the returned IQoSList object beyond the scope of
   this function call, it should AddRef() it.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSPEC_SetTxFlowSpec()

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

IQOSSPEC_GetRxFilterSpec()

Description:
   This function gets the list of Rx Filter specs that is stored in the IQoSSpec
   object.
   This function doesn't copy the stored IQoSList object but rather supplies a
   reference to it.

Prototype:
   int IQOSSPEC_GetRxFilterSpec(IQoSSpec* po, IQoSList** ppIQoSFilterList)

Parameters:
   po: the interface pointer
   ppIQoSFilterList: returns the stored list of Rx Filter specs. If the IQoSSpec
                     object doesn't currently contain a list of Rx Filter specs,
                     *ppIQoSFilterList is set to NULL.

Return Value:
   SUCCESS: The list was returned successfully.
   EBADPARM: ppIQoSFilterList is NULL.

Comments:
   If the client wishes to use the returned IQoSList object beyond the scope of
   this function call, it should AddRef() it.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSPEC_SetRxFilterSpec()

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

IQOSSPEC_GetTxFilterSpec()

Description:
   This function gets the list of Tx Filter specs that is stored in the IQoSSpec
   object.
   This function doesn't copy the stored IQoSList object but rather supplies a
   reference to it.

Prototype:
   int IQOSSPEC_GetTxFilterSpec(IQoSSpec* po, IQoSList** ppIQoSFilterList)

Parameters:
   po: the interface pointer
   ppIQoSFilterList: returns the stored list of Tx Filter specs. If the IQoSSpec
                     object doesn't currently contain a list of Tx Filter specs,
                     *ppIQoSFilterList is set to NULL.

Return Value:
   SUCCESS: The list was returned successfully.
   EBADPARM: ppIQoSFilterList is NULL.

Comments:
   If the client wishes to use the returned IQoSList object beyond the scope of
   this function call, it should AddRef() it.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSPEC_SetTxFilterSpec()

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

IQOSSPEC_LoadFlowSpecByProfile()

Description:
   This function is used to populate the IQoSSpec object with Rx and Tx Flow
   specs from a pre-configured profile. 

Prototype:
   int IQOSSPEC_LoadFlowSpecByProfile)(IQoSSpec* po, uint32 profile_rule_id, 
                                       uint32 profile_id)

Parameters:
   po: the interface pointer
   profile_rule_id: along with profile_id identifies the profile to use.
   profile_id: along with profile_rule_id identifies the profile to use.

Return Value:
   SUCCESS: Rx and Tx Flow specs successfully loaded from the specified profile.
   EBADPARM: the specified profile is not available.
   EUNSUPPORTED: operation not supported.
   
Comments:
   The Rx and Tx Filter specs of the object are untouched.

Version:
   Introduced BREW Client <3.1>

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

=======================================================================
  INTERFACES   DOCUMENTATION
=======================================================================

Interface Name: IQoSErrorSpec

This interface is part of the error reporting mechanism which allows the client to
identify which options in a requested QoS Spec were invalid.
Objects of IQoSErrorSpec can't be created by a client but are rather obtained
from the IQOSSESSION_GetErrorSpec() function.
See IQOSSESSION_GetErrorSpec() for more details.

QoS Error specification is composed of four lists of specs:
- List of Error Rx Flow spec
- List of Error Tx Flow spec
- List of Error Rx Filter spec
- List of Error Tx Filter spec

The two lists of flow spec contains IQoSFlow objects. The two lists of filter 
spec contains IQoSFilter objects.
The order of the objects (IQoSFlow or IQoSFilter) in the lists is significant.
Each object corresponds to its respective counterpart in the requested QoS Spec.

IQoSErrorSpec provides Get accessors to each one of the above four lists.

The following header file is required:~
AEEQoSSession.h

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

IQOSERRORSPEC_AddRef()

Description:
   This function is inherited from IBASE_AddRef().

See Also:
   IQOSERRORSPEC_Release()

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

IQOSERRORSPEC_Release()

Description:
   This function is inherited from IBASE_Release().

See Also:
   IQOSERRORSPEC_AddRef()

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

IQOSERRORSPEC_QueryInterface()

Description:
   This function is inherited from IQI_QueryInterface().

See Also:
   None

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

IQOSERRORSPEC_GetErrorRxFlowSpec()

Description:
   This function gets the list of Error Rx Flow specs that is stored in the
   IQoSErrorSpec object.
   This function doesn't copy the stored IQoSList object but rather supplies a
   reference to it.

Prototype:
   int GetErrorRxFlowSpec(IQoSErrorSpec* po, IQoSList** ppIQoSFlowList)

Parameters:
   po: the interface pointer
   ppIQoSFlowList: returns the stored list of Error Rx Flow specs. If the 
                   IQoSErrorSpec object doesn't currently contain a list of 
                   Error Rx Flow specs, *ppIQoSFlowList is set to NULL.

Return Value:
   SUCCESS: The list was returned successfully.
   EBADPARM: ppIQoSFlowList is NULL.

Comments:
   If the client wishes to use the returned IQoSList object beyond the scope of
   this function call, it should AddRef() it.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_GetErrorSpec()

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

IQOSERRORSPEC_GetErrorTxFlowSpec()

Description:
   This function gets the list of Error Tx Flow specs that is stored in the
   IQoSErrorSpec object.
   This function doesn't copy the stored IQoSList object but rather supplies a
   reference to it.

Prototype:
   int GetErrorTxFlowSpec(IQoSErrorSpec* po, IQoSList** ppIQoSFlowList)

Parameters:
   po: the interface pointer
   ppIQoSFlowList: returns the stored list of Error Tx Flow specs. If the 
                   IQoSErrorSpec object doesn't currently contain a list of 
                   Error Tx Flow specs, *ppIQoSFlowList is set to NULL.

Return Value:
   SUCCESS: The list was returned successfully.
   EBADPARM: ppIQoSFlowList is NULL.

Comments:
   If the client wishes to use the returned IQoSList object beyond the scope of
   this function call, it should AddRef() it.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_GetErrorSpec()

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

IQOSERRORSPEC_GetErrorRxFilterSpec()

Description:
   This function gets the list of Error Rx Filter specs that is stored in the
   IQoSErrorSpec object.
   This function doesn't copy the stored IQoSList object but rather supplies a
   reference to it.

Prototype:
   int GetErrorRxFilterSpec(IQoSErrorSpec* po, IQoSList** ppIQoSFilterList)

Parameters:
   po: the interface pointer
   ppIQoSFilterList: returns the stored list of Error Rx Filter specs. If the 
                     IQoSErrorSpec object doesn't currently contain a list of 
                     Error Rx Filter specs, *ppIQoSFlowList is set to NULL.

Return Value:
   SUCCESS: The list was returned successfully.
   EBADPARM: ppIQoSFilterList is NULL.

Comments:
   If the client wishes to use the returned IQoSList object beyond the scope of
   this function call, it should AddRef() it.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_GetErrorSpec()

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

IQOSERRORSPEC_GetErrorTxFilterSpec()

Description:
   This function gets the list of Error Tx Filter specs that is stored in the
   IQoSErrorSpec object.
   This function doesn't copy the stored IQoSList object but rather supplies a
   reference to it.

Prototype:
   int GetErrorTxFilterSpec(IQoSErrorSpec* po, IQoSList** ppIQoSFilterList)

Parameters:
   po: the interface pointer
   ppIQoSFilterList: returns the stored list of Error Tx Filter specs. If the 
                     IQoSErrorSpec object doesn't currently contain a list of 
                     Error Tx Filter specs, *ppIQoSFlowList is set to NULL.

Return Value:
   SUCCESS: The list was returned successfully.
   EBADPARM: ppIQoSFilterList is NULL.

Comments:
   If the client wishes to use the returned IQoSList object beyond the scope of
   this function call, it should AddRef() it.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_GetErrorSpec()

=======================================================================*/

#endif      // AEEQOSSPEC_H



