#ifndef AEEQOSFILTER_H
#define AEEQOSFILTER_H
/*===========================================================================

FILE: AEEQoSFilter.h

SERVICES: AEE Quality of Service Filter definitions


DESCRIPTION: Base level definitions, typedefs, etc. for AEE QoS Filter

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

#include "AEECLSID_QOSFILTER.bid"
#include "AEEWebOpts.h"
#include "AEENet.h"


//**********************************************************************
//
// IQOSFILTER Interface
//
//**********************************************************************
typedef            WebOpt AEEQoSFilterOpt;
typedef struct IQoSFilter IQoSFilter;

//
// IP Version   
//
typedef uint32 AEEQOS_IPVersion;

// IP Version values:
#define  AEEQOSFILTER_IP_V4   4
#define  AEEQOSFILTER_IP_V6   6

//
// IPv4 Address, Used for both Source and Destination Addresses.
//
typedef struct
{
   INAddr  addr;
   INAddr  subnet_mask;

} AEEQOSFILTER_IPv4Addr;

//
// IPv4 Type Of Service byte
//
typedef struct
{
   uint8 val;
   uint8 mask;

} AEEQOSFILTER_IPv4TOS;

//
// IP Next Protocol   
//
typedef uint32 AEEQOSFILTER_IPNextProtocol;

// IP Next Protocol values:
#define  AEEQOSFILTER_IP_NEXT_PROTOCOL_TCP   6
#define  AEEQOSFILTER_IP_NEXT_PROTOCOL_UDP   17

//
// TCP/UDP Port Address, Used for both Source and Destination Ports.
//
typedef struct
{
   uint16    port;
   uint16    range;

} AEEQOSFILTER_Port;


//
// Defines to set various Quality of Service Filter Options
//

// Define for selecting a unique WEBOPT_VARIABLE value, based on id.
#define WEBOPT_VARIABLE_UNIQUE(id)                (WEBOPT_VARIABLE + (id << 12))

// pVals are 32-bit quantities, no need to copy
#define AEEQOSFILTEROPT_IP_VERSION                (WEBOPT_32BIT + 0)

#define AEEQOSFILTEROPT_IP_NEXT_PROTOCOL          (WEBOPT_32BIT + 1)

// pVals are pointers to opaque, copyable structures, 
// the low 12 bits of the id specify length of the option, in bytes.
#define AEEQOSFILTEROPT_IPV4_SRC_ADDR             (WEBOPT_VARIABLE_UNIQUE(0) \
                                                   + sizeof(AEEQOSFILTER_IPv4Addr))

#define AEEQOSFILTEROPT_IPV4_DST_ADDR             (WEBOPT_VARIABLE_UNIQUE(1) \
                                                   + sizeof(AEEQOSFILTER_IPv4Addr))

#define AEEQOSFILTEROPT_IPV4_TOS                  (WEBOPT_VARIABLE_UNIQUE(2) \
                                                   + sizeof(AEEQOSFILTER_IPv4TOS))

#define AEEQOSFILTEROPT_SRC_PORT                  (WEBOPT_VARIABLE_UNIQUE(3) \
                                                   + sizeof(AEEQOSFILTER_Port))

#define AEEQOSFILTEROPT_DST_PORT                  (WEBOPT_VARIABLE_UNIQUE(4) \
                                                   + sizeof(AEEQOSFILTER_Port))

#define AEEQOSFILTEROPT_END                       WEBOPT_END
#define AEEQOSFILTEROPT_ANY                       WEBOPT_ANY
#define AEEQOSFILTEROPT_COPYOPTS                  WEBOPT_COPYOPTS


// Define IQoSFilter interface methods
AEEINTERFACE(IQoSFilter)
{
   INHERIT_IWebOpts(IQoSFilter);
   int      (*ExtFunc)(IQoSFilter* po, int nOption, uint32 dwVal);
};

#define IQOSFILTER_AddRef(p)                       AEEGETPVTBL((p),IQoSFilter)->AddRef((p))
#define IQOSFILTER_Release(p)                      AEEGETPVTBL((p),IQoSFilter)->Release((p))
#define IQOSFILTER_QueryInterface(p,clsid,pp)      AEEGETPVTBL((p),IQoSFilter)->QueryInterface((p),(clsid),(pp))
#define IQOSFILTER_AddOpt(p,o)                     AEEGETPVTBL((p),IQoSFilter)->AddOpt((p),(o))
#define IQOSFILTER_RemoveOpt(p,i)                  AEEGETPVTBL((p),IQoSFilter)->RemoveOpt((p),(i),(0))
#define IQOSFILTER_RemoveOptAtIndex(p,n)           AEEGETPVTBL((p),IQoSFilter)->RemoveOpt((p),(WEBOPT_ANY),(n))
#define IQOSFILTER_GetOpt(p,i,o)                   AEEGETPVTBL((p),IQoSFilter)->GetOpt((p),(i),(0),(o))
#define IQOSFILTER_GetOptAtIndex(p,n,o)            AEEGETPVTBL((p),IQoSFilter)->GetOpt((p),(WEBOPT_ANY),(n),(o))

  
/*=====================================================================
  DATA STRUCTURE DOCUMENTATION
=======================================================================
AEEQOS_IPVersion

Description:
  Specifies the IP version

Definition:

enum {
   AEEQOS_IP_V4 = 4,
   AEEQOS_IP_V6 = 6
};
typedef uint32 AEEQOS_IPVersion;

Members:
   AEEQOS_IP_V4: IP version 4
   AEEQOS_IP_V6: IP version 6

Comments:
   Mandatory Option, a QoS filter must contain a single AEEQOS_IPVersion option

Version:
   Introduced BREW Client 3.1

See Also:
   None

=======================================================================
AEEQOSFILTER_IPv4Addr

Description:
  Specifies an IPv4 address (source or destination) filter.

Definition:

typedef struct
{
   INAddr  addr;
   INAddr  subnet_mask;

} AEEQOSFILTER_IPv4Addr;

Members:
   addr: IP v4 address, specified in Network byte order.
   subnet_mask: subnet mask, for selecting a range of IP v4 addresses.
                specified in Network byte order.
                All 1's specify a single address value.

Comments:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   None

=======================================================================
AEEQOSFILTER_IPv4TOS

Description:
   Specifies an IPv4 Type of Service (TOS) byte filter.

Definition:

typedef struct
{
   uint8 val;
   uint8 mask;

} AEEQOSFILTER_IPv4TOS;

Members:
   val: specifies the desired value of TOS field's bits (0 or 1).
   mask: specifies which bits in TOS field should be considered for filtering,
         in essence the TOS field is first OR-ed with "mask" and then compared 
         to "val". ~
         i.e. a mask of 11111111 refers to packets with the EXACT TOS field value

Comments:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   None

=======================================================================
AEEQOSFILTER_IPNextProtocol

Description:
   Specifies the next protocol higher then IP, i.e TCP, UDP.

Definition:

enum {
   AEEQOSFILTER_IP_NEXT_PROTOCOL_TCP = 6,  ~
   AEEQOSFILTER_IP_NEXT_PROTOCOL_UDP = 17  ~
};
typedef uint32 AEEQOSFILTER_IPNextProtocol;

Members:
   AEEQOSFILTER_IP_NEXT_PROTOCOL_TCP: 
   specifies the TCP option, meaning that the filter will apply only to TCP packets.

   AEEQOSFILTER_IP_NEXT_PROTOCOL_UDP:
   specifies the UDP option, meaning that the filter will apply only to UDP packets.

Comments:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   None

=======================================================================
AEEQOSFILTER_Port

Description:
   Specifies a Port (TCP/UDP) filter.

Definition:

typedef struct
{
   uint16    port;
   uint16    range

} AEEQOSFILTER_Port;

Members:
   port: TCP/UDP port value, specified in network byte order.
   range: Specifies a range of port numbers starting from the value specified 
          in port to port+range. ~
          i.e. for a single port value range shall be set to zero ~
          specified in host byte order.

Comments:
   None.

Version:
   Introduced BREW Client 3.1

See Also:
   None

=======================================================================
AEEQoSFilterOpt

Description:
   Holds an id, value pair for AEEQoSFilterOpt.

Definition:
   typedef WebOpt AEEQoSFilterOpt;

Members:
   int32  nId: option id, chosen from one of the QoS Filter options
   void *pVal: option value, depends on nId

Comments:
   AEEQoSFilterOpt structures indicate various parameters of an AEEQoSFilter.
   The structures, when passed to AddOpt, are not themselves copied,
   the contents are copied out.

Version:
   Introduced BREW Client 3.1

See Also:
   None

=======================================================================
AEEQOSFILTEROPT_

The prefix AEEQOSFILTEROPT_ is used for QoS Filter options.
=======================================================================

QoS Filter options

Description:
   QoS Filter options specifies a set of IP packet filter rules. ~
   Packets matching these rules are considered part of the QoS flow.

Definition:
   #define AEEQOSFILTEROPT_IP_VERSION                (WEBOPT_32BIT + 0)

   #define AEEQOSFILTEROPT_IP_NEXT_PROTOCOL          (WEBOPT_32BIT + 1)

   #define AEEQOSFILTEROPT_IPV4_SRC_ADDR             (WEBOPT_VARIABLE_UNIQUE(0) 
                                                      + sizeof(AEEQOSFILTER_IPv4Addr))

   #define AEEQOSFILTEROPT_IPV4_DST_ADDR             (WEBOPT_VARIABLE_UNIQUE(1) 
                                                      + sizeof(AEEQOSFILTER_IPv4Addr))

   #define AEEQOSFILTEROPT_IPV4_TOS                  (WEBOPT_VARIABLE_UNIQUE(2) 
                                                      + sizeof(AEEQOSFILTER_IPv4TOS))

   #define AEEQOSFILTEROPT_SRC_PORT                  (WEBOPT_VARIABLE_UNIQUE(3)
                                                     + sizeof(AEEQOSFILTER_Port))

   #define AEEQOSFILTEROPT_DST_PORT                  (WEBOPT_VARIABLE_UNIQUE(4)
                                                      + sizeof(AEEQOSFILTER_Port))

   #define AEEQOSFILTEROPT_END                       WEBOPT_END

   #define AEEQOSFILTEROPT_ANY                       WEBOPT_ANY

   #define AEEQOSFILTEROPT_COPYOPTS                  WEBOPT_COPYOPTS

Members:
   AEEQOSFILTEROPT_IP_VERSION: 
   IP version, mandatory option (see AEEQOS_IPVersion)

   AEEQOSFILTEROPT_IP_NEXT_PROTOCOL: 
   IP next protocol option (see AEEQOSFILTER_IPNextProtocol)
   must be specified if the dst port and/or src port option is used.

   AEEQOSFILTEROPT_IPV4_SRC_ADDR: 
   IPv4 source address option (see AEEQOSFILTER_IPv4Addr)

   AEEQOSFILTEROPT_IPV4_DST_ADDR: 
   IPv4 destination address option (see AEEQOSFILTER_IPv4Addr)

   AEEQOSFILTEROPT_IPV4_TOS: 
   IPv4 Type of Service option (see AEEQOSFILTER_IPv4TOS)

   AEEQOSFILTEROPT_SRC_PORT: 
   source port option (see AEEQOSFILTER_Port)

   AEEQOSFILTEROPT_DST_PORT: 
   destination port option (see AEEQOSFILTER_Port)

Comments:
   1. Applications must specify a single AEEQOSFILTEROPT_IP_VERSION option for
      each filter. Currently only AEEQOS_IP_V4 is supported. ~
      Other then that a QoS Filter needs to have at least one more option in
      order to be valid.

   2. Applications must specify not more the one of each option.
      AddOpt() will fail for an option that already exists in the IQoSFilter.

   3. IP source address in Tx filters and IP destination address in Rx filters
      should not be specified.

Version:
   Introduced BREW Client 3.1

See Also:
   None

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

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

Interface Name: IQoSFilter

Description:
   IQoSFilter interface encapsulates a Quality of Service IP Filter 
   specification. ~
   The IP filter spec, when applied to stream of IP packets, segregates a
   specific IP flow which is characterized by the filter spec parameters, such
   as ip address and TCP/UDP ports. ~
   An IQoSFilter interface instance is obtained via the ISHELL_CreateInstance()
   mechanism.

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

IQOSFILTER_AddRef()

Description:
   This method increments the reference count of the IQoSFilter Interface object.
   This allows the object to be shared by multiple callers. The object is freed when
   the reference count reaches 0 (zero).

Prototype:
   uint32 IQOSFILTER_AddRef(IQoSFilter * po)

Parameters:

   po [in]: Pointer to the IQoSFilter Interface object

Return Value:
   Incremented reference count for the object

Comments:
   A valid object returns a positive reference count.

Side Effects:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   IQOSFILTER_Release()

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

IQOSFILTER_Release()

Description:
   This method decrements the reference count of an object. The object is freed
   from memory and is no longer valid once the reference count reaches 0 (zero).

Prototype:
   uint32 IQOSFILTER_Release(IQoSFilter * po)

Parameters:
   po [in]: Pointer to the IQoSFilter Interface object

Return Value:
   Decremented reference count for the object. The object has been freed and is no
   longer valid if 0 (zero) is returned.

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   IQOSFILTER_AddRef()

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

Function: IQOSFILTER_QueryInterface()

Description:

   This method retrieves a pointer to an interface conforming to the
   definition of the specified class ID.  This can be used to query for
   extended functionality, like future versions or proprietary extensions.

   Upon a successful query, the interace is returned AddRef'ed.  The caller is
   responsible for calling Release() at some point in the future.  One
   exception is when the pointer returned is not an interface pointer.  In
   that case, the memory will share the lifetime of the object being queried,
   and the returned pointer will not be used to free or release the object.

Prototype:

   int IQOSFILTER_QueryInterface(IQoSFilter *po, AEECLSID id, void **p)

Parameters:
   po [in]: Pointer to IQoSFilter interface
   id [in]: A globally unique id to identify the entity (interface or data) that 
            we are trying to query.
   p [out]: Pointer to the data or interface that we want to retrieve.
            If the interface is not available, this is set to NULL.

Return Value:
   Return SUCCESS on success,

   ECLASSNOTSUPPORT if class ID not supported

Comments:
   On failure, QueryInterface() must set *po to NULL.

Side Effects:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   None

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

Function: IQOSFILTER_AddOpt()

Description:
   Append the list of AEEQoSFilterOpts to the current QoS Filter option set

Prototype:

  int IQOSFILTER_AddOpt(IQoSFilter *po, AEEQoSFilterOpt *apwoz)

Parameters:

  po: the interface pointer

  apwoz: array of AEEQoSFilterOpt structs, terminated by a AEEQoSFilterOpt with
         nId set to AEEQOSFILTEROPT_END

Return Value:
   SUCCESS if the options could be added successfully

   ENOMEMORY if enough memory couldn't be allocated

   EBADPARAM if the option is already a part of the current QoS Filter option set
             or if a mutually exclusive option was already added to the current
             QoS Filter option set.

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   None

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

Function: IQOSFILTER_RemoveOpt()

Description:
   Removes the AEEQoSFilterOpt matching nOptId

Prototype:

   int IQOSFILTER_RemoveOpt(IQoSFilter *po, int32 nOptId)

Parameters:
   po:  the interface pointer
   nOptId: id of the option to remove from the options list

Return Value:
   SUCCESS if the option was removed successfully

   EFAILED if the specified AEEQoSFilterOpt couldn't be found

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   None

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

Function: IQOSFILTER_RemoveOptAtIndex()

Description:
   Removes the AEEQoSFilterOpt at nIndex

Prototype:

   int IQOSFILTER_RemoveOpt(IQoSFilter *po, int32 nIndex)

Parameters:
   po:  the interface pointer
   nOptId: id of the option to remove from the options list

Return Value:
   SUCCESS if the option was removed successfully

   EFAILED if the specified index couldn't be found

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   None

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

Function: IQOSFILTER_GetOpt()

Description:

   Find an AEEQoSFilterOpt, in the list of AEEQoSFilterOpts in po, matching nOptId.
   pwo is filled in with a the matching AEEQoSFilterOpt contents.

Prototype:

   int IQOSFILTER_GetOpt(IQoSFilter *po, int32 nOptId, AEEQoSFilterOpt *pwo)

Parameters:
   po :  the interface pointer
   nOptId: id of the option to find in the options list
   pwo: where to stick the found AEEQoSFilterOpt

Return Value:
   SUCCESS if the option was retrieved successfully

   EFAILED if the specified AEEQoSFilterOpt couldn't be retrieved

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   None

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

Function: IQOSFILTER_GetOptAtIndex()

Description: 
    
   Find the AEEQoSFilterOpt, in the list of AEEQoSFilterOpts in po, at nIndex.
   pwo is filled in with a the matching AEEQoSFilterOpt contents.

Prototype:

   int IQOSFILTER_GetOptWithIndex(IQoSFilter *po, int32 nIndex, AEEQoSFilterOpt *pwo)

Parameters:
   po :  the interface pointer
   nIndex: Option Index.
   pwo: where to stick the found AEEQoSFilterOpt

Return Value:  
   SUCCESS if the option was retrieved successfully

   EFAILED if the specified index couldn't be found
    
Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 3.1

See Also:
   None

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

#endif  // AEEQOSFILTER_H
