/*
* 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 RCbsTopicList class
*
* RCbsTopicList provides an interface to CBS clients which
* allows accessing the Cell Broadcast topics stored
* in the CBS Server. Note: This class should not be directly
* accessed by the client application.
*
* Services include accessing and modifying topic information,
* deleting a single or all topics, and a notification service,
* that enables the client to receive notifications on
* events modifying the server's topic list.
*
*
*/
#ifndef RCBSTOPICLIST_H
#define RCBSTOPICLIST_H
// INCLUDES
#include <e32base.h>
#include "CbsCommon.h"
// FORWARD DECLARATIONS
class RCbs;
// CLASS DECLARATION
/**
* This class represents the client-side subsession to handle topic lists.
*/
class RCbsTopicList
: public RSubSessionBase
{
public: // New functions
/**
* Constructor.
*/
RCbsTopicList();
/**
* Creates a subsession to the server. Before using any other method it
* must be called.
* @param aServer It is the cbs server.
* @return Error code.
*/
TInt Open( RCbs& aServer );
/**
* Closes the subsession and connection to the server.
*
* @return Error code.
*/
TInt Close();
/**
* Returns the total amount of topics the topic list contains.
*
* @param aCount It will contain the total amount of topics.
*/
void GetTopicCount( TInt& aCount );
/**
* Returns information about a topic from the topic list.
*
* @param aIndex It is the index to the topic.
* @param aTopic It will contain the topic information.
* @return Error code.
*/
TInt GetTopic( const TInt aIndex, TCbsTopic& aTopic );
/**
* Finds the topic by given number.
*
* @param aNumber It is the number of the topic.
* @param aTopic It will contain the topic information.
* @return Error code.
*/
TInt FindTopicByNumber( TCbsTopicNumber aNumber, TCbsTopic& aTopic );
/**
* Deletes an existing topic.
*
* Note that the topic must exists.
*
* @param aNumber It is the handle to the topic to be deleted.
* @return Error code.
*/
TInt DeleteTopic( TCbsTopicNumber aNumber );
/**
* Delete all topics.
*
* @return Error code.
*/
TInt DeleteAllTopics();
/**
* Adds a new topic.
*
* Note that the number of the new topic must be unused.
*
* @param aTopic It contains the information of the new topic.
* @return Error code.
*/
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.
*
* @param aOldNumber Old topic number
* @param aNewNumber New topic number
* @param aName It is the new name of the topic.
* @return Error code.
*/
TInt ChangeTopicNameAndNumber(
TCbsTopicNumber aOldNumber,
TCbsTopicNumber aNewNumber,
const TCbsTopicName& aName );
/**
* Changes topic subscription status.
*
* @param aNumber Number of the topic
* @param aNewStatus It is the new subscription status.
* @return Error code.
*/
TInt ChangeTopicSubscriptionStatus( TCbsTopicNumber aNumber,
TBool aNewStatus );
/**
* Changes topic hotmark status.
*
* @param aNumber Number of the topic
* @param aNewStatus It is the new hotmark status.
* @return Error code.
*/
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 It is the variable that the server will modify whenever an event occurs.
* @param aRequested It contains the events the client is listening to.
* @param aEvent It will contain the event that occurred.
* @param aNumber Number of topic
*/
void NotifyOnEvent(
TRequestStatus& aStatus,
const TInt aRequested,
TCbsTopicListEvent& aEvent,
TCbsTopicNumber& aNumber );
/**
* Cancels the pending notify request.
*/
void NotifyOnEventCancel();
/**
* Returns the number of session-specific new topics and resets the counter.
* New topics are added by the topic detection feature in absence of
* CBS UI Application.
*
* @param aCount On return contains the amount of new topics.
* @return Result code.
*/
TInt GetNewTopicsCount( TInt& aCount );
/**
* Returns the latest topic's number.
*
* @param aNumber Number of the topic
* @return Result code.
*/
TInt GetLatestTopicNumber( TCbsTopicNumber& aNumber );
/**
* Returns the total amount of unread messages.
*
* @param aCount It will contain the amount of unread messages.
*/
void GetUnreadMessageCount( TInt& aCount );
/**
* Returns the handle to the latest hotmarked message that has been
* received after the system has started up.
*
* @param aMessage It is handle to the message.
*/
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
*/
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
*/
TInt GetNextAndPrevTopicNumber(
const TCbsTopicNumber& aCurrentTopicNumber,
TCbsTopicNumber& aPrevTopicNumber,
TCbsTopicNumber& aNextTopicNumber,
TInt& aPosition );
private: // prohibited functions
// Prohibited copy constructor
RCbsTopicList( const RCbsTopicList& );
// Prohibited assignment operator
RCbsTopicList& operator=( const RCbsTopicList& );
private: // Data
// A pointer descriptor used to transfer information
// during a notify request.
TPtr8 iNotifyEventPtr;
// A pointer descriptor used to transfer information
// during a notify request.
TPtr8 iNotifyHandlePtr;
};
#endif // RCBSTOPICLIST_H
// End of File