--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/cbs/CbsServer/ClientInc/RCbs.h Tue Feb 02 01:11:09 2010 +0200
@@ -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 <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
+
+