/*

* Copyright (c) 2003 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:  This file contains the header file of the RCbs class.

*    

*                The client of the CBS Server is required to import this header file

*                into project. The connection to the server is made with Connect()

*                 and closed with Close().

*

*                RCbs provides the interface to CBS clients for accessing the    

*                CBS server. It uses subsession classes RCbsSettings, RCbsTopicList,

*                RCbsTopicMessages and RCbsTopicCollection to actually carry out

*                the required ITC between client and server threads.

*

*

*/

#ifndef     RCBS_H

#define     RCBS_H

// INCLUDES

#include <e32base.h>

#include "CbsCommon.h"

#include "RCbsSettings.h"

#include "RCbsTopicCollection.h"

#include "RCbsTopicList.h"

#include "RCbsTopicMessages.h"

//  CLASS DECLARATION 

/**

*   This represents the client-side session to the cbs server.

*

*   Every client must have an instance of the class to be able to communicate

*   with the server.

*

*   Note that both client and server must use the same versions of the API.

*   Otherwise the server will terminate the client process.

*

*   - The server does not buffer events. This must be taken into

*     account when using notifications.

*   - There can only be one pending notification request per subsession object.

*     The behaviour is undefined, if you try to make several for only one 

*      subsession.

*/

class RCbs 

        : public RSessionBase

    {

    public:     // New functions

        /**

        *   Constructor.

        */

        IMPORT_C RCbs();

        /**

        *   Destructor.

        */

        IMPORT_C ~RCbs();

        /**

        *   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.

        */

        IMPORT_C TInt Connect();

        /**

        *   Closes the session to the server.

        */

        IMPORT_C void Close();

        /**

        *   Returns the version of CbsClient.

        *

        *   CbsServer and CbsClient must be of same version.

        *

        *   @return                 Returns the version of CbsClient.

        */

        IMPORT_C TVersion Version() const;

        // === 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.

        */

        IMPORT_C void GetReceptionStatus( TBool& aStatus );

        /**

        *   Changes the reception status to aStatus.

        *

        *   @param  aStatus     It contains the new reception status.

        *   @return             KErrNone if succeeded.

        */

        IMPORT_C TInt SetReceptionStatus( TBool aStatus );

        /**

        *   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.

        */

        IMPORT_C void GetTopicDetectionStatus( TBool& aStatus );

        /**

        *   Changes the topic detection status to aStatus.

        *

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

        *   @return             KErrNone if succeeded.

        */

        IMPORT_C TInt SetTopicDetectionStatus( TBool aStatus );

        /**

        *   Returns the preferred languages in aLanguages.

        *

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

        */

        IMPORT_C void GetLanguages( TCbsSettingsLanguages& aLanguages );

        /**

        *   Changes the preferred languages to aLanguages.

        *

        *   @param aLanguages   It contains the new preferred languages.

        *   @return             KErrNone if succeeded.

        */

        IMPORT_C TInt SetLanguages( const TCbsSettingsLanguages& aLanguages );

        /**

        *   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.

        */

        IMPORT_C void NotifySettingsChanged( TRequestStatus& aStatus, 

            TCbsSettingsEvent& aEvent );

        /**

        *   Cancels the request to notify the client.

        */

        IMPORT_C void NotifySettingsChangedCancel();

        //  === Topic Collection-related methods

        /**

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

        *   or NextTopic()!

        */

        IMPORT_C void StartCollectionBrowsing();

        /**

        *   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.

        */

        IMPORT_C TBool HasNextCollectionTopic();                            

        /**

        *   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.

        */

        IMPORT_C TInt NextCollectionTopic( TCbsTopicInfo& aInfo );

        //  === Topic list-related methods

        /**

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

        *

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

        */

        IMPORT_C void GetTopicCount( TInt& aCount );

        /**

        *   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.

        */

        IMPORT_C TInt GetTopic( const TInt aIndex, TCbsTopic& aTopic );

        /**

        *   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

        */

        IMPORT_C TInt FindTopicByNumber( TCbsTopicNumber aNumber,

            TCbsTopic& aTopic );

        /** 

        *   Deletes an existing topic.

        *

        *   @param  aNumber         Number of the topic to be deleted

        *   @return                 Error code

        */

        IMPORT_C TInt DeleteTopic( TCbsTopicNumber aNumber );

        /**

        *   Delete all topics.

        *

        *   @return             Error code.

        */

        IMPORT_C TInt DeleteAllTopics();

        /**

        *   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.

        */

        IMPORT_C TInt AddTopic( TCbsTopic& aTopic );

        /**

        *   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

        */  

        IMPORT_C TInt ChangeTopicNameAndNumber( 

            TCbsTopicNumber aOldNumber,

            TCbsTopicNumber aNewNumber, 

            const TCbsTopicName& aName );

        /**

        *   Changes topic subscription status.

        *

        *   @param  aNumber         Number of the topic

        *   @param  aNewStatus      New subscription status

        *   @return                 Error code

        */

        IMPORT_C TInt ChangeTopicSubscriptionStatus( 

            TCbsTopicNumber aNumber, TBool aNewStatus );

        /**

        *   Changes topic hotmark status.

        *

        *   @param  aNumber         Number of the topic

        *   @param  aNewStatus      New hotmark status

        *   @return                 Error code

        */

        IMPORT_C TInt ChangeTopicHotmarkStatus( TCbsTopicNumber aNumber,

            TBool aNewStatus );

        /**

        *   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.

        */

        IMPORT_C void NotifyOnTopicListEvent( 

            TRequestStatus& aStatus, 

            const TInt aRequested, 

            TCbsTopicListEvent& aEvent, 

            TCbsTopicNumber& aNumber );

        /**

        *   Cancels the pending notify request.

        */

        IMPORT_C void NotifyOnTopicListEventCancel();

        /**

        *   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.

        */

        IMPORT_C TInt GetNewTopicsCount( TInt& aCount );

        /**

        *   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

        */

        IMPORT_C TInt GetLatestTopicNumber( TCbsTopicNumber& aNumber );

        /**

        *   Returns the total amount of unread messages.

        *

        *   @param  aCount          Return: number of unread messages

        */

        IMPORT_C void GetUnreadMessageCount( TInt& aCount );

        /**

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

        *   received after the system has started up.

        *   

        *   @param  aMessage        Handle to the message

        */

        IMPORT_C void GetHotmarkedMessageHandle( TCbsMessageHandle& aMessage );

        /**

        *   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

        */

        IMPORT_C TInt NumberOfUnreadHotmarkedMessages();

        /**

        *   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

        */

        IMPORT_C TInt GetNextAndPrevTopicNumber( 

	        const TCbsTopicNumber& aCurrentTopicNumber,

	        TCbsTopicNumber& aPrevTopicNumber,

	        TCbsTopicNumber& aNextTopicNumber,

	        TInt& aPosition );

        // === 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

        */

        IMPORT_C TInt GetMessageCount( TCbsTopicNumber aNumber,

            TInt& aCount );

        /**

        *   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

        */

        IMPORT_C TInt GetMessage( TCbsTopicNumber aNumber, TInt aIndex,

            TCbsMessage& aMessage );

        /**

        *   Finds a message by given handle.

        *

        *   @param  aHandle     Handle to the message.

        *   @param  aMessage    Return: contains the message information.

        *   @return             Error code.

        */

        IMPORT_C TInt FindMessageByHandle( 

            const TCbsMessageHandle& aHandle, 

            TCbsMessage& aMessage );

        /**

        *   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

        */

        IMPORT_C TInt GetMessageIndexByHandle( 

            const TCbsMessageHandle& aHandle, TInt& aIndex );

        /**

        *   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.

        */

        IMPORT_C TInt DeleteMessage( const TCbsMessageHandle& aHandle );

        /**

        *   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.

        */

        IMPORT_C TInt SaveMessage( const TCbsMessageHandle& aHandle );

        /**

        *   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.

        */

        IMPORT_C TInt LockMessage( const TCbsMessageHandle& aHandle );

        /**

        *   Sets the message as read.

        *

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

        *   @return             Error code.

        */