1 /* |
|
2 * Copyright (c) 2003 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: This file contains the header file of the RCbsTopicMessages class |
|
15 * |
|
16 * Client-side subsession handling requests which regard |
|
17 * CB messages. |
|
18 * |
|
19 * |
|
20 */ |
|
21 |
|
22 |
|
23 |
|
24 #ifndef RCBSTOPICMESSAGES_H |
|
25 #define RCBSTOPICMESSAGES_H |
|
26 |
|
27 // INCLUDES |
|
28 #include <e32base.h> |
|
29 #include "CbsCommon.h" |
|
30 |
|
31 // FORWARD DECLARATIONS |
|
32 class RCbs; |
|
33 |
|
34 // CLASS DECLARATION |
|
35 |
|
36 // Client-side subsession handling requests regarding |
|
37 // CB messages. |
|
38 // |
|
39 class RCbsTopicMessages |
|
40 : public RSubSessionBase |
|
41 { |
|
42 public: // New functions |
|
43 /** |
|
44 * Constructor. |
|
45 */ |
|
46 RCbsTopicMessages(); |
|
47 |
|
48 /** |
|
49 * Creates a subsession to the server. Before using any other method |
|
50 * it must be called. |
|
51 * |
|
52 * @param aServer It is the cbs server. |
|
53 * @return Return code. |
|
54 */ |
|
55 TInt Open( RCbs& aServer ); |
|
56 |
|
57 /** |
|
58 * Closes the subsession. |
|
59 * |
|
60 * @return Return code. |
|
61 */ |
|
62 TInt Close(); |
|
63 |
|
64 /** |
|
65 * Returns the total amount of messages the topic contains. |
|
66 * |
|
67 * @param aNumber Topic number. |
|
68 * @param aCount It will contain the total amount of |
|
69 * messages. |
|
70 */ |
|
71 TInt GetMessageCount( TCbsTopicNumber aNumber, TInt& aCount ); |
|
72 |
|
73 /** |
|
74 * Returns message information. |
|
75 * |
|
76 * @param aNumber Topic number |
|
77 * @param aIndex It is index to the message in topic. |
|
78 * @param aMessage It will contain the message information. |
|
79 * @return Return code. |
|
80 */ |
|
81 TInt GetMessage( TCbsTopicNumber aNumber, TInt aIndex, |
|
82 TCbsMessage& aMessage ); |
|
83 |
|
84 /** |
|
85 * Finds a message by given handle. |
|
86 * |
|
87 * @param aHandle It is handle to the message. |
|
88 * @param aMessage It will contain the message information. |
|
89 * @return Return code. |
|
90 */ |
|
91 TInt FindMessageByHandle( const TCbsMessageHandle& aHandle, |
|
92 TCbsMessage& aMessage ); |
|
93 |
|
94 /** |
|
95 * Returns the index of a message with given handle in topic. |
|
96 * |
|
97 * Result code KErrNotFound indicates that no message was found with |
|
98 * the given handle. |
|
99 * |
|
100 * @param aHandle Handle of the message |
|
101 * @param aIndex Return: index of the message in message topic |
|
102 * @return Result code |
|
103 */ |
|
104 TInt GetMessageIndexByHandle( |
|
105 const TCbsMessageHandle& aHandle, TInt& aIndex ); |
|
106 |
|
107 /** |
|
108 * Deletes an existing message. |
|
109 * |
|
110 * Note that it does not care a lot about the status of the message. |
|
111 * |
|
112 * Check also the description of LockMessage method. |
|
113 * |
|
114 * @param aHandle It is handle to the message. |
|
115 * @return Return code. |
|
116 */ |
|
117 TInt DeleteMessage( const TCbsMessageHandle& aHandle ); |
|
118 |
|
119 /** |
|
120 * Saves a message (i.e., the saved message won't be deleted to make |
|
121 * room for new messages). |
|
122 * |
|
123 * Return codes: |
|
124 * KErrNone Message is saved. |
|
125 * KErrGeneral Message not saved -- total maximum of saved |
|
126 * messages reached. |
|
127 * |
|
128 * @param aHandle Handle to the message to be saved. |
|
129 * @return Return code. |
|
130 */ |
|
131 TInt SaveMessage( const TCbsMessageHandle& aHandle ); |
|
132 |
|
133 /** |
|
134 * Locks the message. |
|
135 * |
|
136 * Note that a single topic messages subsession can have at most one |
|
137 * locked message. |
|
138 * |
|
139 * Message can be unlocked by trying to lock a null message. Locked |
|
140 * message will also be automatically unlocked when subsession is |
|
141 * closed. If a message is locked, then it will not be deleted from |
|
142 * the database. Thus, deleting a message or trying to delete a |
|
143 * topic that contains such a message will fail. |
|
144 * |
|
145 * Locking a message does not prevent to save the message nor read |
|
146 * the message. |
|
147 * |
|
148 * @param aHandle It is handle to the message to be locked. |
|
149 * @return Return code. |
|
150 */ |
|
151 TInt LockMessage( const TCbsMessageHandle& aHandle ); |
|
152 |
|
153 /** |
|
154 * Sets the message as read. |
|
155 * |
|
156 * @param aHandle It is handle to the message to be set read. |
|
157 */ |
|
158 TInt ReadMessage( const TCbsMessageHandle& aHandle ); |
|
159 |
|
160 /** |
|
161 * Returns the message contents. |
|
162 * |
|
163 * @param aHandle It is handle to the message. |
|
164 * @param aBuffer It will contain the contents (as much as it fits). |
|
165 * @return Return code. |
|
166 */ |
|
167 TInt GetMessageContents( const TCbsMessageHandle& aHandle, |
|
168 TDes& aBuffer ); |
|
169 |
|
170 /** |
|
171 * Returns the handles of messages that precede and succeed the |
|
172 * given message in server-side list of topic messages. |
|
173 * |
|
174 * Topic is resolved from the given message handle |
|
175 * |
|
176 * If the given handle specifies the first message in topic, |
|
177 * aPosition has ECbsHead bit up. If the given handle specifies |
|
178 * the last message in topic, aPosition has ECbsTail bit up. |
|
179 * |
|
180 * Return code values: |
|
181 * KErrNone aPrevMsgHandle, aNextMsgHandle and aPosition |
|
182 * contain valid values. |
|
183 * KErrNotFound aCurrentMsgHandle specified a message that was not |
|
184 * found. |
|
185 * |
|
186 * @param aCurrentMsgHandle Handle that specifies the message |
|
187 * whose surroundings are returned |
|
188 * @param aPrevMsgHandle Returns: handle of message |
|
189 * preceding the given message |
|
190 * @param aNextMsgHandle Returns: handle of message |
|
191 * succeeding the given topic |
|
192 * @param aPosition Returns: position of current topic |
|
193 * in list |
|
194 * @return Result code |
|
195 */ |
|
196 IMPORT_C TInt GetNextAndPrevMessageHandle( |
|
197 const TCbsMessageHandle& aCurrentMsgHandle, |
|
198 TCbsMessageHandle& aPrevMsgHandle, |
|
199 TCbsMessageHandle& aNextMsgHandle, |
|
200 TInt& aPosition ); |
|
201 |
|
202 }; |
|
203 |
|
204 #endif // RCBSTOPICMESSAGES_H |
|
205 |
|
206 // End of File |
|
207 |
|
208 |
|