/*

 * MeasurementSrv.h

 *

 * Copyright(c) 1998 - 2010 Texas Instruments. All rights reserved.      

 * All rights reserved.      

 * 

 * This program and the accompanying materials are made available under the 

 * terms of the Eclipse Public License v1.0 or BSD License which accompanies

 * this distribution. The Eclipse Public License is available at

 * http://www.eclipse.org/legal/epl-v10.html and the BSD License is as below.                                   

 *                                                                       

 * Redistribution and use in source and binary forms, with or without    

 * modification, are permitted provided that the following conditions    

 * are met:                                                              

 *                                                                       

 *  * Redistributions of source code must retain the above copyright     

 *    notice, this list of conditions and the following disclaimer.      

 *  * Redistributions in binary form must reproduce the above copyright  

 *    notice, this list of conditions and the following disclaimer in    

 *    the documentation and/or other materials provided with the         

 *    distribution.                                                      

 *  * Neither the name Texas Instruments nor the names of its            

 *    contributors may be used to endorse or promote products derived    

 *    from this software without specific prior written permission.      

 *                                                                       

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS   

 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT     

 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 

 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT  

 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 

 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT      

 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 

 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 

 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT   

 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 

 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 */

/** \file MeasurementSrv.h

 *  \brief This file include private definitions for the Measurement SRV module.

 *  \author Ronen Kalish

 *  \date 08-November-2005

 */

#ifndef __MEASUREMENT_SRV_H__

#define __MEASUREMENT_SRV_H__

#include "TWDriverInternal.h"

#include "MacServices_api.h"

#include "fsm.h"

#include "MeasurementSrvSM.h"

/*

 ***********************************************************************

 *  Constant definitions.

 ***********************************************************************

 */

/* Time in milliseconds to receive a command complete for measure start / stop from the FW */

#define MSR_FW_GUARD_TIME   100 

#define DEF_SAMPLE_INTERVAL             (100)   /* expressed in microsec */

#define NOISE_HISTOGRAM_THRESHOLD           100

/* Get param callback flags  */

#define MSR_SRV_WAITING_CHANNEL_LOAD_RESULTS        0x01 /* channel load results are still pending */

#define MSR_SRV_WAITING_NOISE_HIST_RESULTS          0x02 /* noise histogram results are still pending */

/*

 ***********************************************************************

 *  Enums.

 ***********************************************************************

 */

/*

 ***********************************************************************

 *  Typedefs.

 ***********************************************************************

 */

/*

 ***********************************************************************

 *  Structure definitions.

 ***********************************************************************

 */

/** \struct measurementSRV_t

 * \brief This structure contains the measurement SRV object data

 */

typedef struct

{

    TMediumOccupancy            mediumOccupancyResults; /**< channel load results buffer */

    TNoiseHistogramResults      noiseHistogramResults;  /**< noise histogram results buffer */

    /* module handles */

    TI_HANDLE           hOS;                            /**< OS object handle */

    TI_HANDLE           hReport;                        /**< report object handle */

    TI_HANDLE           hPowerSaveSRV;                  /**< power save SRV object handle */

    TI_HANDLE           hCmdBld;                        /**< Command Builder object handle */

    TI_HANDLE           hEventMbox;                     /**< Event Mbox handle */

    TI_HANDLE           hTimer    ;                     /**< Timer Module handle */

    /* CB functions and objects */                                                        

    TMeasurementSrvCompleteCb measurmentCompleteCBFunc;

                                                        /**< 

                                                         * upper layer (measurement manager) measurement complete 

                                                         * callback function

                                                         */

    TI_HANDLE           measurementCompleteCBObj;       /**< 

                                                         * upper layer (measurement manager) measurement complete

                                                         * callback object

                                                         */

    TCmdResponseCb      commandResponseCBFunc;          /**<

                                                         * upper layer command response CB, used for both start

                                                         * and stop. Passed down to the HAL and called when 

                                                         * the measurement command has been received by the FW

                                                         */

    TI_HANDLE           commandResponseCBObj;           /**<

                                                         * object parameter passed to the commandResposeFunc by 

                                                         * the HAL when it is called 

                                                         */

    TFailureEventCb     failureEventFunc;   /**<

                                            * upper layer Failure Event CB.

                                            * called when the scan command has been Timer Expiry

                                            */

    TI_HANDLE           failureEventObj;        /**<

                                            * object parameter passed to the failureEventFunc

                                            * when it is called 

                                            */

    /* Timers */

    TI_HANDLE           hRequestTimer[ MAX_NUM_OF_MSR_TYPES_IN_PARALLEL ];

                                                        /**< Timers for different measurement types */

    TI_BOOL             bRequestTimerRunning[ MAX_NUM_OF_MSR_TYPES_IN_PARALLEL ];

                                                        /**< Indicates whether each request timer is running */

    TI_HANDLE           hStartStopTimer;                /**< Timer for start / stop commands guard */

    TI_BOOL             bStartStopTimerRunning;         /**< 

                                                         * Indicates whether the start / stop command guard

                                                         * timer is running

                                                         */

    /* Misc stuff */

    TI_BOOL             bInRequest;                     /**<

                                                         * Indicates whether the SM is run within

                                                         * the measurement request context (if so, to avoid

                                                         * re-entrance, the complete function shouldn't

                                                         * be called on failure, but rather an invalid

                                                         * status should be returned)

                                                         */

    TI_STATUS           returnStatus;                   /**< 

                                                         * Holds the return code to the upper layer

                                                         * Used to save errors during SM operation.

                                                         */

    TI_BOOL             bSendNullDataWhenExitPs;        /**< whether to send NULL data frame when exiting

                                                         * driver mode

                                                         */

    /* state machine */

    fsm_stateMachine_t* SM;                            /**< 

                                                         * state machines for different

                                                         * scan types

                                                         */

    measurements_SRVSMStates_e  SMState;                /**< state machine current states */

    /* measurement request */

    TMeasurementRequest     msrRequest;                 /**< measurement request parameters */

    TMeasurementReply       msrReply;                   /**< measurement reply values */

    TI_UINT32               requestRecptionTimeStampMs; /**< The time in which the request was received. */

    TI_UINT32               timeToRequestExpiryMs;      /**<

                                                         * The duration (in ms) from request receiption

                                                         * until it should actually start. Request is

                                                         * discarded if a longer period is required

                                                         */

    TI_UINT8                pendingParamCBs;            /**<

                                                         * a bitmap indicating which get_param CBs are

                                                         * currently pending (noise histogram and/or

                                                         * channel load).

                                                         */

} measurementSRV_t;

/*

 ***********************************************************************

 *  External data definitions.

 ***********************************************************************

 */

/*

 ***********************************************************************

 *  External functions definitions

 ***********************************************************************

 */

/**

 * \author Ronen Kalish\n

 * \date 08-November-2005\n

 * \brief Creates the measurement SRV object

 *

 * Function Scope \e Public.\n

 * \param hOS - handle to the OS object.\n

 * \return a handle to the measurement SRV object, NULL if an error occurred.\n

 */

TI_HANDLE MacServices_measurementSRV_create( TI_HANDLE hOS );

/**

 * \author Ronen Kalish\n

 * \date 08-November-2005\n

 * \brief Initializes the measurement SRV object

 *

 * Function Scope \e Public.\n

 * \param hMeasurementSRV - handle to the measurement SRV object.\n

 * \param hReport - handle to the report object.\n

 * \param hCmdBld - handle to the Command Builder object.\n

 * \param hEventMbox - handle to the Event Mbox object.\n

 * \param hPowerSaveSRV - handle to the power save SRV object.\n

 * \param hTimer - handle to the Timer module object.\n

 */

TI_STATUS MacServices_measurementSRV_init (TI_HANDLE hMeasurementSRV, 

                                           TI_HANDLE hReport, 

                                           TI_HANDLE hCmdBld,

                                           TI_HANDLE hEventMbox,

                                           TI_HANDLE hPowerSaveSRV,

                                           TI_HANDLE hTimer);

/**

 * \author Ronen Kalish\n

 * \date 08-November-2005\n

 * \brief Destroys the measurement SRV object

 *

 * Function Scope \e Public.\n

 * \param hMeasurementSRV - handle to the measurement SRV object.\n

 */

void MacServices_measurementSRV_destroy( TI_HANDLE hMeasurementSRV );

/** 

 * \author Ronen Kalish\n

 * \date 13-November-2005\n

 * \brief Checks whether a beacon measurement is part of current measurement request

 *

 * Function Scope \e Private.\n

 * \param hMeasurementSRV - handle to the measurement SRV object.\n

 * \return TI_TRUE if a beacon measurement is part of current request, TI_FALSE otherwise.\n

 */

TI_BOOL measurementSRVIsBeaconMeasureIncluded( TI_HANDLE hMeasurementSRV );

/** 

 * \author Ronen Kalish\n

 * \date 15-November-2005\n

 * \brief Finds the index for the measurement request with the shortest period 

 * (the one that has now completed).\n

 *

 * Function Scope \e Private.\n

 * \param hMeasurementSRV - handle to the measurement SRV object.\n

 * \return index of the measurement request with the shortest duration.\n

 */

TI_INT32 measurementSRVFindMinDuration( TI_HANDLE hMeasurementSRV );

/** 

 * \author Ronen Kalish\n

 * \date 15-November-2005\n

 * \brief Handles an AP discovery timer expiry, by setting necessary values in the

 * reply struct.\n

 *

 * Function Scope \e Private.\n

 * \param hMeasurementSRV - handle to the measurement SRV object.\n

 * \param requestIndex - index of the beacon request in the request structure.\n

 */

void measurementSRVHandleBeaconMsrComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex );

/** 

 * \author Ronen Kalish\n

 * \date 15-November-2005\n

 * \brief Handles a channel load timer expiry, by requesting channel load 

 * results from the FW.\n

 *

 * Function Scope \e Private.\n

 * \param hMeasurementSRV - handle to the measurement SRV object.\n

 * \param requestIndex - index of the channel load request in the request structure.\n

 */

void measurementSRVHandleChannelLoadComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex );

/** 

 * \author Ronen Kalish\n

 * \date 15-November-2005\n

 * \brief Handles a nois histogram timer expiry, by requesting noise histogram

 * reaults from the FW.\n

 *

 * Function Scope \e Private.\n

 * \param hMeasurementSRV - handle to the measurement SRV object.\n

 * \param requestIndex - indexof the beacon request in the request structure.\n

 */

void measurementSRVHandleNoiseHistogramComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex );

/** 

 * \author Ronen Kalish\n

 * \date 16-November-2005\n

 * \brief Checks whether all measuremtn types had completed and all param CBs had been called.\n

 *

 * Function Scope \e Public.\n

 * \param hMeasurementSRV - handle to the measurement SRV object.\n

 * \param status - the get_param call status.\n

 * \param CB_buf - pointer to the results buffer (already on the measurement SRV object)

 */

TI_BOOL measurementSRVIsMeasurementComplete( TI_HANDLE hMeasurementSRV );

/** 

 * \author Ronen Kalish\n

 * \date 17-November-2005\n

 * \brief Finds a measure type index in the measure request array.\n

 *

 * Function Scope \e Public.\n

 * \param hMeasurementSRV - handle to the measurement SRV object.\n

 * \param type - the measure type to look for.\n

 * \return the type index, -1 if not found.\n

 */

TI_INT32 measurementSRVFindIndexByType( TI_HANDLE hMeasurementSRV, EMeasurementType type );

/****************************************************************************************

 *                        measurementSRVRegisterFailureEventCB                                                  *

 ****************************************************************************************

DESCRIPTION: Registers a failure event callback for scan error notifications.

INPUT:      - hMeasurementSRV   - handle to the Measurement SRV object.     

            - failureEventCB        - the failure event callback function.\n

            - hFailureEventObj  - handle to the object passed to the failure event callback function.

OUTPUT: 

RETURN:    void.

****************************************************************************************/

void measurementSRVRegisterFailureEventCB( TI_HANDLE hMeasurementSRV, 

                                     void * failureEventCB, TI_HANDLE hFailureEventObj );

void measurementSRV_restart( TI_HANDLE hMeasurementSRV);

#endif /* __MEASUREMENT_SRV_H__ */