/*
 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).
 * All rights reserved.
 * This component and the accompanying materials are made available
 * under the terms of "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:
 * Class definition for Flexible timer server side sessions. Session
 * instances handle the commmunication with clients and implement a 
 * callback interface for the CFlexTimerEngine to fire timers
 *
 */
/*
 * %version: 1 %
 */
// Protection against nested includes
#ifndef FLEXTIMERSESSION_H
#define FLEXTIMERSESSION_H

// System includes
#include <e32base.h>

// User includes
#include "mflextimerservicecb.h"

// Forward declarations
class MFlexTimerService;

// Class declaration
/**
 *  Flexible timer server side session
 *  CFlexTimerSession implements sessions in CFlexTimerServer. A sessions
 *  parses client messages and adds/cancels timers to CFlexTimerEngine. The
 *  expiration of the timer completes client side message.
 */
class CFlexTimerSession : public CSession2, public MFlexTimerServiceCB
    {

public:

    /**
     * Constructor
     * 
     * @param aFlexTimerService A pointer to engine interface providing
     *                          timeout service
     */
    CFlexTimerSession( MFlexTimerService* aFlexTimerService );

    /**
     * Destructor
     */
    virtual ~CFlexTimerSession();

    /**
     * From: CSession2
     * Message handler servicing client requests. Interprets message type and
     * passes it to correct function for processing.
     * 
     * @param aMessage Message from client
     */
    void ServiceL( const RMessage2& aMessage );

    /**
     * From CSession2
     * Called by a server when it receives a disconnect message for the 
     * session.
     * 
     * @param aMessage The disconnect message
     */
    void Disconnect( const RMessage2 &aMessage );
    
    /**
     * From: MFlexTimerServiceCB
     * Timeout callback function called by timeout engine when a timer
     * associated to this session expires.
     * 
     * @see MFlexTimerServiceCB
     */
    virtual void Timeout() const;

    /**
     * From: MFlexTimerServiceCB
     * Callback function called by CFlexTimerEngine, when a timer associated
     * to this session is aborted. Most probable cause for this is At()-timer
     * aborting due to the system time change
     * 
     * @param aReason Error code to be passed for client (KErrAbort in case 
     *                of system time change)
     *                
     * @see MFlexTimerServiceCB
     */
    virtual void Abort( TInt aReason ) const;

private:

    /**
     * Handles client messages that are issued using At()-function in
     * RFlexTimer
     * 
     * @param aMessage Message from client
     *
     * @see RFlexTimer
     */
    void NewAtTimer( const RMessage2& aMessage );

    /**
     * Handles client messages that are issued using AtUTC()-function in
     * RFlexTimer
     * 
     * @param aMessage Message from client
     *
     * @see RFlexTimer
     */
    void NewAtUtcTimer( const RMessage2& aMessage );

    /**
     * Handles client messages that a issued using After()-function in
     * RFlexTimer
     * 
     * @param aMessage Message from client
     * 
     * @see RFlexTimer
     */
    void NewAfterTimer( const RMessage2& aMessage );

    /**
     * Handles client messages that a issued using AfterTicks()-function in
     * RFlexTimer
     * 
     * @param aMessage Message from client
     * 
     * @see RFlexTimer
     */
    void NewAfterTicksTimer( const RMessage2& aMessage );

    /**
     * Handles timer cancellation initiated by client via RFlexTimer::Cancel
     * 
     * @param aMessage Message from client
     * 
     * @see RFlexTimer
     */
    void CancelTimer( const RMessage2& aMessage );

    /**
     * Configuration message handler, stores configuration parameters for
     * this session
     * 
     * @param aMessage Message from client
     * 
     * @see RFlexTimer
     */
    void ConfigureParameters( const RMessage2& aMessage );

    /**
     * Inline function for calculating the period from current time to
     * the timestamp given in message parameters. This is used for
     * converting the timestamp given in At()- and AtUtc() -functions
     * to an interval given to DoAddTimer function.
     * 
     * @param aRefTime  Reference time used as a basis for interval
     *                  calculation (interval = timestamp - aRefTime)
     * @param aMessage  Message containing timestamp in Int0 and Int1
     *                  parameters (Int0 contains LSW)
     * @param aInterval On return, contains the interval in microseconds
     */
    inline void GetIntervalToMsgTime( const RMessage2& aMessage,
                                      TTime& aRefTime,
                                      TTimeIntervalMicroSeconds& aInterval );
    
    /**
     * Function for adding timer with desired window to engine, called in
     * AtXxx() and AfterXxx() -functions
     * 
     * @param aMessage      Message from client. Stored if adding a timer is
     *                      successful, completed if adding fails
     * @param aInterval     Microseconds until to requested end time
     * @param aRequestAbort ETrue if timer should be cancelled on system
     *                      time change, EFalse otherwise
     */
    void DoAddTimer( const RMessage2& aMessage,
                     TTimeIntervalMicroSeconds& aInterval,
                     TBool aRequestAbort );

private:

    /**
     * Pointer to engine interface through which new timers can be added
     * and cancelled.
     */
    MFlexTimerService* iService;

    /**
     * Timeout window size in microseconds (64-bit). Timeout window is
     * calculated backwards from the absolute timestamp given in AtXxx()
     * and AfterXxx() -functions
     */
    TTimeIntervalMicroSeconds iTimerWinSize;

    /**
     * ETrue if client has not set timeout window, EFalse otherwise
     */
    TBool iUseDefaultWin;

    /**
     * Handle to pending timeout message
     */
    RMessagePtr2 iPendingTimeoutMsg;
    };

#include "flextimersession.inl"

#endif /* FLEXTIMERSESSION_H */