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 Cmcn class. |
|
15 * |
|
16 * This header file presents an API which allows a client to |
|
17 * subscribe a number of CB topics from CbsServer. The client |
|
18 * receives a notification, if a message belonging to a subscribed |
|
19 * topic is received. |
|
20 * |
|
21 */ |
|
22 |
|
23 |
|
24 |
|
25 #ifndef CMCN_H |
|
26 #define CMCN_H |
|
27 |
|
28 // INCLUDES |
|
29 #include "e32base.h" |
|
30 #include <rcbsmcnsession.h> |
|
31 |
|
32 // CONSTANTS |
|
33 // Maximum length of a MCN message. |
|
34 const TInt KCbsMcnMessageMaxLength = 93; |
|
35 |
|
36 // DATA TYPES |
|
37 typedef TBuf< KCbsMcnMessageMaxLength > TMcnMessage; |
|
38 |
|
39 // FORWARD DECLARATIONS |
|
40 class MCbsMcnObserver; |
|
41 class CCbsMcnListener; |
|
42 class RCbsMcnSession; |
|
43 class CMcnTopicArray; |
|
44 |
|
45 // CLASS DECLARATION |
|
46 |
|
47 /** |
|
48 * Client must first connect to the server and then register |
|
49 * a MCbsMcnObserver-derived class to receive notifications |
|
50 * when MCN messages are received from the network. |
|
51 * |
|
52 * Registration to CbsServer is not required to retrieve |
|
53 * the current cell info message. |
|
54 * |
|
55 * In the example below, the client has implemented the class MCbsMcnObserver |
|
56 * in class CCbsMcnObserver. First, the client establishes a session |
|
57 * with CbsServer. The subscribed topics are specified with a CMcnTopicArray |
|
58 * instance. |
|
59 * |
|
60 * Example: |
|
61 * |
|
62 * // Establish the session. |
|
63 * CMcn* session = CMcn::NewL(); |
|
64 * CleanupStack::PushL( session ); |
|
65 * |
|
66 * // Specify topics with CMcnTopicArray. |
|
67 * CMcnTopicArray* topics = CMcnTopicArray::NewL(); |
|
68 * topics->AddCbTopicL( 50 ); // District info (cell info) |
|
69 * topics->AddCbTopicL( 0 ); // CB index messages |
|
70 * |
|
71 * // Register. Parameter observer is an instance of CCbsMcnObserver. |
|
72 * session->RegisterL( observer, topics ); |
|
73 * delete topics; |
|
74 * |
|
75 * // Get current MCN state. |
|
76 * TMcnMessage mcnInfo; |
|
77 * TInt result( session->GetCellInfo( mcnInfo ) ); |
|
78 * if ( result != KErrNone ) |
|
79 * { |
|
80 * // mcnInfo contains the current MCN message. |
|
81 * } |
|
82 * |
|
83 * // Observer's CellInfoChanged() gets called if MCN state changes. |
|
84 * // Note that the active scheduler must be running here. |
|
85 * |
|
86 * // Terminate session. |
|
87 * session->Unregister( observer ); |
|
88 * CleanupStack::PopAndDestroy(); // session, gets closed when deleted |
|
89 * |
|
90 */ |
|
91 class CMcn |
|
92 : public CBase |
|
93 { |
|
94 public: // New functions |
|
95 /** |
|
96 * Instantiates new CMcn object and establishes a session with |
|
97 * CBS server. |
|
98 * |
|
99 * If connecting to CBS server fails, the function leaves with |
|
100 * the leave code of RSessionBase::CreateSession(). |
|
101 * |
|
102 * Active scheduler has to be installed prior to calling this function. |
|
103 * |
|
104 * @return A new instance of CMcn |
|
105 */ |
|
106 IMPORT_C static CMcn* NewL(); |
|
107 |
|
108 /** |
|
109 * Destructor. Also closes CbsServer session. |
|
110 */ |
|
111 IMPORT_C ~CMcn(); |
|
112 |
|
113 /** |
|
114 * Registers an observer to CBS server. The observer is notified when |
|
115 * a MCN message is received from the network. |
|
116 * The caller is also required to provide an array containing numbers |
|
117 * of subscribed topics. |
|
118 * |
|
119 * Parameter aArray may contain topic number entry duplicates. |
|
120 * Topics may be in any order. |
|
121 * |
|
122 * Leave codes indicate an error accessing EPOC Telephony Sever. |
|
123 * In this case, the leave code is the same returned by EPOC Telephony Sever. |
|
124 * |
|
125 * @param aObserver Observer implemented by the client |
|
126 * @param aArray List of relayed topics |
|
127 */ |
|
128 IMPORT_C void RegisterL( MCbsMcnObserver* aObserver, |
|
129 const CMcnTopicArray& aArray ); |
|
130 |
|
131 /** |
|
132 * Unregisters a previously registered MCN observer clearing |
|
133 * any topic subscriptions of this client in CBS server. |
|
134 * |
|
135 * Panics if the observer specified was not registered. |
|
136 * |
|
137 * @param aObserver Observer implemented by the client |
|
138 */ |
|
139 IMPORT_C void Unregister( MCbsMcnObserver* aObserver ); |
|
140 |
|
141 /** |
|
142 * Retrieves the current MCN message (Cell Info, topic 050) from CBS |
|
143 * server. A new MCN message always overwrites the previous one in CBS |
|
144 * server, no buffering is done. Note that this function may be |
|
145 * only used to retrieve cell info messages. |
|
146 * |
|
147 * Return codes: |
|
148 * KErrNone aMcnMessage contains the current, valid MCN message. |
|
149 * KErrNotFound CbsServer has not yet received a MCN message. |
|
150 * Content of aMcnMessage must be ignored. |
|
151 * |
|
152 * @param aMcnMessage Returns the current MCN message. |
|
153 * @return Result code |
|
154 */ |
|
155 IMPORT_C TInt GetCellInfo( TDes& aMcnMessage ) const; |
|
156 |
|
157 private: // new functions |
|
158 /** |
|
159 * Default constructor. |
|
160 */ |
|
161 CMcn(); |
|
162 |
|
163 /** |
|
164 * 2nd-phase constructor |
|
165 */ |
|
166 void ConstructL(); |
|
167 |
|
168 /** |
|
169 * Relays aMcnMessage to the registered observers. |
|
170 * Used by a friend class CCbsMcnListener instance |
|
171 * |
|
172 * @param aMcnMessage Received CB message from CbsServer |
|
173 */ |
|
174 void RelayMessage( TCbsMcnMessage& aMcnMessage ); |
|
175 |
|
176 private: // friend classes |
|
177 /// Allows use of RelayMessageL(). |
|
178 friend class CCbsMcnListener; |
|
179 |
|
180 private: // prohibited functions and operators |
|
181 /// Copy constructor. |
|
182 CMcn( const CMcn& ); |
|
183 |
|
184 /// Assignment operator |
|
185 CMcn& operator=( const CMcn& ); |
|
186 |
|
187 private: // Data |
|
188 /** |
|
189 * Own: Active object responsible for responding to server-initiated |
|
190 * notification indicating that a message has arrived from |
|
191 * the CbsServer. |
|
192 */ |
|
193 CCbsMcnListener* iMcnListener; |
|
194 |
|
195 /// Own: Dynamic array containing the registered observers. |
|
196 CArrayPtrFlat< MCbsMcnObserver >* iObservers; |
|
197 |
|
198 /// CbsServer session object. |
|
199 RCbsMcnSession iSession; |
|
200 |
|
201 public: |
|
202 |
|
203 /** |
|
204 * Retrieves the current info message (e.g. HomeZone, topic 221) from CBS |
|
205 * server. A new info message always overwrites the previous one in CBS |
|
206 * server, no buffering is done. Note that this function may be |
|
207 * only used to retrieve cell info messages. |
|
208 * |
|
209 * Return codes: |
|
210 * KErrNone aInfoMessage contains the current, valid info message. |
|
211 * KErrNotFound CbsServer has not yet received a info message. |
|
212 * Content of aInfoMessage must be ignored. |
|
213 * |
|
214 * @param aInfoMessage Returns the current info message. |
|
215 * @param aTopicNumber Number of the topic |
|
216 * @return Result code |
|
217 */ |
|
218 IMPORT_C TInt GetInfoMessage( TDes& aInfoMessage, TInt aTopicNumber ) const; |
|
219 }; |
|
220 |
|
221 #endif // CMCN_H |
|
222 |
|
223 // End of File |
|
224 |
|
225 |
|