/*
* Copyright (c) 2002-2006 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 ScanList class
*
*/


#ifndef GENSCANLIST_H
#define GENSCANLIST_H

#include "am_platform_libraries.h"

/** The default maximum size of the scan list is 50kB. */
const u32_t SCAN_LIST_DEFAULT_MAX_SIZE = 51200;
/** The default granularity of the scan list is 8kB. */
const u32_t SCAN_LIST_DEFAULT_GRANULARITY = 8192;
/** The return value for failed Append(). */
const u32_t APPEND_FAILED_NO_MEMORY = 0;
/**
 * The definition for beacon/probe response frame data.
 * Always used as pointer to the frame data, i.e. ScanFrame*.
 */
typedef u8_t ScanFrame;

/**
 * Container class for delivering scan results.
 */
NONSHARABLE_CLASS( ScanList )
    {

    friend class ScanListIterator;

public: // Methods

    // Constructors and destructor

    /**
     * Constructor for an empty container with default parameters.
     */
    ScanList();

    /**
     * Constructor for an empty container.
     *
     * @param max_size The maximum size of the container.
     * @param granularity The granularity of the container.
     * @note After the initial allocation, memory is always allocated
     *       in multiples of the granularity parameter.
     */
    ScanList(
        u32_t max_size,
        u32_t granularity = SCAN_LIST_DEFAULT_GRANULARITY );

    /**
     * Destructor.
     */
    ~ScanList();

    /**
     * Returns the number of access points the instance contains.
     *
     * @return the number of access points the instance contains.
     */
    inline u32_t Count() const;

    /**
     * Appends one beacon/probe response frame to container.
     *
     * @param data_length Length of the frame data to be appended.
     * @param data Pointer to the frame data.
     * @return APPEND_FAILED_NO_MEMORY if there is not enough space,
     *         otherwise the new size of the container.
     * @note If the current size of the container is not enough for the
     *       frame, the container will automatically allocate more memory.
     */
    u32_t Append(
        u32_t data_length,
        const ScanFrame* data );

    /**
     * Returns the current size of the container.
     *
     * @return The current size of the container in bytes.
     */
    inline u32_t Size() const;

    /**
     * Returns the maximum size of the container.
     *
     * @return The maximum size of the container in bytes.
     */
    inline u32_t MaxSize() const;

    /**
     * Sets the maximum size of currently allocated container to the given size.
     *
     * @param max_size Maximum size of the container in bytes.
     * @return The current maximum size if size could not be changed,
     *         the new maximum size otherwise.
     * @note If the current container is smaller than the given size,
     *       more memory is automatically allocated.
     * @note The maximum size is still limited by the size parameter given
     *       when the class was instantiated.
     * @note Making the container smaller than the current size (other than
     *       zero) is not supported at the moment.
     */
    u32_t SetCurrentMaxSize(
        u32_t max_size );

    /**
     * Return a pointer to the currently allocated container.
     *
     * @return NULL if the container is empty, pointer to the
     *         currently allocated container otherwise.
     */
    inline u8_t* Data() const;

    /**
     * Updates the amount of frames and the current size of the container.
     *
     * @param count The amount of beacon/probe response frames stored in the container.
     * @param size The current size of the container (in bytes).
     * @note This method does not do any checking on the parameters and it
     *       is supposed to be used only when the container has been
     *       directly modified through Data().
     */
    inline void Update(
        u32_t count,
        u32_t size );

    /**
     * Clears the container.
     */
    inline void ClearAll();

    /**
     * The alignment of one beacon/probe response frame data must be four bytes.
     * Returns the amount of needed padding for a particular frame length.
     *
     * @param data_length Length of the frame data in bytes.
     * @return Total length in bytes with additional padding.
     */
    inline static u32_t AddPadding(
        u32_t data_length );

    /**
     * Compresses the container so it will be occupy the minimum amount of memory.
     *
     * @return The current size of the container in bytes.
     */
    inline u32_t Compress();

private: // Methods

    /**
     * Prohibit copy constructor.
     */
    ScanList(
        const ScanList& );

    /**
     * Check that the given frame is valid, i.e. it has all mandatory IE fields included.
     *
     * @param data Pointer to the frame data.
     * @return true_t if the frame is valid, false_t otherwise.
     * @note The data being checked has to be stored in the container.
     */
    bool_t CheckData(
        const ScanFrame* data ) const;

    /**
     * Copy data from source buffer to target buffer.
     *
     * @param trg Pointer to the target buffer.
     * @param src Pointer to the source buffer.
     * @param len Length of data to copy in bytes.
     * @return Pointer to end of copied data in the target buffer.
     */
    u8_t* Copy(
        void* target,
        const void* source,
        u32_t data_length );

private: // Data

    /** The container for storing beacon/probe response frames. */
    u8_t* data_m;
    /** The granularity of the container (in bytes). */
    u32_t granularity_m;
    /** The amount of beacon/probe response frames stored in the container. */
    u32_t count_m;
    /** The current size of the container (in bytes). */
    u32_t size_m;
    /** The maximum size of the currently allocated container (in bytes). */
    u32_t current_max_size_m;
    /** The maximum size of the container (in bytes). The container will never exceed this limit. */
    u32_t max_size_m;
    };

#include "genscanlist.inl"

#endif // GENSCANLIST_H