#ifndef AEEQOSSESSION_H
#define AEEQOSSESSION_H
/*======================================================
FILE:  AEEQoSSession.h

SERVICES:  BREW QoS Session Interface

GENERAL DESCRIPTION:
	Interface definitions, data structures, etc. for BREW Quality Of Service
   Session Interface

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

#include "AEECLSID_QOSSESSION.bid"
#include "AEEQoSSpec.h"
#include "AEEQoSFlow.h"
#include "AEE.h"
#include "AEEModel.h"

enum {
   AEE_QOS_AVAILABLE_EV,
   AEE_QOS_AVAILABLE_MODIFIED_EV,
   AEE_QOS_UNAVAILABLE_EV,
   AEE_QOS_AVAILABLE_DEACTIVATED_EV
};

typedef int AEEQoSEvent;

enum {
   AEE_QOS_STATUS_ACTIVE,
   AEE_QOS_STATUS_INACTIVE,
   AEE_QOS_STATUS_GOING_ACTIVE,
   AEE_QOS_STATUS_GOING_INACTIVE,
   AEE_QOS_STATUS_NOT_AVAILABLE
};

typedef int AEEQoSStatus;

enum {
   AEE_QOS_INFO_CODE_NOT_SPECIFIED,
   AEE_QOS_INFO_CODE_NOT_SUPPORTED,
   AEE_QOS_INFO_CODE_NOT_AVAILABLE,
   AEE_QOS_INFO_CODE_NOT_GUARANTEED,
   AEE_QOS_INFO_CODE_INVALID_PARAMS,
   AEE_QOS_INFO_CODE_INTERNAL_ERROR,
   AEE_QOS_INFO_CODE_INSUFFICIENT_NET_RESOURCES,
   AEE_QOS_INFO_CODE_INSUFFICIENT_LOCAL_RESOURCES
};

typedef int AEEQoSInfoCode;

/*
   Quality Of Service Session Interface
*/

typedef struct IQoSSession IQoSSession;

AEEINTERFACE(IQoSSession)
{
   INHERIT_IModel(IQoSSession);

   int      (*SelectNetwork)(IQoSSession *po, int nNetwork);
   int      (*Open)(IQoSSession *po, IQoSSpec* piRequestedQoSSpec);
   int      (*Modify)(IQoSSession *po, IQoSSpec* piRequestedQoSSpec);
   int      (*Close)(IQoSSession *po);
   int      (*AddRetryCB)(IQoSSession *po, AEECallback* pcbRetry);
   int      (*GetFlowSpec)(IQoSSession *po, IQoSFlow** ppRxFlowSpec, IQoSFlow** ppTxFlowSpec);
   AEEQoSStatus (*GetStatus)(IQoSSession *po);
   int      (*GoActive)(IQoSSession *po);
   int      (*SetDormancyTimeout)(IQoSSession *po, uint8 ucSecs);
   int      (*GetErrorSpec)(IQoSSession *po, IQoSErrorSpec** ppErrorSpec);
   int      (*ExtFunc)(IQoSSession* po, int nOption, uint32 dwVal);
};

#define IQOSSESSION_AddRef(p)               AEEGETPVTBL(p,IQoSSession)->AddRef((p))
#define IQOSSESSION_Release(p)              AEEGETPVTBL(p,IQoSSession)->Release((p))
#define IQOSSESSION_QueryInterface(p,i,o)   AEEGETPVTBL(p,IQoSSession)->QueryInterface((p),(i),(o))
#define IQOSSESSION_AddListener(p,pl)       AEEGETPVTBL(p,IQoSSession)->AddListener(p,pl)
//#define IQOSSESSION_Notify(p,pe)            AEEGETPVTBL(p,IQoSSession)->Notify(p,pe)
#define IQOSSESSION_SelectNetwork(p,n)      AEEGETPVTBL(p,IQoSSession)->SelectNetwork(p,n)
#define IQOSSESSION_Open(p,s)               AEEGETPVTBL(p,IQoSSession)->Open((p),(s))
#define IQOSSESSION_Modify(p,s)             AEEGETPVTBL(p,IQoSSession)->Modify((p),(s))
#define IQOSSESSION_Close(p)                AEEGETPVTBL(p,IQoSSession)->Close((p))
#define IQOSSESSION_AddRetryCB(p,c)         AEEGETPVTBL(p,IQoSSession)->AddRetryCB((p),(c))
#define IQOSSESSION_GetFlowSpec(p,rf,tf)    AEEGETPVTBL(p,IQoSSession)->GetFlowSpec((p),(rf),(tf))
#define IQOSSESSION_GetStatus(p)            AEEGETPVTBL(p,IQoSSession)->GetStatus((p))
#define IQOSSESSION_GoActive(p)             AEEGETPVTBL(p,IQoSSession)->GoActive((p))
#define IQOSSESSION_SetDormancyTimeout(p,s) AEEGETPVTBL(p,IQoSSession)->SetDormancyTimeout((p),(s))
#define IQOSSESSION_GetErrorSpec(p,s)       AEEGETPVTBL(p,IQoSSession)->GetErrorSpec((p),(s))

/*=====================================================================
  DATA STRUCTURE DOCUMENTATION
======================================================================
AEEQoSEvent

Description:
   This data type is used for QoS events.

Definition:
   typedef int AEEQoSEvent;

Members: 
   AEE_QOS_AVAILABLE_EV:~
      This event is generated in response to IQOSSESSION_Open() operation that
      has returned SUCCESS, to indicate that the requested IQoSSpec is now 
      available and a link has been setup to provide the desired QoS.
      The event is also generated in response to IQOSSESSION_Modify()
      operation that has returned SUCCESS to indicate that QoS has been
      modified as requested.

      Note that if multiple IQoSFlow objects have been specified in the
      requested IQoSSpec, this event will only be reported if the most
      desirable IQoSFlow has been granted otherwise the event 
      AEE_QOS_AVAILABLE_MODIFIED_EV will be reported instead.

   AEE_QOS_AVAILABLE_MODIFIED_EV:~
      This event is generated in response to IQOSSESSION_Open() operation that
      has returned SUCCESS, to indicate that the requested IQoSSpec is now
      available and a link has been setup to provide the desired QoS but the
      available QoS is not the same as the requested QOS.

      The event is also generated in response to IQOSSESSION_Modify() operation
      that has returned SUCCESS to indicate that QoS has been modified and the
      currently available QoS is not the same as the requested QoS.
      If only a single IQoSFlow have been specified in the requested IQoSSpec,
      this event will be generated if the granted QoS is not the same as the
      requested QoS.  In case multiple IQoSFlow objects have been specified in 
      the requested IQoSSpec, this event is generated when the granted QoS is
      not the same as most desirable IQoSFlow.

      This event is also generated when the network forcibly modifies a
      previously granted QoS which, for instance, can happen during a network
      handoff. 

      In response to this event, in either case, it is recommended that the 
      applications should query the currently applied QoS using 
      IQOSSESSION_GetFlowSpec() and take an appropriate action if the granted
      QoS is not sufficient for the proper functioning of the application.
      The application may choose to release the QoS instance and report an 
      error to the user or retry original QoS request using IQOSSESSION_Modify()
      after waiting for some time although it may still not get the requested 
      QoS if the network does not have sufficient resources to fulfill it.
      If the QoS has been modified by the network, further information about
      the reason of QoS modification may be provided by dwParam in the 
      ModelEvent parameter to the listener callback function.
      
   AEE_QOS_UNAVAILABLE_EV:~
      This event indicates that a requested QoS could not be assigned or an
      assigned QoS is not available anymore. The event is generated in response
      to IQOSSESSION_Close(), IQOSSESSION_Open() or IQOSSESSION_Modify()
      operations that have returned SUCCESS.

      The event is also generated when the network has forcibly revoked 
      previously allocated QoS. This could happen due to various reasons like
      network running out of resources, handoff to an older network system 
      which does not support QoS etc. For each occurrence, specific reason due
      to which the QoS is not available may be indicated by dwParam in the 
      ModelEvent parameter to the listener callback function.

      The event implies that the IQoSSession object is not valid anymore and 
      also that the link providing the QoS has been freed up.
      Note that the application is still able to exchange data over the network
      although no specific QoS can be guaranteed.

   AEE_QOS_AVAILABLE_DEACTIVATED_EV:~
      This event indicates that an assigned QoS is deactivated and all the 
      resources are released. The event is generated after using 
      IQOSSESSION_SetDormancyTimeout() to set an inactivity timeout.
      The event is also generated when the network deactivates the QOS, for 
      example, due to inactivity on the link. For each occurrence, specific 
      reason due to which the QoS is deactivated may be indicated by dwParam in
      the ModelEvent parameter to the listener callback function.

      The event implies that the IQoSSession object and the link providing the
      QoS are still valid and configured with QoS parameters but the resource 
      reservations do not exist anymore.

      Application can try to re-activate the IQoSSession object by using 
      IQOSSESSION_GoActive() or by sending data on the QoS link.
 
Comments:
   None.

See Also:
  IQOSSESSION_AddListener()
  IQOSSESSION_Open()
  IQOSSESSION_Modify()
  IQOSSESSION_GoActive()
  IQOSSESSION_SetDormancyTimeout()
  IQoSSpec

======================================================================
  
AEEQoSStatus

Description:
   This data type represents a QoS link status.

Definition:
   typedef int AEEQoSStatus;

Members: 
   AEE_QOS_STATUS_ACTIVE: QoS link is active.
   NET_QOS_STATUS_INACTIVE: QoS link is dormant.
   NET_QOS_STATUS_GOING_ACTIVE: QoS link is going out of dormant.
   NET_QOS_STATUS_GOING_INACTIVE: QoS link is going into dormant.
   NET_QOS_STATUS_NOT_AVAILABLE: couldn't retrieve the status of the QoS link.
 
Comments:
   None.

See Also:
   None.

======================================================================
  
AEEQoSInfoCode

Description:
   This data type is used to deliver additional information regarding the cause
   of a QoS event

Definition:
   typedef int AEEQoSInfoCode;

Members: 
   AEE_QOS_INFO_CODE_NOT_SPECIFIED:
   AEE_QOS_INFO_CODE_NOT_SUPPORTED:
   AEE_QOS_INFO_CODE_NOT_AVAILABLE:
   AEE_QOS_INFO_CODE_NOT_GUARANTEED:
   AEE_QOS_INFO_CODE_INVALID_PARAMS:
   AEE_QOS_INFO_CODE_INTERNAL_ERROR:
   AEE_QOS_INFO_CODE_INSUFFICIENT_NET_RESOURCES:
   AEE_QOS_INFO_CODE_INSUFFICIENT_LOCAL_RESOURCES:
 
Comments:
   None.

See Also:
   None.

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

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

Interface Name: IQoSSession

This interface represents a QoS link (secondary PDP context in UMTS).

The following header file is required:~
AEEQoSSession.h
  
=============================================================================

IQOSSESSION_AddRef()

Description:
   This function is inherited from IBASE_AddRef().

See Also:
   IQOSSESSION_Release()

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

IQOSSESSION_Release()

Description:
   This function is inherited from IBASE_Release().

See Also:
   IQOSSESSION_AddRef()

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

IQOSSESSION_QueryInterface()

Description:
   This function is inherited from IQI_QueryInterface().

See Also:
   None

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

IQOSSESSION_AddListener()

Description:
   This function is inherited from IMODEL_AddListener().

See Also:
   None

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

IQOSSESSION_SelectNetwork()

Description:
   This function selects a specific data network for this QoS Session.

   When an IQoSSession instance is created, no network is selected. If 
   IQOSSESSION_Open() is called before IQOSSESSION_SelectNetwork(), 
   AEE_NETWORK_DEFAULT will be implicitly selected.

   After the QoS Session is opened by calling IQOSSESSION_Open(), the network
   may not be changed until a AEE_QOS_UNAVAILABLE_EV is received for this QoS
   Session.

Prototype:
   int IQOSSESSION_SelectNetwork(IQoSSession *po, int nNetwork);

Parameters:
   po: the interface pointer
   nNetwork: the network for this QoS Session. one of AEE_NETWORK_* constants.

Return Value:
   SUCCESS: the data network was selected.
   AEE_NET_EINVAL: the network is not valid.
   EBADSTATE: the network has already been selected.
   EFAILED: other failure.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_Open()
   INETMGR_SelectNetwork()

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

IQOSSESSION_Open()

Description:
   This function issues a request for a new QoS Session. The request is 
   forwarded to lower layers in order to establish a new QoS link.

   If a network was not yet selected for the IQoSSession instance, 
   AEE_NETWORK_DEFAULT will be implicitly selected.

   Note that a return value of SUCCESS indicates that the request was 
   successfully issued but it doesn't indicate that QoS is already available.
   After IQOSSESSION_Open() returns SUCCESS, the client should listen (see 
   IQOSSESSION_AddListener()) for QoS events and wait for a QoS event which 
   indicates success (AEE_QOS_AVAILABLE_EV or AEE_QOS_AVAILABLE_MODIFIED_EV).
   Receiving one of these events indicates that QoS was granted and the client
   can start sending or receiving data using the granted QoS.

   After IQOSSESSION_Open() returns SUCCESS, IQOSSESSION_Open() shall not be 
   called again.
   However, IQoSSession instance is re-usable, meaning that the client may call
   IQOSSESSION_Open() again after a QoS event which indicates that the QoS was
   released (AEE_QOS_UNAVAILABLE_EV) is received.

   Also note the possibility of an AEE_NET_WOULDBLOCK return value. This occurs
   in cases where a network connection, such as a PPP link, must be established.
   In that case, IQOSSESSION_Open() returns AEE_NET_WOULDBLOCK, and should be
   called again to obtain the final result (error or success).
   
   For notification of when to call IQOSSESSION_Open() again, the client should
   register a callback thru IQOSSESSION_AddRetryCB(). Note that when the 
   client's callback is resumed, it is not guaranteed that a subsequent call 
   to IQOSSESSION_Open() will complete, so the client must be prepared to
   receive AEE_NET_WOULDBLOCK again.

Prototype:
   int IQOSSESSION_Open(IQoSSession *po, IQoSSpec* piRequestedQoSSpec);

Parameters:
   po: the interface pointer
   piRequestedQoSSpec: the desired QoS specification for the new session.

Return Value:
   SUCCESS:~
      the request was successfully issued. This doesn't indicate that QoS is 
      already available.

   AEE_NET_WOULDBLOCK:~
      operation cannot be completed right now; try again later.

   EBADPARM:~ 
      the desired QoS specification is not valid (e.g. piRequestedQoSSpec is
      NULL, piRequestedQoSSpec is empty, etc.)

   AEE_NET_EQOS_SPEC_INVALID_OPT:~
      the desired QoS specification contains invalid options. Use 
      IQOSSESSION_GetErrorSpec() to identify which options were invalid.

   EBADSTATE: QoSSession state is not suitable for this operation.
   ENOMEMORY: out of memory.
   AEE_NET_ENETNONET: network is not available.

   Other error codes are also possible.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_AddRetryCB()
   IQOSSESSION_Close()
   IQOSSESSION_AddListener()
   IQOSSESSION_SelectNetwork()
   IQOSSESSION_GetErrorSpec()

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

IQOSSESSION_Modify()

Description:
   This function issues a request for modifying an existing QoS Session. The 
   request is forwarded to lower layers in order to modify the appropriate 
   QoS link.

Prototype:
   int IQOSSESSION_Modify(IQoSSession *po, IQoSSpec* piRequestedQoSSpec);

Parameters:
   po: the interface pointer
   piRequestedQoSSpec: the new QoS specification to apply to the QoS session.

Return Value:
   SUCCESS:~
      the request was successfully issued. This doesn't indicate that QoS was 
      already modified.

   EBADPARM:~ 
      the desired QoS specification is not valid (e.g. piRequestedQoSSpec is
      NULL, piRequestedQoSSpec is empty, etc.)

   AEE_NET_EQOS_SPEC_INVALID_OPT:~
      the desired QoS specification contains invalid options. Use 
      IQOSSESSION_GetErrorSpec() to identify which options were invalid.

   EBADSTATE: QoSSession state is not suitable for this operation.

   EUNSUPPORTED: operation not supported.

   Other error codes are also possible.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_Open()
   IQOSSESSION_GetErrorSpec()

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

IQOSSESSION_Close()

Description:
   This function issues a request for releasing a QoS Session. The request is 
   forwarded to lower layers in order to release the QoS link.

   Note that a return value of SUCCESS indicates that the request was 
   successfully issued but it doesn't indicate that all QoS resources are 
   released.
   After IQOSSESSION_Close() returns SUCCESS, the client can listen (see 
   IQOSSESSION_AddListener()) for QoS events and wait for a QoS event which 
   indicates that QoS was released (AEE_QOS_UNAVAILABLE_EV). Only this event 
   indicates that all QoS resources are released.

   IQOSSESSION_Close() can be called only after the QoSSession was previously
   opened with a call to IQOSSESSION_Open(). IQOSSESSION_Close() can not be 
   called twice, i.e. after the QoSSession was previously closed with a call to
   IQOSSESSION_Close().

Prototype:
   int IQOSSESSION_Close(IQoSSession *po);

Parameters:
   po: the interface pointer

Return Value:
   SUCCESS: the request was successfully issued. This doesn't indicate that all
            QoS resources are released.
   EBADSTATE: QoSSession state is not suitable for this operation.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_Open()
   IQOSSESSION_AddListener()

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

IQOSSESSION_AddRetryCB()

Description:
   This function should be used by clients in order to be notified when the
   IQOSSESSION_Open() operation should be retried.

   In the case where IQOSSESSION_Open() returns AEE_NET_WOULDBLOCK, 
   IQOSSESSION_Open() should be called again later to obtain the final result
   (error or success).
   For notification of when to call IQOSSESSION_Open() again, the client should
   register a callback thru IQOSSESSION_AddRetryCB(). Note that when the 
   client's callback is resumed, it is not guaranteed that a subsequent call 
   to IQOSSESSION_Open() will complete, so the client must be prepared to
   receive AEE_NET_WOULDBLOCK again.

Prototype:
   int IQOSSESSION_AddRetryCB(IQoSSession *po, AEECallback* pcbRetry);

Parameters:
   po: the interface pointer
   pcbRetry: the client's callback.

Return Value:
   SUCCESS: client's callback was stored successfully.
   EBADPARM: pcbRetry is NULL.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_Open()

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

IQOSSESSION_GetFlowSpec()

Description:
   This function returns the current Rx and Tx Flow Specs.
   
   This function should be called only after QoS was granted. i.e. after
   receiving a QoS event which indicates success (AEE_QOS_AVAILABLE_EV or 
   AEE_QOS_AVAILABLE_MODIFIED_EV).

Prototype:
   int IQOSSESSION_GetFlowSpec(IQoSSession *po, IQoSFlow** ppRxFlowSpec, IQoSFlow** ppTxFlowSpec);

Parameters:
   po: the interface pointer
   ppRxFlowSpec: returns the current Rx Flow Spec.
   ppTxFlowSpec: returns the current Tx Flow Spec.

Return Value:
   SUCCESS: current Rx and Tx Flow Specs were successfully retrieved.
   EBADSTATE: QoSSession state is not suitable for this operation.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQOSSESSION_Open()

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

IQOSSESSION_GetStatus()

Description:
   This function returns the status of the QoS link.

   This function should be called only after QoS was granted. i.e. after
   receiving a QoS event which indicates success (AEE_QOS_AVAILABLE_EV or 
   AEE_QOS_AVAILABLE_MODIFIED_EV).

Prototype:
   AEEQoSStatus IQOSSESSION_GetStatus(IQoSSession *po);

Parameters:
   po: the interface pointer

Return Value:
   The status of the QoS link.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   AEEQoSStatus

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

IQOSSESSION_GoActive()

Description:
   This function is used by clients in order to activate the QoS link (from
   dormant mode).

   This function should be called only after QoS was granted. i.e. after
   receiving a QoS event which indicates success (AEE_QOS_AVAILABLE_EV or 
   AEE_QOS_AVAILABLE_MODIFIED_EV).

Prototype:
   int IQOSSESSION_GoActive(IQoSSession *po);

Parameters:
   po: the interface pointer

Return Value:
   SUCCESS: the request to activate the QoS link was successfully issued to
            lower layers.
   EBADSTATE: QoSSession state is not suitable for this operation.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   None.

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

IQOSSESSION_SetDormancyTimeout()

Description:
   This function sets the IS-707 (cdma2000 1x) packet data dormancy timeout for
   the QoS link.
   If no network traffic on the QoS link occurs during a period of time equals 
   to the dormancy timeout then the mobile should perform mobile initiated 
   dormancy for the QoS link.

   This function should be called only after QoS was granted. i.e. after
   receiving a QoS event which indicates success (AEE_QOS_AVAILABLE_EV or 
   AEE_QOS_AVAILABLE_MODIFIED_EV).

Prototype:
   int IQOSSESSION_SetDormancyTimeout(IQoSSession *po, uint8 ucSecs);

Parameters:
   po: the interface pointer
   ucSecs: dormant timeout in seconds. 0 means no timeout (no mobile initiated 
           dormancy should occur)

Return Value:
   SUCCESS: the timeout was set.
   EUNSUPPORTED: operation not supported.
   AEE_NET_EOPNOTSUPP: network not suitable for this operation (i.e. not a 
                       cdma2000 1x network).
   EFAILED: other error.
   EBADSTATE: QoSSession state is not suitable for this operation.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   None.

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

IQOSSESSION_GetErrorSpec()

Description:
   This function return an IQoSErrorSpec that can be used by clients in order
   to identify which options in a requested QoS Spec were invalid.

   Clients should call this function after a QoS request operation (either 
   IQOSSESSION_Open() or IQOSSESSION_Modify()) returns 
   AEE_NET_EQOS_SPEC_INVALID_OPT.

Prototype:
   int IQOSSESSION_GetErrorSpec(IQoSSession *po, IQoSErrorSpec** ppErrorSpec);

Parameters:
   po: the interface pointer
   ppErrorSpec: returns the current Error Spec.

Return Value:
   SUCCESS: Error Spec was successfully retrieved. *ppErrorSpec is not NULL;
   EFAILED: no Error Spec is currently available.
   EUNSUPPORTED: operation not supported.

Comments:
   None.

Version:
   Introduced BREW Client <3.1>

See Also:
   IQoSErrorSpec.

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

#endif      // AEEQOSSESSION_H
