cbs/CbsServer/ClientInc/RCbs.h
changeset 46 2fa1fa551b0b
parent 42 35488577e233
child 48 78df25012fda
--- a/cbs/CbsServer/ClientInc/RCbs.h	Mon Aug 23 15:50:31 2010 +0300
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,629 +0,0 @@
-/*
-* 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.
-        */
-        IMPORT_C TInt ReadMessage( const TCbsMessageHandle& aHandle );
-        
-        /**
-        *   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.
-        */
-        IMPORT_C TInt GetMessageContents( 
-            const TCbsMessageHandle& aHandle, 
-            TDes& aBuffer );
-
-        /**
-        *   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 
-        *                                   in list
-        *    @return 				        Result code
-        */
-        IMPORT_C TInt GetNextAndPrevMessageHandle(
-	        const TCbsMessageHandle& aCurrentMsgHandle,
-	        TCbsMessageHandle& aPrevMsgHandle,
-	        TCbsMessageHandle& aNextMsgHandle,
-	        TInt& aPosition );
-
-        // Other methods
-
-        /**
-        *   Returns ETrue if CbsServer session has been established.
-        *
-        *   @return                     ETrue, if session open.
-        */
-        IMPORT_C TBool Connected() const;
-
-        /**
-        *   Forces the server to shut down.
-        *        
-        */
-        IMPORT_C void Shutdown() const;
-
-    private:    // starting server
-        /**
-        *   Starts the server.
-        */
-        TInt StartServer();
-
-        /**
-        *   Checks if the server is already started.
-        */
-        TBool IsServerStarted();
-
-    private:
-
-        // Copy constructor
-        RCbs( const RCbs& );
-
-        // Assignment operator
-        RCbs& operator=( const RCbs& );
-    
-    private:
-        // Settings subsession
-        RCbsSettings iSettings;
-
-        // Topic list subsession
-        RCbsTopicList iTopicList;
-
-        // Topic messages subsession
-        RCbsTopicMessages iTopicMessages;
-
-        // Collection subsession
-        RCbsTopicCollection iTopicCollection;
-
-        // ETrue, if the session has been established
-        TBool iConnected;
-    };
-
-#endif      //  RCbs_H   
-            
-// End of File
-
-