diff -r 7d48bed6ce0c -r 987c9837762f cbs/cbsui/inc/mcbs.h --- a/cbs/cbsui/inc/mcbs.h Tue Aug 31 15:45:17 2010 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,557 +0,0 @@ -/* -* Copyright (c) 2010 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 - -/** -* 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 - * in list - * @return Result code - */ - virtual TInt GetNextAndPrevMessageHandle( - const TCbsMessageHandle& aCurrentMsgHandle, - TCbsMessageHandle& aPrevMsgHandle, - TCbsMessageHandle& aNextMsgHandle, - TInt& aPosition ) = 0; - - // Other methods - - /** - * Returns ETrue if CbsServer session has been established. - * - * @return ETrue, if session open. - */ - virtual TBool Connected() const = 0; - - /** - * Forces the server to shut down. - * - * NOTE: Shutdown not fully implemented in CbsServer yet. - */ - virtual void Shutdown() const = 0; - - }; - -#endif // MCBS_H - -// End of file