1 midiclientutility.h |
1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __MIDICLIENTUTILITY_H__ |
|
17 #define __MIDICLIENTUTILITY_H__ |
|
18 |
|
19 #include <e32std.h> |
|
20 #include <e32base.h> |
|
21 #include <bamdesca.h> |
|
22 #include <mmf/common/mmfcontroller.h> |
|
23 #include <mmf/common/mmfstandardcustomcommands.h> |
|
24 #include <mmf/common/mmfdrmcustomcommands.h> |
|
25 #include <mmf/common/mmfmididatacommon.h> |
|
26 |
|
27 |
|
28 /** |
|
29 General utility class to hold instrument information. |
|
30 |
|
31 @publishedAll |
|
32 @released |
|
33 */ |
|
34 class TInstrumentInfo |
|
35 { |
|
36 public: |
|
37 /** |
|
38 *Identifier of sound bank to reference. |
|
39 */ |
|
40 TInt iBankId; |
|
41 |
|
42 /** |
|
43 * Specifies whether to reference a custom or standard sound bank. |
|
44 */ |
|
45 TBool iCustom; |
|
46 |
|
47 /** |
|
48 * Identifier of specified instrument. |
|
49 */ |
|
50 TInt iInstrumentId; |
|
51 }; |
|
52 |
|
53 /** |
|
54 Defines the state of the MIDI client utility with regard to the MIDI resource. |
|
55 |
|
56 @publishedAll |
|
57 @released |
|
58 */ |
|
59 enum TMidiState |
|
60 { |
|
61 /** |
|
62 * No MIDI resource is currently open. |
|
63 * The MIDI engine is not processing midi events. |
|
64 */ |
|
65 EMidiStateClosedDisengaged, |
|
66 |
|
67 |
|
68 /** |
|
69 * A MIDI resource is open and primed but not playing. |
|
70 * The MIDI engine is not processing midi events. |
|
71 */ |
|
72 EMidiStateOpenDisengaged, |
|
73 |
|
74 /** |
|
75 * A MIDI resource is open and currently playing. |
|
76 * The MIDI engine is currently processing midi events. |
|
77 */ |
|
78 EMidiStateOpenPlaying, |
|
79 |
|
80 /** |
|
81 * Not able to play full SP-MIDI or DLS content, but attempting best-effort playback. |
|
82 */ |
|
83 EMidiStatePlaybackIncompatible, |
|
84 |
|
85 /** |
|
86 * Due to system resource constraints and SP-MIDI content constraints, |
|
87 * there is no audible MIDI content during playback currently. |
|
88 * The situation may change if resources are freed later. |
|
89 */ |
|
90 EMidiStatePlaybackSilent, |
|
91 |
|
92 /** |
|
93 * No MIDI resource is currently open. |
|
94 * The MIDI engine is currently processing midi events. |
|
95 */ |
|
96 EMidiStateClosedEngaged, |
|
97 |
|
98 /** |
|
99 * A MIDI resource is open and primed but not playing. |
|
100 * The MIDI engine is currently processing MIDI events. |
|
101 * The transition to this state is only possible from EMidiStateOpenPlaying state, |
|
102 * when the 'playback head' reaches the end of media data or the playback |
|
103 * stops due to stop time set. |
|
104 */ |
|
105 EMidiStateOpenEngaged, |
|
106 }; |
|
107 |
|
108 /** |
|
109 Active object utility class to allow MIDI events to be signalled asynchronously. |
|
110 @see CMidiClientUtility::NewL(). |
|
111 |
|
112 @publishedAll |
|
113 @released |
|
114 */ |
|
115 class MMidiClientUtilityObserver |
|
116 { |
|
117 public: |
|
118 /** |
|
119 A state change has occurred in the MIDI client utility. |
|
120 |
|
121 @param aOldState |
|
122 Old state. |
|
123 @param aNewState |
|
124 New state. |
|
125 @param aTime |
|
126 The time in microseconds at which playback stopped relative to the start of the MIDI resource. |
|
127 @param aError |
|
128 Error code. |
|
129 */ |
|
130 virtual void MmcuoStateChanged(TMidiState aOldState,TMidiState aNewState,const TTimeIntervalMicroSeconds& aTime,TInt aError) = 0; |
|
131 /** |
|
132 The MIDI resource has encountered a tempo change message in the MIDI data stream. |
|
133 |
|
134 @param aMicroBeatsPerMinute |
|
135 New tempo value in micro beats per minute (BPM*1000000). |
|
136 */ |
|
137 virtual void MmcuoTempoChanged(TInt aMicroBeatsPerMinute) = 0; |
|
138 /** |
|
139 The MIDI resource has encountered a volume change message in the MIDI data stream. |
|
140 |
|
141 @param aChannel |
|
142 Logical channel to which the message applies. 0 <= aChannel < ChannelsSupportedL(). |
|
143 @param aVolumeInDecibels |
|
144 New volume setting being used. |
|
145 */ |
|
146 virtual void MmcuoVolumeChanged(TInt aChannel,TReal32 aVolumeInDecibels) = 0; |
|
147 /** |
|
148 The MIDI resource has encountered a mute message in the MIDI data stream. |
|
149 |
|
150 @param aChannel |
|
151 Logical channel to which the message applies. 0 <= aChannel < ChannelsSupportedL(). |
|
152 @param aMuted |
|
153 New muting state of the channel - ETrue is muted, EFalse is unmuted. |
|
154 */ |
|
155 virtual void MmcuoMuteChanged(TInt aChannel,TBool aMuted) = 0; |
|
156 /** |
|
157 Callback in response to a call to CMIDIClientUtility::SetSyncUpdateCallbackIntervalL(). |
|
158 By default there are no callbacks. Otherwise the callback is called at an interval set by the client. |
|
159 |
|
160 @param aMicroSeconds |
|
161 Position in microseconds relative to the start of the resource - only set if |
|
162 the sync update set function was called with the microseconds parameter set. |
|
163 @param aMicroBeats |
|
164 Position in microbeats relative to the start of the resource - only set if |
|
165 the sync update set function was called with the microbeats parameter set and |
|
166 the microseconds parameter set to 0. |
|
167 */ |
|
168 virtual void MmcuoSyncUpdate(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats) = 0; |
|
169 /** |
|
170 A timed meta data entry has been found in the MIDI data stream, eg a timed song lyric in an SMF file. |
|
171 |
|
172 @param aMetaDataEntryId |
|
173 Index of the meta data entry - if this entry has not been encountere before, |
|
174 it will be added to the list of meta data entries. Previously encountered timed |
|
175 entries still generate this callback. |
|
176 @param aPosition |
|
177 Position in microseconds relative to the start of the MIDI resource that the MIDI |
|
178 meta data entry was found at. |
|
179 */ |
|
180 virtual void MmcuoMetaDataEntryFound(const TInt aMetaDataEntryId,const TTimeIntervalMicroSeconds& aPosition) = 0; |
|
181 /** |
|
182 A MIP message has been found in the MIDI data stream. |
|
183 |
|
184 @param aMessage |
|
185 Reference to an array of MIP message entries (logical {channel, MIP} value pairs) |
|
186 contained in the message. |
|
187 */ |
|
188 virtual void MmcuoMipMessageReceived(const RArray<TMipMessageEntry>& aMessage) = 0; |
|
189 /** |
|
190 The polyphony of the MIDI engine has changed. |
|
191 |
|
192 @param aNewPolyphony |
|
193 The new polyphony value. |
|
194 */ |
|
195 virtual void MmcuoPolyphonyChanged(TInt aNewPolyphony) = 0; |
|
196 /** |
|
197 An instrument has been changed on a channel. |
|
198 |
|
199 @param aChannel |
|
200 Channel where the change of instrument occurred. 0 <= aChannel < ChannelsSupportedL(). |
|
201 @param aBankId |
|
202 Identifier of the bank that the instrument belongs to, occupying no more than 14 bits. |
|
203 The bank ID is a concatenation of MIDI bank MSB and LSB values. |
|
204 @param aInstrumentId |
|
205 Identifier of the instrument that has been changed. 0 <= aInstrumentId <= 127. |
|
206 */ |
|
207 virtual void MmcuoInstrumentChanged(TInt aChannel,TInt aBankId,TInt aInstrumentId) = 0; |
|
208 }; |
|
209 |
|
210 |
|
211 /** |
|
212 Utility class to provide a standard client interface to a MIDI controller. |
|
213 |
|
214 @publishedAll |
|
215 @released |
|
216 */ |
|
217 class CMidiClientUtility : public CBase |
|
218 { |
|
219 class CBody; |
|
220 public: |
|
221 IMPORT_C static CMidiClientUtility* NewL(MMidiClientUtilityObserver& aObserver, |
|
222 TInt aPriority = EMdaPriorityNormal, |
|
223 TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality); |
|
224 |
|
225 // alternative NewL for selecting shared/separate controller heap(s) |
|
226 IMPORT_C static CMidiClientUtility* NewL(MMidiClientUtilityObserver& aObserver, |
|
227 TInt aPriority, |
|
228 TMdaPriorityPreference aPref, |
|
229 TBool aUseSharedHeap); |
|
230 |
|
231 /** Destructor */ |
|
232 virtual ~CMidiClientUtility(); |
|
233 IMPORT_C TMidiState State() const; |
|
234 IMPORT_C void OpenFile(const TDesC& aFileName); |
|
235 IMPORT_C void OpenFile(const RFile& aFile); |
|
236 |
|
237 IMPORT_C void OpenFile(const TMMSource& aSource); |
|
238 |
|
239 IMPORT_C void OpenDes(const TDesC8& aDescriptor); |
|
240 IMPORT_C void OpenUrl(const TDesC& aUrl,TInt aIapId = KUseDefaultIap,const TDesC8& aMimeType=KNullDesC8); |
|
241 IMPORT_C void Close(); |
|
242 IMPORT_C void Play(); |
|
243 IMPORT_C void Stop(const TTimeIntervalMicroSeconds& aFadeOutDuration); |
|
244 IMPORT_C void PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity); |
|
245 IMPORT_C void PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity); |
|
246 IMPORT_C void StopNotes(TInt aChannel); |
|
247 IMPORT_C void NoteOnL(TInt aChannel,TInt aNote,TInt aVelocity); |
|
248 IMPORT_C void NoteOffL(TInt aChannel,TInt aNote,TInt aVelocity); |
|
249 IMPORT_C TInt PlaybackRateL() const; |
|
250 IMPORT_C void SetPlaybackRateL(TInt aRate); |
|
251 IMPORT_C TInt MaxPlaybackRateL() const; |
|
252 IMPORT_C TInt MinPlaybackRateL() const; |
|
253 IMPORT_C TInt TempoMicroBeatsPerMinuteL() const; |
|
254 IMPORT_C void SetTempoL(TInt aMicroBeatsPerMinute); |
|
255 IMPORT_C TInt PitchTranspositionCentsL() const; |
|
256 IMPORT_C TInt SetPitchTranspositionL(TInt aCents); |
|
257 IMPORT_C TTimeIntervalMicroSeconds DurationMicroSecondsL() const; |
|
258 IMPORT_C TInt64 DurationMicroBeatsL() const; |
|
259 IMPORT_C TInt NumTracksL() const; |
|
260 IMPORT_C void SetTrackMuteL(TInt aTrack,TBool aMuted) const; |
|
261 IMPORT_C const TDesC8& MimeTypeL(); |
|
262 IMPORT_C TTimeIntervalMicroSeconds PositionMicroSecondsL() const; |
|
263 IMPORT_C void SetPositionMicroSecondsL(const TTimeIntervalMicroSeconds& aPosition); |
|
264 IMPORT_C TInt64 PositionMicroBeatsL() const; |
|
265 IMPORT_C void SetPositionMicroBeatsL(TInt64 aMicroBeats); |
|
266 IMPORT_C void SetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds& aMicroSeconds, TInt64 aMicroBeats=0); |
|
267 IMPORT_C TInt SendMessageL(const TDesC8& aMidiMessage); |
|
268 IMPORT_C TInt SendMessageL(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime); |
|
269 IMPORT_C void SendMipMessageL(const RArray<TMipMessageEntry>& aEntry); |
|
270 IMPORT_C TInt NumberOfBanksL(TBool aCustom) const; |
|
271 IMPORT_C TInt GetBankIdL(TBool aCustom,TInt aBankIndex) const; |
|
272 IMPORT_C void LoadCustomBankL(const TDesC& aFileName,TInt& aBankCollectionIndex); |
|
273 IMPORT_C void LoadCustomBankDataL(const TDesC8& aBankData,TInt& aBankCollectionIndex); |
|
274 IMPORT_C void UnloadCustomBankL(TInt aBankCollectionIndex); |
|
275 IMPORT_C TBool CustomBankLoadedL(TInt aBankCollectionIndex) const; |
|
276 IMPORT_C void UnloadAllCustomBanksL(); |
|
277 IMPORT_C TInt NumberOfInstrumentsL(TInt aBankId,TBool aCustom) const; |
|
278 IMPORT_C TInt GetInstrumentIdL(TInt aBankId,TBool aCustom,TInt aInstrumentIndex) const; |
|
279 IMPORT_C HBufC* InstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) const; |
|
280 IMPORT_C void GetInstrumentL(TInt aChannel, TInt& aInstrumentId, TInt& aBankId); |
|
281 IMPORT_C void SetInstrumentL(TInt aChannel,TInt aBankId,TInt aInstrumentId); |
|
282 IMPORT_C void LoadCustomInstrumentL(const TDesC& aFileName,TInt aFileBankId,TInt aFileInstrumentId,TInt aMemoryBankId,TInt aMemoryInstrumentId); |
|
283 IMPORT_C void LoadCustomInstrumentDataL(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId); |
|
284 IMPORT_C void UnloadCustomInstrumentL(TInt aCustomBankId,TInt aInstrumentId); |
|
285 IMPORT_C HBufC* PercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) const; |
|
286 IMPORT_C void StopTimeL(TTimeIntervalMicroSeconds& aStopTime) const; |
|
287 IMPORT_C void SetStopTimeL(const TTimeIntervalMicroSeconds& aStopTime); |
|
288 IMPORT_C void SetRepeatsL(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence); |
|
289 IMPORT_C TInt GetRepeats() const; |
|
290 IMPORT_C TInt PolyphonyL() const; |
|
291 IMPORT_C void SetMaxPolyphonyL(TInt aMaxNotes); |
|
292 IMPORT_C TInt ChannelsSupportedL() const; |
|
293 IMPORT_C TReal32 ChannelVolumeL(TInt aChannel) const; |
|
294 IMPORT_C TReal32 MaxChannelVolumeL() const; |
|
295 IMPORT_C void SetChannelVolumeL(TInt aChannel,TReal32 aVolumeInDecibels); |
|
296 IMPORT_C void SetChannelMuteL(TInt aChannel,TBool aMuted); |
|
297 IMPORT_C TInt VolumeL() const; |
|
298 IMPORT_C TInt MaxVolumeL() const; |
|
299 IMPORT_C void SetVolumeL(TInt aVolume); |
|
300 IMPORT_C void SetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration); |
|
301 IMPORT_C TInt GetBalanceL() const; |
|
302 IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter); |
|
303 IMPORT_C void SetPriorityL(TInt aPriority, TMdaPriorityPreference aPref); |
|
304 IMPORT_C TInt NumberOfMetaDataEntriesL() const; |
|
305 IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aMetaDataIndex) const; |
|
306 /** |
|
307 * @deprecated SetBankL is deprecated due to Mobile XMF specification requirement that user instruments (custom instruments) override standard instruments. |
|
308 */ |
|
309 IMPORT_C void SetBankL(TBool aCustom); |
|
310 IMPORT_C TBool IsTrackMuteL(TInt aTrack) const; |
|
311 IMPORT_C TBool IsChannelMuteL(TInt aChannel) const; |
|
312 IMPORT_C void CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom); |
|
313 IMPORT_C void CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2); |
|
314 IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus); |
|
315 IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus); |
|
316 IMPORT_C TInt MaxPolyphonyL() const; |
|
317 |
|
318 IMPORT_C MMMFDRMCustomCommand* GetDRMCustomCommand(); |
|
319 |
|
320 private: |
|
321 /** |
|
322 * a pointer to the implementation. |
|
323 */ |
|
324 CBody* iBody; |
|
325 friend class CBody; |
|
326 }; |
|
327 |
|
328 #endif |