/*

* Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:   Declaration of the WlanElementLocator class.

*

*/

/*

* %version: 8 %

*/

#ifndef WLAN_ELEMENT_LOCATOR_H

#define WLAN_ELEMENT_LOCATOR_H

/**

 *  Provides methods to locate 802.11 information elements.

 *

 *  @lib wlanumac.lib

 *  @since S60 v3.1

 */

class WlanElementLocator 

    {

public:

    enum TWlanLocateStatus

    {

        EWlanLocateOk,

        EWlanLocateElementNotFound

    };

    /**

     * Constructor. 

     *

     * @since S60 3.1

     * @param aStart   (IN) beginning of the area from where to locate 

     *                 elements

     * @param aLength  (IN) length of the area to search

     */

    WlanElementLocator( const TUint8* aStart, TUint16 aLength );

    /**

    * Return requested information element data.

    * @param aIeId     Id of the requested IE data. See 802dot11.h

    * @param aIeLength (OUT) Length of the IE. Zero if IE not found.

    * @param aIeData   (OUT) Pointer to the beginning of the IE data. 

    *                  NULL if IE not found.

    * @param aValidateLength (IN) If ETrue, the indicated length of the IE 

    *                  data part is checked for validity against the relevant

    *                  specification.

    *                  If EFalse, the validity check is not done.

    * @return          Locate status.

    */

    TWlanLocateStatus InformationElement( 

        TUint8 aIeId, 

        TUint8& aIeLength, 

        const TUint8** aIeData,

        TBool aValidateLength = ETrue );    

    /**

    * Return requested information element data.

    *

    * @since S60 3.2

    * @param aIeId          (IN)  Id of the requested IE data. See 802dot11.h

    * @param aIeOui         (IN)  OUI of the requested IE data. See 802dot11.h

    * @param aIeOuiType     (IN)  OUI Type of the requested IE data. 

    *                             See 802dot11.h

    * @param aIeLength      (OUT) Length of the IE. Zero if IE not found.

    * @param aIeData        (OUT) Pointer to the beginning of the IE data. 

    *                             NULL if IE not found.

    * @return               Locate status.

    */

    TWlanLocateStatus InformationElement( 

        TUint8 aIeId,

        const TIeOui& aIeOui,

        TUint8 aIeOuiType,

        TUint8& aIeLength, 

        const TUint8** aIeData );

    /**

    * Return requested information element data.

    * @param aIeId          (IN)  Id of the requested IE data. See 802dot11.h

    * @param aIeOui         (IN)  OUI of the requested IE data. See 802dot11.h

    * @param aIeOuiType     (IN)  OUI Type of the requested IE data. 

    *                             See 802dot11.h

    * @param aIeOuiSubtype  (IN)  OUI Subtype of the requested IE data. 

    *                             See 802dot11.h

    * @param aIeLength      (OUT) Length of the IE. Zero if IE not found.

    * @param aIeData        (OUT) Pointer to the beginning of the IE data. 

    *                             NULL if IE not found.

    * @return               Locate status.

    */

    TWlanLocateStatus InformationElement( 

        TUint8 aIeId,

        const TIeOui& aIeOui,

        TUint8 aIeOuiType,

        TUint8 aIeOuiSubtype,    

        TUint8& aIeLength, 

        const TUint8** aIeData );

private:

    /**

    * Return the first information element data.

    * @param aIeId     (OUT) Id of the IE. See 802dot11.h.

    * @param aIeLength (OUT) Length of the IE. Zero if IE not found.

    * @param aIeData   (OUT) Pointer to the beginning of the IE data. 

    *                  NULL if IE not found.

    * @return          Locate status.

    */

    TWlanLocateStatus FirstIE( 

        TUint8& aIeId, 

        TUint8& aIeLength, 

        const TUint8** aIeData );

    /**

    * Return next information element data.

    * @param aIeId     (OUT) Id of the IE. See 802dot11.h.

    * @param aIeLength (OUT) Length of the IE. Zero if IE not found.

    * @param aIeData   (OUT) Pointer to the beginning of the IE data. 

    *                  NULL if IE not found.

    * @return          Locate status.

    */

    TWlanLocateStatus NextIE( 

        TUint8& aIeId, 

        TUint8& aIeLength, 

        const TUint8** aIeData );

    /**

    * Return current information element data.

    * @param aIeId     (OUT) Id of the IE. See 802dot11.h.

    * @param aIeLength (OUT) Length of the IE. Zero if IE not found.

    * @param aIeData   (OUT) Pointer to the beginning of the IE data. 

    *                  NULL if IE not found.

    * @return          Locate status.

    */

    TWlanLocateStatus CurrentIE( 

        TUint8& aIeId, 

        TUint8& aIeLength, 

        const TUint8** aIeData ) const;

    /**

    * Validates the indicated length of the IE data part (aIeLength) against

    * the relevant specification. 

    * @param aIeId         (IN) Id of the IE. See 802dot11.h.

    * @param aIeLength     (IN) Length of the IE.

    * @param aIeData       (IN) Pointer to the beginning of the IE data. NULL

    *                      if not relevant for the validity check.

    * @param aIeOuiType    (IN) OUI Type of the IE (if relevant)

    * @param aIeOuiSubtype (IN) OUI Subtype of the IE (if relevant)

    * @return              

    */

    WlanElementLocator::TWlanLocateStatus ValidIE(

        TUint8 aIeId,

        TUint8 aIeLength,

        const TUint8* aIeData = 0,

        TUint8 aIeOuiType = KWmmElemOuiType,

        TUint8 aIeOuiSubtype = KWmmInfoElemOuiSubType ) const;

    // Prohibit copy constructor.

    WlanElementLocator( const WlanElementLocator& );

    // Prohibit assigment operator.

    WlanElementLocator& operator= 

        ( const WlanElementLocator& );

private:   // data

    /** start of the search area */    

    const TUint8* iStart;

    /** length of the search area */        

    TUint16 iLength;

    /** Iterator for going through elements */

    const TUint8* iIterator;

    };

#endif // WLAN_ELEMENT_LOCATOR_H