diff -r 1f002146abb4 -r 8d5d7fcf9b59 cbs/cbsserver/ClientInc/RCbs.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/cbs/cbsserver/ClientInc/RCbs.h Wed Jul 21 18:26:52 2010 +0300 @@ -0,0 +1,629 @@ +/* +* 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 +#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 + +