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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __MIDISTANDARDCUSTOMCOMMANDS_H__
17 #define __MIDISTANDARDCUSTOMCOMMANDS_H__
19 #include <mmf/common/mmfcontroller.h>
20 #include <midiclientutility.h>
21 #include <mmf/common/mmfmidi.h>
24 Interface UID for the Midi Controller API.
29 const TUid KUidInterfaceMidi = { 0x101F945C };
32 Describe a MIDI event.
33 Contains a UID to define the actual event type, and an integer to define the event code.
38 class CMMFMidiEvent: public CBase
41 IMPORT_C CMMFMidiEvent(TUid aEventType, TInt aErrorCode);
42 IMPORT_C CMMFMidiEvent();
43 IMPORT_C ~CMMFMidiEvent();
44 IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
45 IMPORT_C void InternalizeL(RReadStream& aStream);
46 IMPORT_C void CopyL(const CMMFMidiEvent& aOther);
53 * A UID to define the type of MIDI event.
57 * The error code associated with the MIDI event.
61 * Old state of the MIDI client utility object.
65 * Current state of the MIDI client utility object.
69 * General purpose time stamp in microseconds.
71 TTimeIntervalMicroSeconds iMicroSeconds;
73 * General purpose time stamp in micro beats per minute.
81 * Volume in decibel of a logical channel.
83 TReal32 iVolumeInDecibels;
85 * Mute state of a track or of a channel.
90 * Client will retrieve meta data entry by calling GetMetaDataEntryL()
91 * using this TInt to indicate which meta data entry to retrieve.
93 TInt iMetaDataEntryId;
95 * Array of logical {channel, MIP} value pairs.
97 RArray<TMipMessageEntry> iMipMessage;
99 * Polyphony of the MIDI engine.
103 * Identifier of a bank occupying, at most, 14 bits.
107 * Identifier of a specific instrument.
111 * Tempo value in micro beats per minute.
113 TInt iTempoMicroBeats;
119 enum TMMFMidiControllerMessages
121 EMMFMidiControllerSetPositionMicroBeats,
122 EMMFMidiControllerPositionMicroBeats,
123 EMMFMidiControllerPlayNote,
124 EMMFMidiControllerPlayNoteWithStartTime,
125 EMMFMidiControllerStopNotes,
126 EMMFMidiControllerNoteOn,
127 EMMFMidiControllerNoteOff,
128 EMMFMidiControllerPlaybackRate,
129 EMMFMidiControllerSetPlaybackRate,
130 EMMFMidiControllerMaxPlaybackRate,
131 EMMFMidiControllerMinPlaybackRate,
132 EMMFMidiControllerTempo,
133 EMMFMidiControllerSetTempo,
134 EMMFMidiControllerPitch,
135 EMMFMidiControllerSetPitch,
136 EMMFMidiControllerDurationMicroBeats,
137 EMMFMidiControllerNumTracks,
138 EMMFMidiControllerSetTrackMute,
139 EMMFMidiControllerMimeType,
140 EMMFMidiControllerSetSyncUpdateCallbackInterval,
141 EMMFMidiControllerSendMessage,
142 EMMFMidiControllerSendMessageWithTimeStamp,
143 EMMFMidiControllerSendMipMessage,
144 EMMFMidiControllerNumberOfBanks,
145 EMMFMidiControllerGetBankId,
146 EMMFMidiControllerLoadCustomBank,
147 EMMFMidiControllerLoadCustomBankData,
148 EMMFMidiControllerUnloadCustomBank,
149 EMMFMidiControllerCustomBankLoaded,
150 EMMFMidiControllerUnloadAllCustomBanks,
151 EMMFMidiControllerNumberOfInstruments,
152 EMMFMidiControllerGetInstrumentId,
153 EMMFMidiControllerInstrumentName,
154 EMMFMidiControllerCopyInstrumentName,
155 EMMFMidiControllerSetInstrument,
156 EMMFMidiControllerLoadCustomInstrument,
157 EMMFMidiControllerLoadCustomInstrumentData,
158 EMMFMidiControllerUnloadCustomInstrument,
159 EMMFMidiControllerPercussionKeyName,
160 EMMFMidiControllerCopyPercussionKeyName,
161 EMMFMidiControllerSetStopTime,
162 EMMFMidiControllerStopTime,
163 EMMFMidiControllerPolyphony,
164 EMMFMidiControllerSetMaxPolyphony,
165 EMMFMidiControllerChannelsSupported,
166 EMMFMidiControllerChannelVolume,
167 EMMFMidiControllerMaxChannelVolume,
168 EMMFMidiControllerSetChannelVolume,
169 EMMFMidiControllerSetChannelMute,
170 EMMFMidiControllerVolume,
171 EMMFMidiControllerMaxVolume,
172 EMMFMidiControllerSetVolume,
173 EMMFMidiControllerSetVolumeRamp,
174 EMMFMidiControllerGetBalance,
175 EMMFMidiControllerSetBalance,
176 EMMFMidiControllerGetRepeats,
177 EMMFMidiControllerSetRepeats,
178 EMMFMidiControllerSetBank,
179 EMMFMidiControllerIsTrackMute,
180 EMMFMidiControllerIsChannelMute,
181 EMMFMidiControllerGetInstrument,
182 EMMFMidiControllerClose,
183 EMMFMidiControllerStop,
184 EMMFMidiControllerReceiveEvents,
185 EMMFMidiControllerRetrieveEvent,
186 EMMFMidiControllerCancelReceiveEvents,
187 EMMFMidiControllerMaxPolyphony
191 Client class to access functionality specific to a MIDI controller.
192 The class uses the custom command function of the controller plugin, and removes the necessity
193 for the client to formulate the custom commands.
198 class RMidiControllerCustomCommands : public RMMFCustomCommandsBase
201 IMPORT_C RMidiControllerCustomCommands(RMMFController& aController);
202 IMPORT_C TInt SetPositionMicroBeats(TInt64 aMicroBeats) const;
203 IMPORT_C TInt PositionMicroBeats(TInt64& aMicroBeats) const;
204 IMPORT_C TInt PlayNote(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);
205 IMPORT_C TInt PlayNote(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime, const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);
206 IMPORT_C TInt StopNotes(TInt aChannel);
207 IMPORT_C TInt NoteOn(TInt aChannel,TInt aNote,TInt aVelocity);
208 IMPORT_C TInt NoteOff(TInt aChannel,TInt aNote,TInt aVelocity);
209 IMPORT_C TInt PlaybackRate(TInt& aPlayBackRate) const;
210 IMPORT_C TInt SetPlaybackRate(TInt aPlayBackRate);
211 IMPORT_C TInt MaxPlaybackRate(TInt& aMaxRate) const;
212 IMPORT_C TInt MinPlaybackRate(TInt& aMinRate) const;
213 IMPORT_C TInt TempoMicroBeatsPerMinute(TInt& aMicroBeatsPerMinute) const;
214 IMPORT_C TInt SetTempo(TInt aMicroBeatsPerMinute);
215 IMPORT_C TInt PitchTranspositionCents(TInt& aPitch) const;
216 IMPORT_C TInt SetPitchTransposition(TInt aCents, TInt& aCentsApplied);
217 IMPORT_C TInt DurationMicroBeats(TInt64& aDuration) const;
218 IMPORT_C TInt NumTracks(TInt& aTracks) const;
219 IMPORT_C TInt SetTrackMute(TInt aTrack, TBool aMuted) const;
220 IMPORT_C TInt MimeType(TDes8& aMimeType) const;
221 IMPORT_C TInt SetSyncUpdateCallbackInterval(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats=0);
222 IMPORT_C TInt SendMessage(const TDesC8& aMidiMessage, TInt& aBytes);
223 IMPORT_C TInt SendMessage(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime, TInt& aBytes);
224 IMPORT_C TInt SendMipMessage(const RArray<TMipMessageEntry>& aEntry);
225 IMPORT_C TInt NumberOfBanks(TBool aCustom, TInt& aNumBanks) const;
226 IMPORT_C TInt GetBankId(TBool aCustom, TInt aBankIndex, TInt& aBankId) const;
227 IMPORT_C TInt LoadCustomBank(const TDesC& aFileName,TInt& aBankId);
228 IMPORT_C TInt LoadCustomBankData(const TDesC8& aBankData,TInt& aBankId);
229 IMPORT_C TInt UnloadCustomBank(TInt aBankId);
230 IMPORT_C TInt CustomBankLoaded(TInt aBankId, TBool& aBankLoaded) const;
231 IMPORT_C TInt UnloadAllCustomBanks();
232 IMPORT_C TInt NumberOfInstruments(TInt aBankId, TBool aCustom, TInt& aNumInstruments) const;
233 IMPORT_C TInt GetInstrumentId(TInt aBankId,TBool aCustom,TInt aInstrumentIndex, TInt& aInstrumentId) const;
234 IMPORT_C HBufC* InstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) const;
235 IMPORT_C TInt SetInstrument(TInt aChannel,TInt aBankId,TInt aInstrumentId);
236 IMPORT_C TInt LoadCustomInstrument(const TDesC& aFileName, TInt aFileBankId, TInt aFileInstrumentId, TInt aMemoryBankId, TInt aMemoryInstrumentId);
237 IMPORT_C TInt LoadCustomInstrumentData(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId);
238 IMPORT_C TInt UnloadCustomInstrument(TInt aCustomBankId,TInt aInstrumentId);
239 IMPORT_C HBufC* PercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) const;
240 IMPORT_C TInt StopTime(TTimeIntervalMicroSeconds& aStopTime) const;
241 IMPORT_C TInt SetStopTime(const TTimeIntervalMicroSeconds& aStopTime) const;
242 IMPORT_C TInt Polyphony(TInt& aNumNotes) const;
243 IMPORT_C TInt ChannelsSupported(TInt& aChannels) const;
244 IMPORT_C TInt ChannelVolume(TInt aChannel, TReal32& aChannelVol) const;
245 IMPORT_C TInt MaxChannelVolume(TReal32& aMaxVol) const;
246 IMPORT_C TInt SetChannelVolume(TInt aChannel,TReal32 aVolume);
247 IMPORT_C TInt SetChannelMute(TInt aChannel,TBool aMuted);
248 IMPORT_C TInt Volume(TInt& aVolume) const;
249 IMPORT_C TInt MaxVolume(TInt& aMaxVolume) const;
250 IMPORT_C TInt SetVolume(TInt aVolume);
251 IMPORT_C TInt SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);
252 IMPORT_C TInt GetBalance(TInt& aBalance) const;
253 IMPORT_C TInt SetBalance(TInt aBalance);
254 IMPORT_C TInt SetMaxPolyphony(TInt aMaxNotes);
255 IMPORT_C TInt GetRepeats(TInt& aNumRepeats) const;
256 IMPORT_C TInt SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence);
257 IMPORT_C TInt SetBank(TBool aCustom);
258 IMPORT_C TInt IsTrackMute(TInt aTrack, TBool& aTrackMute) const;
259 IMPORT_C TInt IsChannelMute(TInt aChannel, TBool& aChannelMute) const;
260 IMPORT_C TInt GetInstrument(TInt aChannel, TInt& aInstrumentId, TInt& aBankId);
261 IMPORT_C TInt Close();
262 IMPORT_C TInt Stop(const TTimeIntervalMicroSeconds& aFadeOutDuration);
263 IMPORT_C void ReceiveEvents(TPckgBuf<TInt>& aEventSize, TRequestStatus& aStatus);
264 IMPORT_C TInt RetrieveEvent(TDes8& aMidiEventPckg);
265 IMPORT_C TInt CancelReceiveEvents();
266 IMPORT_C TInt MaxPolyphony(TInt& aNumNotes) const;
271 Mixin class to be derived from by controller plugins wishing
272 to support the MIDI controller custom commands.
277 class MMidiCustomCommandImplementor
281 Change the position of the currently playing MIDI resource to the given position.
282 May be called whenever a MIDI resource is open.
285 Metrical position to move to. Clamped to (0, DurationMicroBeats()).
287 virtual void MmcSetPositionMicroBeatsL(TInt64 aMicroBeats) = 0;
289 Gets the current metrical position of the MIDI resource being played
292 (BPM*1000000) relative to the start of the resource
294 virtual void MmcPositionMicroBeatsL(TInt64& aMicroBeats) = 0;
296 Synchronous function to play a single note.
297 Multiple calls to this function will be accommodated as far as the MIDI engine can
298 manage. The same functionality could be implemented using the SendMessage function
301 Logical channel to play note on. 0 <= aChannel <= 15.
303 Note to play. 0 <= aNote <= 127
305 Length of time to play note for.
306 @param aNoteOnVelocity
307 Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.
308 @param aNoteOffVelocity
309 Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.
311 virtual void MmcPlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity) = 0;
313 Synchronous function to play a single note at a specified time.
314 Multiple calls to this function will be accommodated as far as the MIDI engine can
315 manage. The same functionality could be implemented using the SendMessage function
318 Logical channel to play note on. 0 <= aChannel <= 15.
320 Note to play. 0 <= aNote <= 127
322 Specifies the time at which to start playing the note, relative to the MIDI
323 resource playing time or the time elapsed since Play() was called if no resource is present.
325 Length of time to play note for.
326 @param aNoteOnVelocity
327 Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.
328 @param aNoteOffVelocity
329 Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.
331 virtual void MmcPlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime, const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity) = 0;
333 Stops the playback of all notes on the given channel,
334 by means of an All Notes Off MIDI message
337 Logical channel to stop notes on. 0 <= aChannel <= 15
339 virtual void MmcStopNotesL(TInt aChannel) = 0;
341 Synchronous function to commence playback of a note.
342 Multiple calls to this function will be accommodated as far as the MIDI engine can manage
345 Logical channel to play note on. 0 <= aChannel <= 15.
347 Note to play. 0 <= aNote <= 127.
349 Velocity with which to start the note. The legal integer range
350 is 0 <= aVelocity <= 127, but the value zero actually causes the
351 message to be interpreted as a Note Off message instead of a Note On.
353 virtual void MmcNoteOnL(TInt aChannel,TInt aNote,TInt aVelocity) = 0;
355 Synchronous function to terminate playback of a note.
356 If no corresponding note is found then no error is raised
359 Logical channel on which the note is playing. 0 <= aChannel <= 15.
361 Note to terminate. 0 <= aNote <= 127.
363 Velocity with which to stop the note. 0 <= aVelocity <= 127.
364 There is no standard behaviour corresponding with note off velocity.
366 virtual void MmcNoteOffL(TInt aChannel,TInt aNote,TInt aVelocity) = 0;
368 Gets the current playback rate factor of the currently open MIDI resource.
369 The playback rate is independent from tempo,
370 i.e., it can be used to give an overall speed factor for playback.
373 Current playback rate in percent times 1000, i.e., 100000 means original
374 playback speed, 200000 means double speed, and 50000 means half speed playback.
376 virtual void MmcPlaybackRateL(TInt& aPlayBackRate) = 0;
378 Sets the playback rate for the playback of the current MIDI resource.
379 The playback rate is independent from tempo,
380 i.e., it can be used to give an overall speed factor for playback.
381 May be called whether playback is in progress or not.
384 Playback rate in percent times 1000, i.e., 100000 means original playback speed,
385 200000 means double speed, and 50000 means half speed playback.
387 virtual void MmcSetPlaybackRateL(TInt aPlayBackRate) = 0;
389 Gets the maximum playback rate in milli-percentage from the MIDI engine.
390 @see SetPlaybackRate() for milli-percentage details.
393 Playback rate supported by MIDI player.
395 virtual void MmcMaxPlaybackRateL(TInt& aMaxRate) = 0;
397 Gets the minimum playback rate in milli-percentage from the MIDI engine.
398 @see SetPlaybackRate() for milli-percentage details.
401 Minimum playback rate supported by MIDI player.
403 virtual void MmcMinPlaybackRateL(TInt& aMinRate) = 0;
405 Gets the current tempo of the currently open MIDI resource. The tempo is independent
406 from the playback rate, i.e., the resulting playback speed will be affected by both.
408 @param aMicroBeatsPerMinute
409 Tempo at the current position of the currently open resource in microbeats
410 per minute, i.e. BPM * 1000000. Filled in by the controller framework.
412 virtual void MmcTempoMicroBeatsPerMinuteL(TInt& aMicroBeatsPerMinute) = 0;
414 Sets the tempo at which the current MIDI resource should be played.
415 May be called whether playback is in progress or not. The tempo is
416 independent from the playback rate, i.e., the resulting playback speed
417 will be affected by both.
419 @param aMicroBeatsPerMinute
420 Tempo in microbeats per minute (BPM*1000000) to set.
422 virtual void MmcSetTempoL(TInt aMicroBeatsPerMinute) = 0;
424 Gets the pitch shift in use for the currently open MIDI resource.
427 Shift in cents, i.e. semitones * 100. One octave equals 1200 cents.
428 @return One of the system-wide error codes.
430 virtual void MmcPitchTranspositionCentsL(TInt& aPitch) = 0;
432 Sets the pitch shift to apply to the currently open MIDI resource.
433 May be called during playback.
436 Pitch shift in cents, i.e. semitones * 100. One octave equals 1200 cents.
438 Actual pitch shift applied - may differ from the requested value due
439 to limitations of the MIDI engine.
441 virtual void MmcSetPitchTranspositionL(TInt aCents, TInt& aCentsApplied) = 0;
443 Gets the length of the currently open MIDI resource in micro-beats
446 Duration in microbeats (beats * 1000000).
448 virtual void MmcDurationMicroBeatsL(TInt64& aDuration) = 0;
450 Gets the number of tracks present in the currently open MIDI resource.
455 virtual void MmcNumTracksL(TInt& aTracks) = 0;
457 Mutes or unmutes a particular track.
460 Index of the track to mute - 0 <= aTrack < NumTracks().
462 ETrue to mute the track, EFalse to unmute it.
464 virtual void MmcSetTrackMuteL(TInt aTrack, TBool aMuted) = 0;
466 Gets the MIME type of the MIDI resource currently open.
469 Descriptor containing the MIDI mime type.
471 virtual void MmcMimeTypeL(TDes8& aMimeType) = 0;
473 Sets the frequency at which MMIDIClientUtilityObserver::MmcuoSyncUpdateL() is called
474 to allow other components to synchronise with playback of this MIDI resource.
477 Temporal interval to callback at. Used in preference to aMicroBeats if both are set.
479 Metrical interval to callback at. Set both parameters to zero to cancel.
481 virtual void MmcSetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats=0) = 0;
483 Sends a single MIDI message to the MIDI engine.
486 Descriptor containing the MIDI message data. If there are several
487 MIDI messages in the buffer, only the first one is processed.
489 Number of bytes of the message buffer actually processed.
491 virtual void MmcSendMessageL(const TDesC8& aMidiMessage, TInt& aBytes) = 0;
493 Sends a single MIDI message, with time stamp, to the MIDI engine.
496 Descriptor containing the MIDI message data. If there are several
497 MIDI messages in the buffer, only the first one is processed.
499 The time at which to execute the message, relative to the MIDI resource playing
500 time or the time elapsed since Play() was called if no resource is present.
502 Number of bytes of the message buffer actually processed.
504 virtual void MmcSendMessageL(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime, TInt& aBytes) = 0;
506 Sends a mip message to the MIDI engine. This is a convenience function,
507 because the same functionality could be achieved with the SendMessage() function.
510 Array of logical {channel, MIP} value pairs to send, highest priority first.
512 virtual void MmcSendMipMessageL(const TArray<TMipMessageEntry>& aEntry) = 0;
514 Gets the number of standard or custom sound banks currently available.
517 Specifies whether to reference a custom or standard sound bank.
519 Number of custom or standard sound banks available.
521 virtual void MmcNumberOfBanksL(TBool aCustom, TInt& aNumBanks) = 0;
523 Gets the identifier of a sound bank. Bank identifier (aka bank number) is a
524 14-bit value consisting of MIDI bank MSB and LSB values.
527 Specifies whether to reference a custom or standard sound bank.
529 Index of sound bank where 0 <= aBankIndex < NumberOfBanks().
531 Identifier of the specified bank occupying, at most, 14 bits.
533 virtual void MmcGetBankIdL(TBool aCustom, TInt aBankIndex, TInt& aBankId) = 0;
535 Loads one or more custom sound banks from a file into memory for use.
536 If several banks are loaded with consequent LoadCustomBanksL() function calls,
537 the banks are combined if the bank sets have conflicting bank numbers.
540 Name of the file containing the custom sound bank.
542 Identifier of the custom sound bank loaded, occupying no more than 14 bits.
544 virtual void MmcLoadCustomBankL(const TDesC& aFileName,TInt& aBankId) = 0;
546 Loads one or more custom sound banks from a descriptor into memory for use.
547 If several banks are loaded with consequent LoadCustomBanksL() function calls,
548 the banks are combined if the bank sets have conflicting bank numbers.
551 Descriptor containing the custom sound bank.
553 Identifier of the custom sound bank loaded, occupying no more than 14 bits.
555 virtual void MmcLoadCustomBankDataL(const TDesC8& aBankData,TInt& aBankId) = 0;
557 Removes a custom sound bank from memory. Only valid for sound banks previously
558 loaded from file. Once unloaded the custom sound bank is no longer available for use.
561 Identifier of the custom sound bank to unload,occupying no more than 14 bits.
563 virtual void MmcUnloadCustomBankL(TInt aBankId) = 0;
565 Query if a bank has been loaded to the memory.
568 Identifier of the custom sound bank to check if it's in memory or not.
570 ETrue if the specified bank is in memory, EFalse otherwise.
572 virtual void MmcCustomBankLoadedL(TInt aBankId, TBool& aBankLoaded) = 0;
574 Removes all custom sound banks from memory.
576 virtual void MmcUnloadAllCustomBanksL() = 0;
578 Gets the number of instruments available in a given sound bank.
581 Identifier of sound bank to reference, occupying no more than 14 bits.
583 Specifies whether to reference a custom or standard sound bank.
584 @param aNumInstruments
585 Count of the number of instruments available for the specified sound bank.
587 virtual void MmcNumberOfInstrumentsL(TInt aBankId, TBool aCustom, TInt& aNumInstruments) = 0;
589 Gets the identifier of an instrument.
592 Identifier of the sound bank to reference, occupying no more than 14 bits.
594 Specifies whether to reference a custom or standard sound bank.
595 @param aInstrumentIndex
596 Index of the instrument to reference where 0 <= aInstrumentIndex < NumberOfInstrumentsL().
598 Identifier of specified instrument. This may differ from the index since the
599 index simply enumerates the instruments, whereas identifiers may not be
600 contiguous, especially where certain instruments correspond to General MIDI-defined
601 instruments but not all instruments are present. Instrument identifiers are
602 between 0 and 127 inclusive.
604 virtual void MmcGetInstrumentIdL(TInt aBankId,TBool aCustom,TInt aInstrumentIndex, TInt& aInstrumentId) = 0;
606 Gets the name of the given instrument.
609 Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
611 Specifies whether to reference a custom or standard sound bank.
613 Identifier of the instrument under scrutiny. 0 <= aInstrumentId <= 127.
614 @return Buffer containing the name of the specified instrument.
615 If it has no name then an empty descriptor is returned.
617 virtual const TDesC& MmcInstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) = 0;
619 Sets a logical channel to use the given instrument.
622 Logical channel to set the instrument for. 0 <= aChannel <= 15.
624 Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
625 The bank ID is a concatenation of MIDI bank MSB and LSB values.
627 Identifier of the instrument under scrutiny. 0 <= aInstrumentId <= 127.
629 virtual void MmcSetInstrumentL(TInt aChannel,TInt aBankId,TInt aInstrumentId) = 0;
631 Loads an individual instrument from file into custom sound bank memory for use.
632 The bank and instrument ids given in the file can be mapped into different bank
633 and instrument ids in memory.
636 Name of the file containing the instrument.
638 Identifier of the bank in the file from which to load the instrument,
639 occupying no more than 14 bits.
640 @param aFileInstrumentId
641 Identifier of the instrument to load. 0 <= aInstrumentId <= 127.
643 Identifier of the custom bank in memory to load the instrument into,
644 occupying no more than 14 bits.
645 @param aMemoryInstrumentId
646 Identifier of the instrument in memory to load the new instrument into.
647 0 <= aInstrumentId <= 127.
649 virtual void MmcLoadCustomInstrumentL(const TDesC& aFileName, TInt aFileBankId, TInt aFileInstrumentId, TInt aMemoryBankId, TInt aMemoryInstrumentId) = 0;
651 Loads an individual instrument from descriptor into custom sound bank memory for use.
652 The bank and instrument ids given in the descriptor can be mapped into different bank
653 and instrument ids in memory.
655 @param aInstrumentData
656 Descriptor containing the instrument.
658 Identifier of the bank in the descriptor from which to load the instrument,
659 occupying no more than 14 bits.
660 @param aInstrumentDataId
661 Identifier of the instrument to load. 0 <= aInstrumentId <= 127.
663 Identifier of the custom bank in memory to load the instrument into,
664 occupying no more than 14 bits.
665 @param aMemoryInstrumentId
666 Identifier of the instrument in memory to load the new instrument into.
667 0 <= aInstrumentId <= 127.
669 virtual void MmcLoadCustomInstrumentDataL(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId) = 0;
671 Removes an instrument from custom sound bank memory.
672 Only valid for instruments previously loaded from file.
673 Once unloaded the instrument is no longer available for use.
676 Identifier of the custom sound bank containing the instrument
677 to unload, occupying no more than 14 bits.
679 Identifier of the instrument to unload. 0 <= aInstrumentId <= 127.
681 virtual void MmcUnloadCustomInstrumentL(TInt aCustomBankId,TInt aInstrumentId) = 0;
683 Gets the name of a particular percussion key corresponding to a given note.
686 Note to query. 0 <= aNote <= 127.
688 Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
689 The bank ID is a concatenation of MIDI bank MSB and LSB values.
691 Specifies whether to reference a custom or standard sound bank.
693 Identifier of an instrument.
694 @return Descriptor containing the name of the percussion key.
695 If the key does not have a name then an empty descriptor is returned.
697 virtual const TDesC& MmcPercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) = 0;
699 Get the stop time currently set for the MIDI resource.
702 Time at which playback will stop, relative to the start of the resource.
703 @return Descriptor containing the name of the percussion key. If the key
704 does not have a name then an empty descriptor is returned.
706 virtual void MmcStopTimeL(TTimeIntervalMicroSeconds& aStopTime) = 0;
708 Sets the stop time to use for the currently open MIDI resource
711 Time at which playback will stop, relative to the start of the resource.
712 Clamped to 0 and the duration of the resource.
714 virtual void MmcSetStopTimeL(const TTimeIntervalMicroSeconds& aStopTime) = 0;
716 Gets the number of currently active voices.
719 The number of currently active voices.
721 virtual void MmcPolyphonyL(TInt& aNumNotes) = 0;
723 Get the maximum number of logical channels supported by the MIDI engine.
726 The maximum number of logical channels that the MIDI engine supports, 0 <= aChannels <=15.
728 virtual void MmcChannelsSupportedL(TInt& aChannels) = 0;
730 Get the current volume setting of a logical channel.
733 Logical channel to query. 0 <= aChannel <= 15.
735 Volume currently set on the specified channel in decibels.
737 virtual void MmcChannelVolumeL(TInt aChannel, TReal32& aChannelVol) = 0;
739 Gets the Maximum volume setting that may be applied to a logical channel.
742 Maximum volume setting. Minimum value is -infinity dB, which is
743 the smallest possible value that TReal32 supports.
745 virtual void MmcMaxChannelVolumeL(TReal32& aMaxVol) = 0;
747 Set the volume of a channel.
750 Logical channel to set the volume on. 0 <= aChannel <= 15.
752 The channel volume can be set within a range. The minimum channel
753 volume is -infinity dB, which is the smallest possible value that
754 TReal32 supports while the maximum channel volume is set via MaxVolumeL()
755 which represents the volume level in dB corresponding to the MIDI Channel
758 virtual void MmcSetChannelVolumeL(TInt aChannel,TReal32 aVolume) = 0;
760 Set the muting state of a channel without changing its volume setting.
761 When unmuted the channel goes back to its previous volume setting.
764 Logical channel to set the mute state of. 0 <= aChannel <= 15.
766 ETrue to mute the channel, EFalse to unmute it.
768 virtual void MmcSetChannelMuteL(TInt aChannel,TBool aMuted) = 0;
770 Gets the overall volume of the MIDI client.
773 The current overall volume setting.
775 virtual void MmcVolumeL(TInt& aVolume) = 0;
777 Maximum volume setting that may be applied overall.
780 Maximum volume setting. Minimum value is always zero which is silent.
782 virtual void MmcMaxVolumeL(TInt& aMaxVolume) = 0;
784 Set the overall volume of the MIDI client.
785 This setting scales all channel volumes respectively so the actual volume
786 that a channel is played at becomes (overall volume * channel volume / max volume).
788 @param aVolume Overall volume setting to use.
790 virtual void MmcSetVolumeL(TInt aVolume) = 0;
792 Length of time over which the volume is faded up from zero to the current settings
793 when playback is started.
796 Duration of the ramping period.
798 virtual void MmcSetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration) = 0;
800 Get the current stereo balance value.
803 Balance value ranging from KMMFBalanceMaxLeft to KMMFBalanceMaxRight.
805 virtual void MmcGetBalanceL(TInt& aBalance) = 0;
807 Set the current stereo balance value.
810 Balance value to set. Defaults to KMMFBalanceCenter to restore equal left-right balance.
812 virtual void MmcSetBalanceL(TInt aBalance) = 0;
814 Set the max polyphony level the engine can handle.
817 Max polyphony level, 0 <= PolyphonyL() <= aMaxNotes.
819 virtual void MmcSetMaxPolyphonyL(TInt aMaxNotes) = 0;
821 Gets the number of times the current opened resources have to be repeated.
824 The number of time the current opened resources have to be repeated.
826 virtual void MmcGetRepeatsL(TInt& aNumRepeats) = 0;
828 Set the number of times to repeat the current MIDI resource.
829 After Stop() has been called, repeat number of times and the trailing silence are reset.
831 @param aRepeatNumberOfTimes
832 Number of times to repeat the resource during playback. This includes the first playing.
833 @param aTrailingSilence
834 Time in microseconds to pause between repeats.
836 virtual void MmcSetRepeatsL(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence) = 0;
838 Tell the MIDI engine to use a custom bank or a standard bank.
841 If Etrue the custom bank in memory is used otherwise the standard bank
842 is used leaving the custom bank in memory.
844 virtual void MmcSetBankL(TBool aCustom) = 0;
846 Gets the muting status of a specific track.
851 The mute status of the track.
853 virtual void MmcIsTrackMuteL(TInt aTrack, TBool& aTrackMute) = 0;
855 Gets the muting status of a specific channel.
858 The channel to query.
860 The mute status of the channel.
862 virtual void MmcIsChannelMuteL(TInt aChannel, TBool& aChannelMute) = 0;
864 Gets the instrument assigned to a specified channel.
867 Logical channel, 0 <= aChannel <= 15.
869 Identifier of the instrument assigned to aChannel. 0 <= aInstrumentId <= 127.
871 Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
873 virtual void MmcGetInstrumentL(TInt aChannel, TInt& aInstrumentId, TInt& aBankId) = 0;
875 Closes any currently open resources, such as files, descriptors or URLs in use.
876 Does nothing if there is nothing currently open.
878 virtual void MmcCloseL() = 0;
880 Stops playback of a resource but does not change the current position or release any resources.
881 Pauses the internal timer if no resource is open.
883 @param aFadeOutDuration
884 Length of time over which the volume is faded out from the current settings to zero.
886 virtual void MmcStopL(const TTimeIntervalMicroSeconds& aFadeOutDuration) = 0;
888 Gets the max polyphony level the engine can handle.
891 Max polyphony level, PolyphonyL() <= aMaxNotes.
893 virtual void MmcMaxPolyphonyL(TInt& aMaxNotes) = 0;
900 class CMidiEventReceiver : public CBase
903 static CMidiEventReceiver* NewL(const TMMFMessage& aMessage);
904 ~CMidiEventReceiver();
905 void PrepareEventL(const CMMFMidiEvent& aEvent);
906 void SendEventL(TMMFMessage& aMessage);
907 TBool IsWaitingToSendEvent();
909 CMidiEventReceiver(const TMMFMessage& aMessage);
911 TMMFMessage iMessage;
917 Mixin class to define an object capable of handling a MIDI event within the controller framework.
922 class MMidiEventHandler
926 Send an event to the client.
930 @return One of the system-wide error codes.
932 virtual TInt SendMidiEventToClient(const CMMFMidiEvent& aEvent) = 0;
937 Custom command parser class to be used by controller plugins wishing to support
938 MIDI controller commands.
939 The controller plugin must be derived from MMidiCustomCommandImplementor
940 to use this class. The controller plugin should create an object of this type and add
941 it to the list of custom command parsers in the controller framework.
946 class CMidiCustomCommandParser : public CMMFCustomCommandParserBase,
947 public MMidiEventHandler
950 IMPORT_C static CMidiCustomCommandParser* NewL(MMidiCustomCommandImplementor& aImplementor);
951 IMPORT_C ~CMidiCustomCommandParser();
955 void HandleRequest(TMMFMessage& aMessage);
956 virtual TInt SendMidiEventToClient(const CMMFMidiEvent& aEvent);
958 CMidiCustomCommandParser(MMidiCustomCommandImplementor& aImplementor);
959 // Internal request handling methods.
960 void DoHandleRequestL(TMMFMessage& aMessage);
962 TBool DoSetPositionMicroBeatsL(TMMFMessage& aMessage);
963 TBool DoPositionMicroBeatsL(TMMFMessage& aMessage);
964 TBool DoPlayNoteL(TMMFMessage& aMessage);
965 TBool DoPlayNoteWithStartTimeL(TMMFMessage& aMessage);
966 TBool DoStopNotesL(TMMFMessage& aMessage);
967 TBool DoNoteOnL(TMMFMessage& aMessage);
968 TBool DoNoteOffL(TMMFMessage& aMessage);
969 TBool DoPlaybackRateL(TMMFMessage& aMessage);
970 TBool DoSetPlaybackRateL(TMMFMessage& aMessage);
971 TBool DoMaxPlaybackRateL(TMMFMessage& aMessage);
972 TBool DoMinPlaybackRateL(TMMFMessage& aMessage);
973 TBool DoTempoMicroBeatsPerMinuteL(TMMFMessage& aMessage);
974 TBool DoSetTempoL(TMMFMessage& aMessage);
975 TBool DoPitchTranspositionCentsL(TMMFMessage& aMessage);
976 TBool DoSetPitchTranspositionL(TMMFMessage& aMessage);
977 TBool DoDurationMicroBeatsL(TMMFMessage& aMessage);
978 TBool DoNumTracksL(TMMFMessage& aMessage);
979 TBool DoSetTrackMuteL(TMMFMessage& aMessage);
980 TBool DoMimeTypeL(TMMFMessage& aMessage);
981 TBool DoSetSyncUpdateCallbackIntervalL(TMMFMessage& aMessage);
982 TBool DoSendMessageL(TMMFMessage& aMessage);
983 TBool DoSendMessageWithTimeStampL(TMMFMessage& aMessage);
984 TBool DoSendMipMessageL(TMMFMessage& aMessage);
985 TBool DoNumberOfBanksL(TMMFMessage& aMessage);
986 TBool DoGetBankIdL(TMMFMessage& aMessage);
987 TBool DoLoadCustomBankL(TMMFMessage& aMessage);
988 TBool DoLoadCustomBankDataL(TMMFMessage& aMessage);
989 TBool DoUnloadCustomBankL(TMMFMessage& aMessage);
990 TBool DoCustomBankLoadedL(TMMFMessage& aMessage);
991 TBool DoUnloadAllCustomBanksL(TMMFMessage& aMessage);
992 TBool DoNumberOfInstrumentsL(TMMFMessage& aMessage);
993 TBool DoGetInstrumentIdL(TMMFMessage& aMessage);
994 TBool DoInstrumentNameL(TMMFMessage& aMessage);
995 TBool DoCopyInstrumentNameL(TMMFMessage& aMessage);
996 TBool DoSetInstrumentL(TMMFMessage& aMessage);
997 TBool DoLoadCustomInstrumentL(TMMFMessage& aMessage);
998 TBool DoLoadCustomInstrumentDataL(TMMFMessage& aMessage);
999 TBool DoUnloadCustomInstrumentL(TMMFMessage& aMessage);
1000 TBool DoPercussionKeyNameL(TMMFMessage& aMessage);
1001 TBool DoCopyPercussionKeyNameL(TMMFMessage& aMessage);
1002 TBool DoStopTimeL(TMMFMessage& aMessage);
1003 TBool DoSetStopTimeL(TMMFMessage& aMessage);
1004 TBool DoPolyphonyL(TMMFMessage& aMessage);
1005 TBool DoChannelsSupportedL(TMMFMessage& aMessage);
1006 TBool DoChannelVolumeL(TMMFMessage& aMessage);
1007 TBool DoMaxChannelVolumeL(TMMFMessage& aMessage);
1008 TBool DoSetChannelVolumeL(TMMFMessage& aMessage);
1009 TBool DoSetChannelMuteL(TMMFMessage& aMessage);
1010 TBool DoVolumeL(TMMFMessage& aMessage);
1011 TBool DoMaxVolumeL(TMMFMessage& aMessage);
1012 TBool DoSetVolumeL(TMMFMessage& aMessage);
1013 TBool DoSetVolumeRampL(TMMFMessage& aMessage);
1014 TBool DoGetBalanceL(TMMFMessage& aMessage);
1015 TBool DoSetBalanceL(TMMFMessage& aMessage);
1016 TBool DoSetMaxPolyphonyL(TMMFMessage& aMessage);
1017 TBool DoGetRepeatsL(TMMFMessage& aMessage);
1018 TBool DoSetRepeatsL(TMMFMessage& aMessage);
1019 TBool DoSetBankL(TMMFMessage& aMessage);
1020 TBool DoIsTrackMuteL(TMMFMessage& aMessage);
1021 TBool DoIsChannelMuteL(TMMFMessage& aMessage);
1022 TBool DoGetInstrumentL(TMMFMessage& aMessage);
1023 TBool DoCloseL(TMMFMessage& aMessage);
1024 TBool DoStopL(TMMFMessage& aMessage);
1025 TBool DoReceiveEventsL(TMMFMessage& aMessage);
1026 TBool DoRetrieveEventL(TMMFMessage& aMessage);
1027 TBool DoCancelReceiveEventsL(TMMFMessage& aMessage);
1029 void DoCreateBufFromUintArrayL(RArray<TUint>& aArray);
1030 void DoCreateBufFromFourCCArrayL(RArray<TFourCC>& aArray);
1031 TBool DoMaxPolyphonyL(TMMFMessage& aMessage);
1033 /** The object that implements the MIDI controller interface */
1034 MMidiCustomCommandImplementor& iImplementor;
1036 CMidiEventReceiver* iMidiEventReceiver;
1037 /** The events waiting to be sent to the client.*/
1038 RPointerArray<CMMFMidiEvent> iMidiEvents;
1040 // variable length data waiting to be copied back to the client
1041 CBufFlat* iInstrumentName;
1042 CBufFlat* iPercussionKeyName;