/*

* Copyright (c) 2006-2008 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:  Sensor server message wrapper

*

*/

#ifndef SENSRVMESSAGE_H

#define SENSRVMESSAGE_H

#include <e32base.h>

#include "sensrvtypes.h"

class CSensrvSession;

/**

*  Wraps the client message for sensor server internal handling. 

*

*  @since S60 5.0

*/

class CSensrvMessage : public CBase

    {

    public: 

        /**

        * Two-phased constructor for external message

        *

        * @since S60 5.0

        * @return New CSensrvMessage instance

        */

        static CSensrvMessage* NewL();

        /**

        * Destructor.

        * @since S60 5.0

        */

        virtual ~CSensrvMessage();

        /**

        * Initializes the message. Must be done before message is

        * used first time and before use after each complete.

        *

        * @since S60 5.0

        * @param aMessage Client message to wrap

        */

        void Initialize(const RMessage2& aMessage);

        /**

        * Completes the message

        *

        * @since S60 5.0

        * @param aReason Completion reason identifier. Usually error code.

        */

        void Complete(TInt aReason);

        /**

        * Gets the function requested by client.

        *

        * @since S60 5.0

        * @return Function id.

        */

        inline TInt Function() const { return iMessage.Function(); };

        /**

        * Gets session related to this message.

        *

        * @since S60 5.0

        * @return Pointer to related session.

        */

        CSensrvSession* Session();

        /**

        * Writes return data to wrapped message.

        *

        * @since S60 5.0

        * @param aParam Parameter index to write

        * @param aDes Source descriptor for written data.

        * @param aOffset The offset from the start of the client's descriptor. 

        *        If not explicitly specified, the offset defaults to zero.

        * @return KErrArgument aParam is invalid, or if aOffset is negative.

        *         KErrBadDescriptor Parameter is not a descriptor.

        *         KErrOverflow Target descriptor is too small.

        */

        TInt Write(TInt aParam, const TDesC8& aDes, TInt aOffset=0);

        /**

        * Gets message parameter descriptor maximum lenght.

        *

        * @since S60 5.0

        * @param aParam Index of message parameter

        * @return If >= 0, indicates maximum lenght of descriptor parameter.

        *         Otherwise indicates error code: KErrArgument if aParam is invalid,

        *         or KErrBadDescriptor if message parameter specified

        *         aParam is not of the descriptor type.

        */

        TInt GetDesMaxLength(TInt aParam) const;

        /**

        * Gets message parameter descriptor lenght.

        *

        * @since S60 5.0

        * @param aParam Index of message parameter

        * @return If >= 0, indicates maximum lenght of descriptor parameter.

        *         Otherwise indicates error code: KErrArgument if aParam is invalid,

        *         or KErrBadDescriptor if message parameter specified

        *         aParam is not of the descriptor type.

        */

        TInt GetDesLength(TInt aParam) const;

        /**

        * Gets client process SID

        *

        * @since S60 5.0

        * @return Secure Id of the client process.

        */

        TSecureId SecureId() const;

        /**

        * Reads data from wrapped message.

        *

        * @since S60 5.0

        * @param aParam The index value identifying the argument. 

        *         This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.

        * @param aDes The target descriptor into which the client data is to be written. 

        * @return KErrArgument If aParam has a value outside the valid range.

        *         KErrBadDescriptor If the message argument is not an 8-bit descriptor.

        */

        TInt Read( const TInt aParam, TDes8 &aDes ) const;

        /**

        * Reads integer data from wrapped message.

        *

        * @since S60 5.0

        * @param aParam The index value identifying the argument. 

        *         This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.

        * @param aInt The target integer where the value is read.

        */

        void ReadInt( const TInt aParam, TInt &aInt ) const;

        /**

        * Extracts channel id from message.

        *

        * @since S60 5.0

        * @param aChannelId The found channel id is returned here.

        * @return KErrNotSupported If message data doesn't include channel id.

        */

        TInt GetChannelId(TSensrvChannelId& aChannelId) const;

        /**

        * Gets the security info of the client message

        *

        * @since S60 5.0

        * @param aSecurityInfo This object will contain client security info

        */

        void GetSecurityInfo(TSecurityInfo& aSecurityInfo) const;

        /**

        * Returns message handle. Used to determine if message is still valid.

        *

        * @since S60 5.0

        * @return Message handle. Handle will be zero if message is not currently valid.

        */

        inline TInt Handle() const { return iMessage.Handle(); };

        /**

        * Returns the message as read only.

        *

        * @since S60 5.0

        * @return The message.

        */

        inline const RMessage2& GetMessage() const { return iMessage; };

    private:

        /**

        * C++ constructor for external message.

        */

        CSensrvMessage();

    private:    // Data

        /**

        * Wrapped message

        */

        RMessage2 iMessage;

    };

#endif // SENSRVMESSAGE_H