|
1 /* |
|
2 * Copyright (c) 2006-2009 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: |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 #ifndef HWRMFMTX_H |
|
21 #define HWRMFMTX_H |
|
22 |
|
23 // INCLUDES |
|
24 |
|
25 #include <e32base.h> |
|
26 #include <hwrm/hwrmfmtxdata.h> |
|
27 |
|
28 // FUNCTION PROTOTYPES |
|
29 |
|
30 // FORWARD DECLARATIONS |
|
31 class MHWRMFmTxObserver; |
|
32 |
|
33 // CLASS DECLARATIONS |
|
34 |
|
35 /** |
|
36 * Base class of FM Tx Client API of HWRM |
|
37 * |
|
38 * The HWRM FM Tx API provides the ability to control the device's FM radio transmitter |
|
39 * |
|
40 * @publishedPartner |
|
41 * @deprecated |
|
42 */ |
|
43 class CHWRMFmTx : public CBase |
|
44 { |
|
45 public: // Constructors |
|
46 |
|
47 /** |
|
48 * Two-phased constructor for implementation class. |
|
49 * Use this method for creating a FM Tx client with callbacks. |
|
50 * |
|
51 * @param aCallback Pointer to callback instance (NULL if callbacks are |
|
52 * not required). |
|
53 * @return New CHWRMFmTx implementing instance. |
|
54 * @exception KErrNotSupported Device doesn't support FM Tx feature. |
|
55 * KErrNoMemory if there is a memory allocation failure. |
|
56 */ |
|
57 IMPORT_C static CHWRMFmTx* NewL(MHWRMFmTxObserver* aCallback = NULL); |
|
58 |
|
59 /** |
|
60 * Two-phased constructor for implementation class. |
|
61 * Use this method for creating a FM Tx client with callbacks. |
|
62 * Leaves instance on cleanup stack. |
|
63 * |
|
64 * @param aCallback Pointer to callback instance (NULL if callbacks are |
|
65 * not required). |
|
66 * @return New CHWRMFmTx implementing instance. |
|
67 * @exception KErrNotSupported Device doesn't support FM Tx feature. |
|
68 * KErrNoMemory if there is a memory allocation failure. |
|
69 */ |
|
70 IMPORT_C static CHWRMFmTx* NewLC(MHWRMFmTxObserver* aCallback = NULL); |
|
71 |
|
72 public: // New functions |
|
73 |
|
74 /** |
|
75 * Reserves FM Tx resource exclusively for this client. |
|
76 * A higher priority client may cause lower priority client reservation to be |
|
77 * temporarily suspended. If FM Tx is already reserved by a higher or equal |
|
78 * priority application, reserving will still succeed, but reservation is |
|
79 * immediately suspended. |
|
80 * The suspended client will not get any notification about suspension. Any |
|
81 * ongoing commands will be cancelled, when a client’s reservation is suspended. |
|
82 * Only reservation and status query commands may be issued, in the suspended |
|
83 * state. |
|
84 * |
|
85 * @param aForceNoCCoeEnv If EFalse, then reservation requires that this |
|
86 * client is on the foreground at the time of reservation and FM Tx |
|
87 * will be automatically released and re-reserved based on |
|
88 * background/foreground status of the this client. This also implies |
|
89 * that CCoeEnv::Static() != NULL is required. |
|
90 * If ETrue, the client will not require CCoeEnv to be present nor |
|
91 * does it automatically reserve/release FM Tx. |
|
92 * Only trusted clients are allowed to set this flag to ETrue. |
|
93 * |
|
94 * @exception KErrAccessDenied if aForceNoCCoeEnv is ETrue and client is not |
|
95 * trusted. |
|
96 * KErrBadHandle if aForceNoCCoeEnv is EFalse and no CCoeEnv present. |
|
97 * KErrNotReady if trying to reserve while on background and |
|
98 * aForceNoCCoeEnv is EFalse. |
|
99 * KErrNoMemory if there is a memory allocation failure. |
|
100 */ |
|
101 virtual void ReserveL(TBool aForceNoCCoeEnv)=0; |
|
102 |
|
103 /** |
|
104 * Releases FM Tx resource, if it was previously reserved for this client. |
|
105 * If this client has not reserved FM Tx, then this method does nothing. |
|
106 */ |
|
107 virtual void Release() = 0; |
|
108 |
|
109 /** |
|
110 * This method retrieves the current FM Tx state. |
|
111 * |
|
112 * @return TFmTxState The current FM Tx state. |
|
113 * @see MHWRMFmTxObserver |
|
114 */ |
|
115 virtual TFmTxState Status() const = 0; |
|
116 |
|
117 /** |
|
118 * The EnableL method switches the FM transmitter on. This is a synchronous |
|
119 * method that will block the client application. |
|
120 * |
|
121 * @param aFrequency The initial transmitter frequency. Defaults to the previous |
|
122 * frequency setting in Central Repository. |
|
123 * @exception KErrInUse if reserved by another client. |
|
124 * KErrArgument if frequency is out of range |
|
125 * KErrNotReady if there is a wired accessory conflict. Some |
|
126 * accessories are mutually exclusive with FM Tx. |
|
127 * KErrNoMemory if there is a memory allocation failure. |
|
128 * KErrGeneral if there is a hardware error. |
|
129 */ |
|
130 virtual void EnableL(TInt aFrequency=0) = 0; |
|
131 |
|
132 /** |
|
133 * The DisableL method switches the FM transmitter off. This is a synchronous |
|
134 * method that will block the client application. |
|
135 * |
|
136 * @exception KErrInUse if reserved by another client. |
|
137 * KErrGeneral if there is a hardware error. |
|
138 */ |
|
139 virtual void DisableL() = 0; |
|
140 |
|
141 /** |
|
142 * The Frequency method queries the current FM Tx frequency |
|
143 * |
|
144 * @return TInt The current FM Tx frequency (kHz). |
|
145 */ |
|
146 virtual TInt Frequency() const = 0; |
|
147 |
|
148 /** |
|
149 * The GetFrequencyRangeL method queries the valid FM frequency range |
|
150 * |
|
151 * @param aFrequencyRange On return, min. and max. frequencies and step size |
|
152 * of the FM range (kHz) |
|
153 * @exception KErrInUse if reserved by another client |
|
154 * KErrGeneral if there is a hardware error |
|
155 */ |
|
156 virtual void GetFrequencyRangeL(TFmTxFrequencyRange& aFrequencyRange) const = 0; |
|
157 |
|
158 /** |
|
159 * The SetFrequencyL method sets the FM transmission frequency. FM Tx |
|
160 * does not need to be enabled. This is a synchronous method |
|
161 * that will block the client application. |
|
162 * |
|
163 * @param TInt aFrequency The new Tx frequency (Hz) |
|
164 * @exception KErrInUse if reserved by another client |
|
165 * KErrArgument if frequency parameter is out of range |
|
166 * KErrGeneral if there is a hardware error |
|
167 */ |
|
168 virtual void SetFrequencyL(TInt aFrequency) = 0; |
|
169 |
|
170 /** |
|
171 * The GetNextClearFrequency method requests a new clear frequency |
|
172 * suggestion. This results in a RSSI scan at the hardware level, |
|
173 * starting from the frequency increment after the previous suggested |
|
174 * clear frequency. This is a synchronous method that will block |
|
175 * the client application. |
|
176 * |
|
177 * @param aClearFrequency On return, this is set to a new (suggested) |
|
178 * clear frequency. |
|
179 * @exception KErrInUse if reserved by another client |
|
180 * KErrNotSupported if RSSI scanning is unsupported |
|
181 * KErrGeneral if there is a hardware error |
|
182 * KErrNotReady if FM Tx is not enabled |
|
183 */ |
|
184 virtual void GetNextClearFrequencyL(TInt& aClearFrequency) = 0; |
|
185 |
|
186 /** |
|
187 * The GetNextClearFrequency method requests a new clear frequency |
|
188 * suggestion. This results in a RSSI scan at the hardware level, |
|
189 * starting from the frequency increment after the previous suggested |
|
190 * clear frequency. This is a synchronous method that will block |
|
191 * the client application. |
|
192 * |
|
193 * @param aClearFrequencyArray On return, this contains 0-KClearFrequencyArrayMax |
|
194 * clear frequencies. |
|
195 * @param aCount The number of clear frequencies requested (1-KClearFrequencyArrayMax) |
|
196 * On return, this is set to the actual number of clear frequencies found. |
|
197 * @exception KErrInUse if reserved by another client |
|
198 * KErrArgument If aCount is out of range |
|
199 * KErrNotSupported if RSSI scanning is unsupported |
|
200 * KErrGeneral if there is a hardware error |
|
201 * KErrNotReady if FM Tx is not enabled |
|
202 */ |
|
203 virtual void GetNextClearFrequencyL(TClearFrequencyArray& aClearFrequencyArray, TUint& aCount) = 0; |
|
204 |
|
205 /** |
|
206 * The GetNextClearFrequency method requests a new clear frequency |
|
207 * suggestion. This results in a RSSI scan at the hardware level, |
|
208 * starting from the frequency increment after the previous suggested |
|
209 * clear frequency. This is an asynchronous method. |
|
210 * |
|
211 * @param aStatus This will be completed when a clear frequency is found |
|
212 * @param aClearFrequency The clear frequency is returned in this parameter, |
|
213 * which is only valid when aStatus == KErrNone. |
|
214 */ |
|
215 virtual void GetNextClearFrequency(TRequestStatus& aStatus, TInt& aClearFrequency) = 0; |
|
216 |
|
217 /** |
|
218 * The GetNextClearFrequency method requests a new clear frequency |
|
219 * suggestion. This results in a RSSI scan at the hardware level, |
|
220 * starting from the frequency increment after the previous suggested |
|
221 * clear frequency. This is an asynchronous method. |
|
222 * |
|
223 * @param aStatus This will be completed when a clear frequency is found |
|
224 * @param aClearFrequencyArray On return, this contains 0-KClearFrequencyArrayMax |
|
225 * clear frequencies. |
|
226 * @param aCount The number of clear frequencies requested (1-KClearFrequencyArrayMax). |
|
227 * On completion, this is set to the actual number of clear frequencies found. |
|
228 * @exception KErrArgument if aCount is out of range |
|
229 */ |
|
230 virtual void GetNextClearFrequencyL(TRequestStatus& aStatus, TClearFrequencyArray& aClearFrequencyArray, TUint& aCount) = 0; |
|
231 |
|
232 /** |
|
233 * The CancelGetNextClearFrequency method cancels any outstanding |
|
234 * GetNextClearFrequency requests. If no requests have been made, |
|
235 * then this has no effect. Note that the request may complete, |
|
236 * before it can be cancelled. |
|
237 */ |
|
238 virtual void CancelGetNextClearFrequency() = 0; |
|
239 |
|
240 /** |
|
241 * The SetNextClearFrequency method sets the FM Tx frequency to a |
|
242 * new clear frequency suggested. This is equivalent to calling |
|
243 * SetFrequencyL, with a result returned from GetNextClearFrequency. |
|
244 * This is a synchronous method that will block the client application. |
|
245 * |
|
246 * @param aClearFrequency On return, this is set to the new Tx frequency. |
|
247 * @exception KErrInUse if reserved by another client. |
|
248 * KErrNotSupported if RSSI scanning is unsupported |
|
249 * KErrGeneral if there is a hardware error. |
|
250 * KErrNotReady if FM Tx is not enabled |
|
251 */ |
|
252 virtual void SetNextClearFrequencyL(TInt& aClearFrequency) = 0; |
|
253 |
|
254 /** |
|
255 * The SetNextClearFrequency method sets the FM Tx frequency to a |
|
256 * new clear frequency suggested. This is equivalent to calling |
|
257 * SetFrequencyL, with a result returned from GetNextClearFrequency. |
|
258 * This is an asynchronous method. |
|
259 * |
|
260 * @param aStatus This will be completed when a clear frequency is found |
|
261 * @param aClearFrequency The clear frequency is returned in this parameter, |
|
262 * which is only valid when aStatus == KErrNone. |
|
263 */ |
|
264 virtual void SetNextClearFrequency(TRequestStatus& aStatus, TInt& aClearFrequency) = 0; |
|
265 |
|
266 /** |
|
267 * The CancelSetNextClearFrequency method cancels any outstanding |
|
268 * SetNextClearFrequency requests. If no requests have been made, |
|
269 * then this has no effect. Note that the request may complete, |
|
270 * before it can be cancelled. |
|
271 */ |
|
272 virtual void CancelSetNextClearFrequency() = 0; |
|
273 |
|
274 /** |
|
275 * The IsAutoFrequencyEnabled method queries whether auto frequency |
|
276 * mode is enabled. |
|
277 * |
|
278 * @return TBool ETrue if auto frequency is enabled. |
|
279 */ |
|
280 virtual TBool IsAutoFrequencyEnabled() = 0; |
|
281 |
|
282 /** |
|
283 * The EnableAutoFrequency method enables the FM Tx automatic frequency |
|
284 * tuning mode. In this mode, the transmitter will continuously scan |
|
285 * for interference from other transmitters. When interference is detected, |
|
286 * the FM Tx frequency will change automatically, resulting in a |
|
287 * MHWRMFmTxObserver::FmTxFrequencyChanged indication. |
|
288 * |
|
289 * @exception KErrInUse if reserved by another client. |
|
290 * KErrNotSupported if auto frequency is unsupported |
|
291 * KErrGeneral if there is a hardware error. |
|
292 * KErrNotReady if FM Tx is not enabled |
|
293 */ |
|
294 virtual void EnableAutoFrequencyL() = 0; |
|
295 |
|
296 /** |
|
297 * The DisableAutoFrequency method disables the FM Tx automatic frequency |
|
298 * tuning mode. |
|
299 * |
|
300 * @exception KErrInUse if reserved by another client. |
|
301 * KErrGeneral if there is a hardware error. |
|
302 */ |
|
303 virtual void DisableAutoFrequencyL() = 0; |
|
304 |
|
305 /** |
|
306 * The GetRdsData method Queries the current FM Tx RDS data. |
|
307 * If FM Tx is enabled, then this data is being transmitted. |
|
308 * |
|
309 * @param aData The current FM Tx RDS data. |
|
310 */ |
|
311 virtual void GetRdsData(TFmTxRdsData& aData) = 0; |
|
312 |
|
313 /** |
|
314 * The SetRdsPTY method sets the RDS Programme Type to be transmitted. |
|
315 * |
|
316 * @param aPty The new Programme Type |
|
317 * |
|
318 * @exception KErrInUse if reserved by another client. |
|
319 * KErrNotSupported if RDS is unsupported |
|
320 * KErrArgument if aPty out of range |
|
321 * KErrGeneral if there is a hardware error. |
|
322 * KErrNotReady if FM Tx is not enabled |
|
323 */ |
|
324 virtual void SetRdsPtyL(TRdsProgrammeType aPty) = 0; |
|
325 |
|
326 /** |
|
327 * The SetRdsPTYN method sets the RDS Programme Type Name to be transmitted. |
|
328 * |
|
329 * @param aPtyn The new Programme Type Name |
|
330 * |
|
331 * @exception KErrInUse if reserved by another client. |
|
332 * KErrNotSupported if RDS is unsupported |
|
333 * KErrArgument if non-latin characters are supplied or |
|
334 * programme type name too long |
|
335 * KErrGeneral if there is a hardware error. |
|
336 * KErrNotReady if FM Tx is not enabled |
|
337 */ |
|
338 virtual void SetRdsPtynL(TRdsProgrammeTypeName& aPtyn) = 0; |
|
339 |
|
340 /** |
|
341 * The SetRdsMS method sets the RDS Music/Speech flag |
|
342 * |
|
343 * @param aMusic ETrue if transmitting music. EFalse if transmitting speech. |
|
344 * |
|
345 * @exception KErrInUse if reserved by another client. |
|
346 * KErrNotSupported if RDS is unsupported |
|
347 * KErrGeneral if there is a hardware error. |
|
348 * KErrNotReady if FM Tx is not enabled |
|
349 */ |
|
350 virtual void SetRdsMsL(TBool aMusic) = 0; |
|
351 |
|
352 /** |
|
353 * The SetRdsLanguageId method sets the RDS language ID. Only relevant if MS flag |
|
354 * is set to Speech. |
|
355 * |
|
356 * @param aLanguageId The new language ID. |
|
357 * |
|
358 * @exception KErrInUse if reserved by another client. |
|
359 * KErrNotSupported if RDS is unsupported |
|
360 * KErrArgument if aLanguageId out of range |
|
361 * KErrGeneral if there is a hardware error. |
|
362 * KErrNotReady if FM Tx is not enabled |
|
363 */ |
|
364 virtual void SetRdsLanguageIdL(TRdsLanguageIdType aLanguageId) = 0; |
|
365 |
|
366 /** |
|
367 * The ClearRdsData method clears any RDS data previously set by clients. |
|
368 * This does not include Radiotext or Radiotext+ data. |
|
369 */ |
|
370 virtual void ClearRdsData() = 0; |
|
371 |
|
372 /** |
|
373 * The SetRadiotext method sets the Radiotext to be transmitted. |
|
374 * |
|
375 * @param aText The new Radiotext data. |
|
376 * |
|
377 * @exception KErrInUse if reserved by another client. |
|
378 * KErrNotSupported if Radiotext is unsupported |
|
379 * KErrArgument if non-latin characters are supplied |
|
380 * KErrGeneral if there is a hardware error. |
|
381 * KErrNotReady if FM Tx is not enabled |
|
382 */ |
|
383 virtual void SetRadiotextL(TDes& aText) = 0; |
|
384 |
|
385 /** |
|
386 * The SetRadiotextPlus method sets the Radiotext+ to be transmitted. |
|
387 * |
|
388 * @param aText The new Radiotext+ data. |
|
389 * @param aTag The Radiotext+ content type. |
|
390 * |
|
391 * @exception KErrInUse if reserved by another client. |
|
392 * KErrNotSupported if Radiotext+ is unsupported |
|
393 * KErrArgument if non-latin characters are supplied or |
|
394 * if content type not valid. |
|
395 * KErrGeneral if there is a hardware error. |
|
396 * KErrNotReady if FM Tx is not enabled |
|
397 */ |
|
398 virtual void SetRadiotextPlusL(TDes& aText, TRtPlusContentType aContentType) = 0; |
|
399 |
|
400 /** |
|
401 * The SetRadiotextPlus method sets the Radiotext+ to be transmitted. |
|
402 * |
|
403 * @param aText The new Radiotext+ data. |
|
404 * @param aTag A Radiotext+ tag. |
|
405 * |
|
406 * @exception KErrInUse if reserved by another client. |
|
407 * KErrNotSupported if Radiotext+ is unsupported |
|
408 * KErrArgument if non-latin characters are supplied or |
|
409 * if RT-plus tag content not valid. |
|
410 * KErrGeneral if there is a hardware error. |
|
411 * KErrNotReady if FM Tx is not enabled |
|
412 */ |
|
413 virtual void SetRadiotextPlusL(TDes& aText, TRtPlusTag aTag) = 0; |
|
414 |
|
415 /** |
|
416 * The SetRadiotextPlus method sets the Radiotext+ to be transmitted. |
|
417 * |
|
418 * @param aText The new Radiotext+ data. |
|
419 * @param aTag A Radiotext+ tag. |
|
420 * @param aTag A second Radiotext+ tag. |
|
421 * |
|
422 * @exception KErrInUse if reserved by another client. |
|
423 * KErrNotSupported if Radiotext+ is unsupported |
|
424 * KErrArgument if non-latin characters are supplied or |
|
425 * if RT-plus tag content not valid. |
|
426 * KErrGeneral if there is a hardware error. |
|
427 * KErrNotReady if FM Tx is not enabled |
|
428 */ |
|
429 virtual void SetRadiotextPlusL(TDes& aText, TRtPlusTag aTag1, TRtPlusTag aTag2) = 0; |
|
430 |
|
431 /** |
|
432 * The ClearRdsData method clears any Radiotext or Radiotext+ data previously |
|
433 * set by clients. |
|
434 */ |
|
435 virtual void ClearRadiotextData() = 0; |
|
436 }; |
|
437 |
|
438 /** |
|
439 * MHWRMFmTxObserver |
|
440 * A client should derive from this abstract class, to receive FM Tx status notifications. |
|
441 * |
|
442 * @publishedPartner |
|
443 * @released |
|
444 */ |
|
445 class MHWRMFmTxObserver |
|
446 { |
|
447 public: |
|
448 |
|
449 /** |
|
450 * Called when the device FM Tx status changes. |
|
451 * |
|
452 * @param aState Indicates current FM Tx state. |
|
453 * |
|
454 * @see TFmTxState |
|
455 */ |
|
456 virtual void FmTxStatusChanged(TFmTxState aState) = 0; |
|
457 |
|
458 /** |
|
459 * Called when the device FM Tx frequency changes. |
|
460 * |
|
461 * @param aFrequency Indicates current FM Tx frequency (Hz). |
|
462 */ |
|
463 virtual void FmTxFrequencyChanged(TInt aFrequency) = 0; |
|
464 }; |
|
465 |
|
466 |
|
467 #endif // HWRMFMTX_H |
|
468 |
|
469 // End of File |