/*

* Copyright (c) 2002 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 for cbs client.

*

*

*/

#ifndef __MCbs_h

#define __MCbs_h

// INCLUDES

#include <CbsCommon.h>

/**

* Interface MCbs is used to change real client server

* connection to some test stub implementation.

*/

class MCbs

    {

    public:

        /**

        * Destructor.

        */

        virtual ~MCbs() {}

        /**

        *   Creates connection to the server.

        *

        *   Note that the method must be called before calling any other 

        *   methods. The method returns an error code and, therefore, 

        *   the caller is responsible of checking that everything went just 

        *   fine.

        *

        *   @return                 Error code.

        */

        virtual TInt Connect() = 0;

        /**

        *   Closes the session to the server.

        */

        virtual void Close() = 0;

        /**

        *   Returns the version of CbsClient.

        *

        *   CbsServer and CbsClient must be of same version.

        *

        *   @return                 Returns the version of CbsClient.

        */

        virtual TVersion Version() const = 0;

        // === Settings-related methods

        /**

        *   Returns the reception status in aStatus, which is ETrue if the reception is

        *   on. Otherwise it is EFalse.

        *

        *   @param  aStatus     The method returns the reception status in this parameter.

        */

        virtual void GetReceptionStatus( TBool& aStatus ) = 0;

        /**

        *   Changes the reception status to aStatus.

        *

        *   @param  aStatus     It contains the new reception status.

        *   @return             Error code.

        */

        virtual TInt SetReceptionStatus( TBool aStatus ) = 0;

        /**

        *   Returns the topic detection status in aStatus, which is ETrue if the detection

        *   is on. Otherwise it is EFalse.

        *

        *   @param  aStatus     The method returns the topic detection status in this parameter.

        */

        virtual void GetTopicDetectionStatus( TBool& aStatus ) = 0;

        /**

        *   Changes the topic detection status to aStatus.

        *

        *   @param  aStatus     It contains the new topic detection status.

        *   @return             Error code.

        */

        virtual TInt SetTopicDetectionStatus( TBool aStatus ) = 0;

        /**

        *   Returns the preferred languages in aLanguages.

        *

        *   @param aLanguages   The method returns the languages in this parameter.

        */

        virtual void GetLanguages( TCbsSettingsLanguages& aLanguages ) = 0;

        /**

        *   Changes the preferred languages to aLanguages.

        *

        *   @param aLanguages   It contains the new preferred languages.

        *   @return             Error code.

        */

        virtual TInt SetLanguages( const TCbsSettingsLanguages& aLanguages ) = 0;

        /**

        *   Requests the server to notify the client whenever any settings will be 

        *   changed.

        *

        *   Note that for each subsession only one this kind of request can be pending. Each

        *   client is responsible of assuring this.

        *

        *   @param  aStatus     It is the variable that the server will modify whenever an event occurs.

        *   @param  aEvent      The server will store the type of occurred event to this variable.

        */

        virtual void NotifySettingsChanged( TRequestStatus& aStatus, TCbsSettingsEvent& aEvent ) = 0;

        /**

        *   Cancels the request to notify the client.

        */

        virtual void NotifySettingsChangedCancel() = 0;

        //  === Topic Collection-related methods

        /**

        *   Resets the iterator. Must be called prior any call to HasNextTopic() 

        *   or NextTopic()!

        */

        virtual void StartCollectionBrowsing() = 0;

        /**

        *   Returns ETrue, if there is a topic not accessed with NextTopic()

        *    

        *   @return     ETrue, if there is a topic. EFalse if the end of the collection

        *               has been reached.

        */

        virtual TBool HasNextCollectionTopic() = 0;                            

        /**

        *   Returns the next topic in the topic collection skipping all topics with 

        *   a topic number matching a topic already listed in the current topic list.

        *   This function will return KErrNotFound if the collection is tried to 

        *   access beyond the end of the list. Otherwise the error code will be 

        *   the same returned by GetTopicInfo().

        *

        *   @param aInfo        The topic information will be stored here.

        *   @return             The error code. KErrNotFound if there are no topics left.

        */

        virtual TInt NextCollectionTopic( TCbsTopicInfo& aInfo ) = 0;

        //  === Topic list-related methods

        /**

        *   Returns the total amount of topics the topic list contains.

        *

        *   @param aCount       It will contain the total amount of topics.

        */

        virtual void GetTopicCount( TInt& aCount ) = 0;

        /**

        *   Returns information about a topic from the topic list.

        *

        *   Return values:

        *   KErrArgument        Topic was not found.

        *    

        *   Rest of return values indicate a file error.

        *

        *   @param aIndex       It is the index to the topic.

        *   @param aTopic       It will contain the topic information.

        *   @return             Error code.

        */

        virtual TInt GetTopic( const TInt aIndex, TCbsTopic& aTopic ) = 0;

        /**

        *   Finds the topic by the given number.

        *

        *   Return values:

        *   KErrNone            Topic returned in parameter aTopic.

        *   KErrNotFound        Topic was not found.

        *

        *   @param aNumber      Number of the topic

        *   @param aTopic       Return: contains the topic information

        *   @return             Error code

        */

        virtual TInt FindTopicByNumber( TCbsTopicNumber aNumber,

            TCbsTopic& aTopic ) = 0;

            /** 

            *   Deletes an existing topic.

            *

            *   @param  aNumber         Number of the topic to be deleted

            *   @return                 Error code

        */

        virtual TInt DeleteTopic( TCbsTopicNumber aNumber ) = 0;

        /**

        *   Delete all topics.

        *

        *   @return             Error code.

        */

        virtual TInt DeleteAllTopics() = 0;

        /**

        *   Adds a new topic. The handle assigned to the topic will be returned

        *   in aTopic.

        *

        *   Return values:

        *   KErrNone            Topic was successfully added.

        *   KErrAlreadyExists   A topic of the same number already exists in DB

        *   KErrArgument        Topic number given was not in a proper range.

        *   KErrDiskFull        Topic not added - FFS out of space

        *

        *   Note that the number of the new topic must be unused.

        *

        *   @param aTopic       Contains the information of the new topic.

        *                       On return, aTopic also contains the topic 

        *                       handle.

        *   @return             Error code.

        */

        virtual TInt AddTopic( TCbsTopic& aTopic ) = 0;

        /**

        *   Changes the name and number of the existing topic.

        *

        *   Note that the changing fails in case there is another topic with

        *   the new topic number. It also fails if the topic is protected.

        *

        *   Return values:

        *   KErrNone            Topic name and number successfully changed.

        *   KErrDiskFull        Topic information not changed - FFS out of space

        *

        *   @param  aOldNumber      Number of the topic to be changed

        *   @param  aNewNumber      Number to be given for the topic

        *   @param  aName           Name to be given for the topic

        *   @return                 Error code

        */  

        virtual TInt ChangeTopicNameAndNumber( 

            TCbsTopicNumber aOldNumber,

            TCbsTopicNumber aNewNumber, 

            const TCbsTopicName& aName ) = 0;

        /**

        *   Changes topic subscription status.

        *

        *   @param  aNumber         Number of the topic

        *   @param  aNewStatus      New subscription status

        *   @return                 Error code

        */

        virtual TInt ChangeTopicSubscriptionStatus( 

            TCbsTopicNumber aNumber, TBool aNewStatus ) = 0;

        /**

        *   Changes topic hotmark status.

        *

        *   @param  aNumber         Number of the topic

        *   @param  aNewStatus      New hotmark status

        *   @return                 Error code

        */

        virtual TInt ChangeTopicHotmarkStatus( TCbsTopicNumber aNumber,

            TBool aNewStatus ) = 0;

        /**

        *   Requests the server to notify the client whenever an event occurs 

        *   that changes the information of the topics. 

        *   

        *   Note that the client may select what kind of events it is 

        *   interested in. Note also that there can be at most one pending

        *   request per instance of the class.

        *

        *   @param aStatus      The variable that the server will modify

        *                       whenever an event occurs.

        *   @param aRequested   Events the client is interested in

        *   @param aEvent       Indicates the variable that will contain the

        *                       type of event that occured.

        *   @param aNumber      Indicates the variable that will contain the

        *                       topic number that was changed in event.

        */

        virtual void NotifyOnTopicListEvent( 

            TRequestStatus& aStatus, 

            const TInt aRequested, 

            TCbsTopicListEvent& aEvent, 

            TCbsTopicNumber& aNumber ) = 0;

        /**

        *   Cancels the pending notify request.

        */

        virtual void NotifyOnTopicListEventCancel() = 0;

        /**

        *   Returns the number of topics added since last GetNewTopicsCount()

        *   by the topic detection feature.

        *

        *   @param aCount       It will contain the amount of new topics.

        *   @return TInt Result code.

        */

        virtual TInt GetNewTopicsCount( TInt& aCount ) = 0;

        /**

        *   Returns the number of the topic which was last added 

        *   to topic list.

        *

        *   Note: if a topic list cache is maintained by the client

        *   (as CBS UI application does), this function has to 

        *   be called BEFORE calling GetTopicCount() and GetTopic() 

        *   to make sure that no topic is added in between 

        *   GetTopic() and GetLatestTopicHandle() calls. If this

        *   happens, GetLatestTopicHandle() will return a handle

        *   to a topic that is not cached client-side.            

        *        

        *   Return codes:

        *   KErrNone        aNumber is a valid topic number.

        *   KErrNotFound    No topic added since server start, 

        *                   aNumber is not valid.

        *

        *   @param  aNumber         Returns: number of the topic last added

        *   @return                 Result code

        */

        virtual TInt GetLatestTopicNumber( TCbsTopicNumber& aNumber ) = 0;

        /**

        *   Returns the total amount of unread messages.

        *

        *   @param  aCount          Return: number of unread messages

        */

        virtual void GetUnreadMessageCount( TInt& aCount ) = 0;

        /**

        *   Returns the handle to the latest hotmarked message that has been

        *   received after the system has started up.

        *   

        *   @param  aMessage        Handle to the message

        */

        virtual void GetHotmarkedMessageHandle( TCbsMessageHandle& aMessage ) = 0;

        /**

        *   Returns the number of unread messages in hotmarked topics.

        *

        *   This function is to used by the client when deciding whether

        *   the message or topic list view should be opened to display

        *   a hotmarked message(s).

        *

        *   @return                 Number of unread hotmarked messages

        */

        virtual TInt NumberOfUnreadHotmarkedMessages() = 0;

        /**

        *   Returns the numbers of topics that precede and succeed the given 

        *   topic in server-side topic list.

        *

        *   If the given topic is the first topic in list, aPosition has 

        *   ECbsHead bit up. If the given topic is the last topic in list,

        *   aPosition has ECbsTail bit up.

        *    

        *   Return code values:

        *   KErrNone		aPrevTopicNumber, aNextTopicNumber and aPosition 

        *		            contain valid values.

        *   KErrNotFound	aCurrentTopicNumber specified a topic that was not

        *                   on topic list.

        *

        *   @param  aCurrentTopicNumber	    Number that specifies the topic 

        *                                   whose surroundings are returned

        *   @param  aPrevTopicNumber		Returns: number of topic preceding 

        *                                   the given topic

        *   @param  aNextTopicNumber		Returns: number of topic succeeding

        *                                   the given topic

        *   @param  aPosition			    Returns: position of current 

        *                                   topic in list.

        *   @return 				        Result code

        */

        virtual TInt GetNextAndPrevTopicNumber( 

            const TCbsTopicNumber& aCurrentTopicNumber,

            TCbsTopicNumber& aPrevTopicNumber,

            TCbsTopicNumber& aNextTopicNumber,

            TInt& aPosition ) = 0;

        // === Topic Messages-related methods

        /**

        *   Returns the total amount of messages the topic contains.    

        *

        *   Return codes:

        *   KErrNotFound            Invalid handle.

        *   KErrNone                aCount contains the number of messages 

        *                           in topic

        *

        *   @param  aNumber         Number of the topic.

        *   @param  aCount          Number of messages in given topic.

        *   @return                 Result code

        */

        virtual TInt GetMessageCount( TCbsTopicNumber aNumber,

            TInt& aCount ) = 0;

        /**

        *   Returns message information.

        *

        *   Return codes:

        *   KErrNotFound        Topic or message not found.

        *   KErrNone            aMessage contains the message information.

        *

        *   @param  aNumber     Number of the topic

        *   @param  aIndex      Index to the message in topic.

        *   @param  aMessage    Returns: the message information

        *   @return             Error code

        */

        virtual TInt GetMessage( TCbsTopicNumber aNumber, TInt aIndex,

            TCbsMessage& aMessage ) = 0;

        /**

        *   Finds a message by given handle.

        *

        *   @param  aHandle     Handle to the message.

        *   @param  aMessage    Return: contains the message information.

        *   @return             Error code.

        */

        virtual TInt FindMessageByHandle( 

            const TCbsMessageHandle& aHandle, 

            TCbsMessage& aMessage ) = 0;

        /**

        *   Returns the index of a message with given handle in topic.

        *

        *   Result code KErrNotFound indicates that no message was found with

        *   the given handle.

        *

        *   @param  aHandle     Handle of the message

        *   @param  aIndex      Return: index of the message in message topic

        *   @return             Result code

        */

        virtual TInt GetMessageIndexByHandle( 

            const TCbsMessageHandle& aHandle, TInt& aIndex ) = 0;

        /**

        *   Deletes an existing message.

        *

        *   Note that it does not care a lot about the status of the message.

        *   

        *   Please check also the description of LockMessage().

        *

        *   @param  aHandle     It is handle to the message.

        *   @return             Error code.

        */

        virtual TInt DeleteMessage( const TCbsMessageHandle& aHandle ) = 0;

        /**

        *   Saves a message (the saved message won't be deleted to make 

        *   room for new messages).

        *

        *   Return codes:

        *   KErrNone            Message is saved.

        *   KErrGeneral         Message not saved -- total maximum of saved 

        *                       messages reached.

        *   KErrNotFound        Message not saved -- no message associated

        *                       with the given handle.

        *   KErrDiskFull        Message not saved -- FFS out of space.

        *

        *   @param  aHandle     Handle to the message to be saved.

        *   @return             Return code.

        */

        virtual TInt SaveMessage( const TCbsMessageHandle& aHandle ) = 0;

        /**

        *   Locks the message.

        *

        *   Note that a single topic messages subsession can have at most one locked

        *   message. 

        *

        *   Message can be unlocked by trying to lock a null message. Locked message

        *   will also be automatically unlocked when subsession is closed. If a message

        *   is locked, then it will not be deleted from the database. Thus, deleting a 

        *   message or trying to delete a topic that contains such a message will fail.

        *

        *   Locking a message does not prevent to save the message nor read the message.

        *

        *   @param  aHandle     It is handle to the message to be locked.

        *   @return             Error code.

        */

        virtual TInt LockMessage( const TCbsMessageHandle& aHandle ) = 0;

        /**

        *   Sets the message as read.

        *

        *   @param  aHandle     It is handle to the message to be set read.

        */

        virtual TInt ReadMessage( const TCbsMessageHandle& aHandle ) = 0;

        /**

        *   Returns the message contents.

        *

        *   @param  aHandle     It is handle to the message.

        *   @param  aBuffer     It will contain the contents (as much as it fits).

        *   @return             Error code.

        */

        virtual TInt GetMessageContents( 

            const TCbsMessageHandle& aHandle, 

            TDes& aBuffer ) = 0;

        /**

        *   Returns the handles of messages that precede and succeed the 

        *   given message in server-side list of topic messages.

        *

        *   Topic is resolved from the given message handle

        *

        *   If the given handle specifies the first message in topic,

        *   aPosition has ECbsHead bit up. If the given handle specifies 

        *   the last message in topic, aPosition has ECbsTail bit up.

        *    

        *    Return code values:

        *    KErrNone       aPrevMsgHandle, aNextMsgHandle and aPosition

        *                   contain valid values.

        *    KErrNotFound	aCurrentMsgHandle specified a message that was not

        *			        found.

        *

        *    @param  aCurrentMsgHandle		Handle that specifies the message 

        *                                   whose surroundings are returned

        *    @param  aPrevMsgHandle		    Returns: handle of message 

        *                                   preceding the given message

        *    @param  aNextMsgHandle		    Returns: handle of message 

        *                                   succeeding the given topic

        *    @param  aPosition			    Returns: position of current topic