/*

* Copyright (c) 2006 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:   Interface MCatalogsBaseMessage declaration

*

*/

#ifndef M_CATALOGS_BASE_MESSAGE_H

#define M_CATALOGS_BASE_MESSAGE_H

#include "catalogssession.h"

class RFile;

class RFs;

class TSecurityPolicy;

/**

 *  An interface through which a message can be handled.

 *  This class should be implemented by CBase derived class.

 *

 *  This interface is used to pass the message information

 *  to a receiving object. The interface gives access to

 *  message handling functions. These functions include reading 

 *  input data, returning output data to the client and signal the

 *  client about message completion and success. Also a function to 

 *  obtain a message reciver registration interface is included to 

 *  allow registartion of new objects.

 *

 *  @lib ?library

 *  @since S60 ?S60_version *** for example, S60 v3.0

 */

class MCatalogsBaseMessage

    {

public:

    /**

     * Returns the length of the sent input data.

     * NOTICE: The returned length is the length of the sent

     *         descriptor and so the  difference between 8 and 16 bit

     *         variants are taken into account.

     *

     * @since S60 ?S60_version

     * @return the input data length. Error code in error situations.

     */

    virtual TInt InputLength() const = 0;

    /**

     * Reads the sent input data

     *

     * @since S60 ?S60_version

     * @param aInputData a descriptor where the input data is

     *          to be written. The descriptor length can be obtained

     *          enquired by calling first the method InputLength.

     * @return Symbian error code.

     */

    virtual TInt ReadInput( TDes8& aInputData ) const = 0;

    /**

     * Reads the sent input data

     *

     * @since S60 ?S60_version

     * @param aInputData a descriptor where the input data is

     *          to be written. The descriptor length can be obtained

     *          enquired by calling first the method InputLength.

     * @return Symbian error code.

     */

    virtual TInt ReadInput( TDes16& aInputData ) const = 0;

    /**

     * Reads the handle of the object to whome this message is 

     * intended to. This is used primarily when unregistering

     * object from the session.

     *

     * @since S60 ?S60_version

     * @return Handle.

     */   

    virtual TInt Handle() const = 0;

    /**

     * Completes the message with the given status.

     * After this, releases implementor of this interface.

     * NOTICE: Do not use this message after this.

     *

     * @since S60 ?S60_version

     * @param aStatus message completion status

     */

    virtual void CompleteAndRelease( TInt aStatus ) const = 0;

    /**

     * Writes the output data to a client side output

     * buffer and completes the message with the status given.

     * After this, releases implementor of this interface.

     * NOTICE: Do not use this message after this.

     * NOTICE: If leave occurs, this message is NOT released and

     *         NOT completed.

     *

     * @since S60 ?S60_version

     * @param aOutputData a buffer that contains the output data

     * @param aStatus message completion status

     */

    virtual void CompleteAndReleaseL( const TDesC8& aOutputData,

                                      TInt aStatus ) = 0;

    /**

     * Writes the output data to a client side output

     * buffer and completes the message with the status given.

     * After this, releases implementor of this interface.

     * NOTICE: Do not use this message after this.

     * NOTICE: If leave occurs, this message is NOT released and

     *         NOT completed.

     *

     * @since S60 ?S60_version

     * @param aOutputData a buffer that contains the output data

     * @param aStatus message completion status

     */

    virtual void CompleteAndReleaseL( const TDesC16& aOutputData,

                                      TInt aStatus ) = 0;

    /**

     * Writes the output data to a client side output

     * buffer and completes the message with the status given.

     * After this, releases implementor of this interface.

     * NOTICE: Do not use this message after this.

     * NOTICE: If leave occurs, this message is NOT released and

     *         NOT completed.

     *

     * @since S60 ?S60_version

     * @param aOutputData a buffer that contains the output data

     * @param aStatus message completion status

     */

    virtual void CompleteAndReleaseL( TInt aOutputData,

                                      TInt aStatus ) = 0;

    /**

     * Returns the file handle to the client side

     * and completes the message with the status given.

     * After this, releases implementor of this interface.

     * NOTICE: Do not use this message after this.

     * NOTICE: If leave occurs, this message is NOT released and

     *         NOT completed.

     *

     * @since S60 ?S60_version

     * @param aFs File server session used to open the file.

     * @param aFile File handle that is shared with the client

     * @note The file server session must be shared with 

     * RFs::ShareProtected() before the file is opened with it.

     */

    virtual void CompleteAndReleaseL( RFs& aFs, RFile& aFile ) = 0;

    /**

     * Releases this message. This function is only intended for

     * special case usage when session has died and no communication

     * is allowed anymore. At that point, this function can be

     * used to release this message.

     * NOTICE: Do not use this message after this.

     *

     * @since S60 ?S60_version

     * @param aStatus message completion status

     */

    virtual void Release() = 0;

    /**

     * Checks if this message qualify the given security policies.

     *

     * @since S60 ?S60_version

     * @param aPolicy The policy is checked against the policy of this

     * message. If multiple capabilities are specified, all of them must 

     * be present in this message for the security check to succeed 

     * ('AND' relation).

     * @return TBool ETrue if the security check is success. Else EFalse.

     */

    virtual TBool CheckSecurityPolicy( const TSecurityPolicy& aSecurityPolicy ) = 0;

    /**

     * Returns the interface that gives access to registering

     * receiving objects and removing registered receivers

     *

     * @since S60 ?S60_version

     * @return a reference to the registering interface

     */

    virtual MCatalogsSession& Session() const = 0;

    /**

     * Function to inform that if this message is from given

     * session, then the client-side object (sender of this

     * message) has been lost. This means that this message

     * will not write anything to client-side or complete any

     * messages anymore even if CompleteAndRelease or

     * CompleteAndReleaseL are called. (this message is only

     * deleted at that point)

     *

     * If this message is not from the given session, nothing is

     * changed and normal functionality is received when

     * complete-functions are called.

     *

     * @since S60 ?S60_version

     * @param aSession Reference to the session in which the

     *                 message sender has died. This function

     *                 checks whether this message originates from

     *                 the same session or not and acts according

     *                 to it.

     * @return Returns ETrue if this message is from the given

     *         session, otherwise EFalse.

     */

    virtual TBool CounterPartLost(

        const MCatalogsSession& aSession ) = 0;

protected:

    /**

     * Destructor. Usage through this interface is not intended.

     *

     * @since S60 ?S60_version

     */    

    virtual ~MCatalogsBaseMessage() {}

    };

#endif // M_CATALOGS_BASE_MESSAGE_H