--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/mmf/common/midistandardcustomcommands.h Tue Mar 16 16:12:26 2010 +0000
@@ -0,0 +1,1045 @@
+// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// 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
+// which accompanies this distribution, and is available
+// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+//
+
+#ifndef __MIDISTANDARDCUSTOMCOMMANDS_H__
+#define __MIDISTANDARDCUSTOMCOMMANDS_H__
+
+#include <mmf/common/mmfcontroller.h>
+#include <midiclientutility.h>
+#include <mmf/common/mmfmidi.h>
+
+/**
+Interface UID for the Midi Controller API.
+
+@publishedAll
+@released
+*/
+const TUid KUidInterfaceMidi = { 0x101F945C };
+
+/**
+Describe a MIDI event.
+Contains a UID to define the actual event type, and an integer to define the event code.
+
+@publishedAll
+@released
+*/
+class CMMFMidiEvent: public CBase
+ {
+public:
+ IMPORT_C CMMFMidiEvent(TUid aEventType, TInt aErrorCode);
+ IMPORT_C CMMFMidiEvent();
+ IMPORT_C ~CMMFMidiEvent();
+ IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
+ IMPORT_C void InternalizeL(RReadStream& aStream);
+ IMPORT_C void CopyL(const CMMFMidiEvent& aOther);
+ /**
+ @internalTechnology
+ */
+ void ZeroMembers();
+public:
+ /**
+ * A UID to define the type of MIDI event.
+ */
+ TUid iEventType;
+ /**
+ * The error code associated with the MIDI event.
+ */
+ TInt iErrorCode;
+ /**
+ * Old state of the MIDI client utility object.
+ */
+ TMidiState iOldState;
+ /**
+ * Current state of the MIDI client utility object.
+ */
+ TMidiState iNewState;
+ /**
+ * General purpose time stamp in microseconds.
+ */
+ TTimeIntervalMicroSeconds iMicroSeconds;
+ /**
+ * General purpose time stamp in micro beats per minute.
+ */
+ TInt64 iMicroBeats;
+ /**
+ * Channel
+ */
+ TInt iChannel;
+ /**
+ * Volume in decibel of a logical channel.
+ */
+ TReal32 iVolumeInDecibels;
+ /**
+ * Mute state of a track or of a channel.
+ */
+ TBool iMute;
+ /**
+ * Meta data entry.
+ * Client will retrieve meta data entry by calling GetMetaDataEntryL()
+ * using this TInt to indicate which meta data entry to retrieve.
+ */
+ TInt iMetaDataEntryId;
+ /**
+ * Array of logical {channel, MIP} value pairs.
+ */
+ RArray<TMipMessageEntry> iMipMessage;
+ /**
+ * Polyphony of the MIDI engine.
+ */
+ TInt iPolyphony;
+ /**
+ * Identifier of a bank occupying, at most, 14 bits.
+ */
+ TInt iBankId;
+ /**
+ * Identifier of a specific instrument.
+ */
+ TInt iInstrumentId;
+ /**
+ * Tempo value in micro beats per minute.
+ */
+ TInt iTempoMicroBeats;
+ };
+
+/**
+@internalComponent
+*/
+enum TMMFMidiControllerMessages
+ {
+ EMMFMidiControllerSetPositionMicroBeats,
+ EMMFMidiControllerPositionMicroBeats,
+ EMMFMidiControllerPlayNote,
+ EMMFMidiControllerPlayNoteWithStartTime,
+ EMMFMidiControllerStopNotes,
+ EMMFMidiControllerNoteOn,
+ EMMFMidiControllerNoteOff,
+ EMMFMidiControllerPlaybackRate,
+ EMMFMidiControllerSetPlaybackRate,
+ EMMFMidiControllerMaxPlaybackRate,
+ EMMFMidiControllerMinPlaybackRate,
+ EMMFMidiControllerTempo,
+ EMMFMidiControllerSetTempo,
+ EMMFMidiControllerPitch,
+ EMMFMidiControllerSetPitch,
+ EMMFMidiControllerDurationMicroBeats,
+ EMMFMidiControllerNumTracks,
+ EMMFMidiControllerSetTrackMute,
+ EMMFMidiControllerMimeType,
+ EMMFMidiControllerSetSyncUpdateCallbackInterval,
+ EMMFMidiControllerSendMessage,
+ EMMFMidiControllerSendMessageWithTimeStamp,
+ EMMFMidiControllerSendMipMessage,
+ EMMFMidiControllerNumberOfBanks,
+ EMMFMidiControllerGetBankId,
+ EMMFMidiControllerLoadCustomBank,
+ EMMFMidiControllerLoadCustomBankData,
+ EMMFMidiControllerUnloadCustomBank,
+ EMMFMidiControllerCustomBankLoaded,
+ EMMFMidiControllerUnloadAllCustomBanks,
+ EMMFMidiControllerNumberOfInstruments,
+ EMMFMidiControllerGetInstrumentId,
+ EMMFMidiControllerInstrumentName,
+ EMMFMidiControllerCopyInstrumentName,
+ EMMFMidiControllerSetInstrument,
+ EMMFMidiControllerLoadCustomInstrument,
+ EMMFMidiControllerLoadCustomInstrumentData,
+ EMMFMidiControllerUnloadCustomInstrument,
+ EMMFMidiControllerPercussionKeyName,
+ EMMFMidiControllerCopyPercussionKeyName,
+ EMMFMidiControllerSetStopTime,
+ EMMFMidiControllerStopTime,
+ EMMFMidiControllerPolyphony,
+ EMMFMidiControllerSetMaxPolyphony,
+ EMMFMidiControllerChannelsSupported,
+ EMMFMidiControllerChannelVolume,
+ EMMFMidiControllerMaxChannelVolume,
+ EMMFMidiControllerSetChannelVolume,
+ EMMFMidiControllerSetChannelMute,
+ EMMFMidiControllerVolume,
+ EMMFMidiControllerMaxVolume,
+ EMMFMidiControllerSetVolume,
+ EMMFMidiControllerSetVolumeRamp,
+ EMMFMidiControllerGetBalance,
+ EMMFMidiControllerSetBalance,
+ EMMFMidiControllerGetRepeats,
+ EMMFMidiControllerSetRepeats,
+ EMMFMidiControllerSetBank,
+ EMMFMidiControllerIsTrackMute,
+ EMMFMidiControllerIsChannelMute,
+ EMMFMidiControllerGetInstrument,
+ EMMFMidiControllerClose,
+ EMMFMidiControllerStop,
+ EMMFMidiControllerReceiveEvents,
+ EMMFMidiControllerRetrieveEvent,
+ EMMFMidiControllerCancelReceiveEvents,
+ EMMFMidiControllerMaxPolyphony
+ };
+
+/**
+Client class to access functionality specific to a MIDI controller.
+The class uses the custom command function of the controller plugin, and removes the necessity
+for the client to formulate the custom commands.
+
+@publishedAll
+@released
+*/
+class RMidiControllerCustomCommands : public RMMFCustomCommandsBase
+ {
+public:
+ IMPORT_C RMidiControllerCustomCommands(RMMFController& aController);
+ IMPORT_C TInt SetPositionMicroBeats(TInt64 aMicroBeats) const;
+ IMPORT_C TInt PositionMicroBeats(TInt64& aMicroBeats) const;
+ IMPORT_C TInt PlayNote(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);
+ IMPORT_C TInt PlayNote(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime, const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);
+ IMPORT_C TInt StopNotes(TInt aChannel);
+ IMPORT_C TInt NoteOn(TInt aChannel,TInt aNote,TInt aVelocity);
+ IMPORT_C TInt NoteOff(TInt aChannel,TInt aNote,TInt aVelocity);
+ IMPORT_C TInt PlaybackRate(TInt& aPlayBackRate) const;
+ IMPORT_C TInt SetPlaybackRate(TInt aPlayBackRate);
+ IMPORT_C TInt MaxPlaybackRate(TInt& aMaxRate) const;
+ IMPORT_C TInt MinPlaybackRate(TInt& aMinRate) const;
+ IMPORT_C TInt TempoMicroBeatsPerMinute(TInt& aMicroBeatsPerMinute) const;
+ IMPORT_C TInt SetTempo(TInt aMicroBeatsPerMinute);
+ IMPORT_C TInt PitchTranspositionCents(TInt& aPitch) const;
+ IMPORT_C TInt SetPitchTransposition(TInt aCents, TInt& aCentsApplied);
+ IMPORT_C TInt DurationMicroBeats(TInt64& aDuration) const;
+ IMPORT_C TInt NumTracks(TInt& aTracks) const;
+ IMPORT_C TInt SetTrackMute(TInt aTrack, TBool aMuted) const;
+ IMPORT_C TInt MimeType(TDes8& aMimeType) const;
+ IMPORT_C TInt SetSyncUpdateCallbackInterval(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats=0);
+ IMPORT_C TInt SendMessage(const TDesC8& aMidiMessage, TInt& aBytes);
+ IMPORT_C TInt SendMessage(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime, TInt& aBytes);
+ IMPORT_C TInt SendMipMessage(const RArray<TMipMessageEntry>& aEntry);
+ IMPORT_C TInt NumberOfBanks(TBool aCustom, TInt& aNumBanks) const;
+ IMPORT_C TInt GetBankId(TBool aCustom, TInt aBankIndex, TInt& aBankId) const;
+ IMPORT_C TInt LoadCustomBank(const TDesC& aFileName,TInt& aBankId);
+ IMPORT_C TInt LoadCustomBankData(const TDesC8& aBankData,TInt& aBankId);
+ IMPORT_C TInt UnloadCustomBank(TInt aBankId);
+ IMPORT_C TInt CustomBankLoaded(TInt aBankId, TBool& aBankLoaded) const;
+ IMPORT_C TInt UnloadAllCustomBanks();
+ IMPORT_C TInt NumberOfInstruments(TInt aBankId, TBool aCustom, TInt& aNumInstruments) const;
+ IMPORT_C TInt GetInstrumentId(TInt aBankId,TBool aCustom,TInt aInstrumentIndex, TInt& aInstrumentId) const;
+ IMPORT_C HBufC* InstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) const;
+ IMPORT_C TInt SetInstrument(TInt aChannel,TInt aBankId,TInt aInstrumentId);
+ IMPORT_C TInt LoadCustomInstrument(const TDesC& aFileName, TInt aFileBankId, TInt aFileInstrumentId, TInt aMemoryBankId, TInt aMemoryInstrumentId);
+ IMPORT_C TInt LoadCustomInstrumentData(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId);
+ IMPORT_C TInt UnloadCustomInstrument(TInt aCustomBankId,TInt aInstrumentId);
+ IMPORT_C HBufC* PercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) const;
+ IMPORT_C TInt StopTime(TTimeIntervalMicroSeconds& aStopTime) const;
+ IMPORT_C TInt SetStopTime(const TTimeIntervalMicroSeconds& aStopTime) const;
+ IMPORT_C TInt Polyphony(TInt& aNumNotes) const;
+ IMPORT_C TInt ChannelsSupported(TInt& aChannels) const;
+ IMPORT_C TInt ChannelVolume(TInt aChannel, TReal32& aChannelVol) const;
+ IMPORT_C TInt MaxChannelVolume(TReal32& aMaxVol) const;
+ IMPORT_C TInt SetChannelVolume(TInt aChannel,TReal32 aVolume);
+ IMPORT_C TInt SetChannelMute(TInt aChannel,TBool aMuted);
+ IMPORT_C TInt Volume(TInt& aVolume) const;
+ IMPORT_C TInt MaxVolume(TInt& aMaxVolume) const;
+ IMPORT_C TInt SetVolume(TInt aVolume);
+ IMPORT_C TInt SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);
+ IMPORT_C TInt GetBalance(TInt& aBalance) const;
+ IMPORT_C TInt SetBalance(TInt aBalance);
+ IMPORT_C TInt SetMaxPolyphony(TInt aMaxNotes);
+ IMPORT_C TInt GetRepeats(TInt& aNumRepeats) const;
+ IMPORT_C TInt SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence);
+ IMPORT_C TInt SetBank(TBool aCustom);
+ IMPORT_C TInt IsTrackMute(TInt aTrack, TBool& aTrackMute) const;
+ IMPORT_C TInt IsChannelMute(TInt aChannel, TBool& aChannelMute) const;
+ IMPORT_C TInt GetInstrument(TInt aChannel, TInt& aInstrumentId, TInt& aBankId);
+ IMPORT_C TInt Close();
+ IMPORT_C TInt Stop(const TTimeIntervalMicroSeconds& aFadeOutDuration);
+ IMPORT_C void ReceiveEvents(TPckgBuf<TInt>& aEventSize, TRequestStatus& aStatus);
+ IMPORT_C TInt RetrieveEvent(TDes8& aMidiEventPckg);
+ IMPORT_C TInt CancelReceiveEvents();
+ IMPORT_C TInt MaxPolyphony(TInt& aNumNotes) const;
+ };
+
+
+/**
+Mixin class to be derived from by controller plugins wishing
+to support the MIDI controller custom commands.
+
+@publishedAll
+@released
+*/
+class MMidiCustomCommandImplementor
+ {
+public:
+ /**
+ Change the position of the currently playing MIDI resource to the given position.
+ May be called whenever a MIDI resource is open.
+
+ @param aMicroBeats
+ Metrical position to move to. Clamped to (0, DurationMicroBeats()).
+ */
+ virtual void MmcSetPositionMicroBeatsL(TInt64 aMicroBeats) = 0;
+ /**
+ Gets the current metrical position of the MIDI resource being played
+
+ @param aMicroBeats
+ (BPM*1000000) relative to the start of the resource
+ */
+ virtual void MmcPositionMicroBeatsL(TInt64& aMicroBeats) = 0;
+ /**
+ Synchronous function to play a single note.
+ Multiple calls to this function will be accommodated as far as the MIDI engine can
+ manage. The same functionality could be implemented using the SendMessage function
+
+ @param aChannel
+ Logical channel to play note on. 0 <= aChannel <= 15.
+ @param aNote
+ Note to play. 0 <= aNote <= 127
+ @param aDuration
+ Length of time to play note for.
+ @param aNoteOnVelocity
+ Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.
+ @param aNoteOffVelocity
+ Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.
+ */
+ virtual void MmcPlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity) = 0;
+ /**
+ Synchronous function to play a single note at a specified time.
+ Multiple calls to this function will be accommodated as far as the MIDI engine can
+ manage. The same functionality could be implemented using the SendMessage function
+
+ @param aChannel
+ Logical channel to play note on. 0 <= aChannel <= 15.
+ @param aNote
+ Note to play. 0 <= aNote <= 127
+ @param aStartTime
+ Specifies the time at which to start playing the note, relative to the MIDI
+ resource playing time or the time elapsed since Play() was called if no resource is present.
+ @param aDuration
+ Length of time to play note for.
+ @param aNoteOnVelocity
+ Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.
+ @param aNoteOffVelocity
+ Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.
+ */
+ virtual void MmcPlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime, const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity) = 0;
+ /**
+ Stops the playback of all notes on the given channel,
+ by means of an All Notes Off MIDI message
+
+ @param aChannel
+ Logical channel to stop notes on. 0 <= aChannel <= 15
+ */
+ virtual void MmcStopNotesL(TInt aChannel) = 0;
+ /**
+ Synchronous function to commence playback of a note.
+ Multiple calls to this function will be accommodated as far as the MIDI engine can manage
+
+ @param aChannel
+ Logical channel to play note on. 0 <= aChannel <= 15.
+ @param aNote
+ Note to play. 0 <= aNote <= 127.
+ @param aVelocity
+ Velocity with which to start the note. The legal integer range
+ is 0 <= aVelocity <= 127, but the value zero actually causes the
+ message to be interpreted as a Note Off message instead of a Note On.
+ */
+ virtual void MmcNoteOnL(TInt aChannel,TInt aNote,TInt aVelocity) = 0;
+ /**
+ Synchronous function to terminate playback of a note.
+ If no corresponding note is found then no error is raised
+
+ @param aChannel
+ Logical channel on which the note is playing. 0 <= aChannel <= 15.
+ @param aNote
+ Note to terminate. 0 <= aNote <= 127.
+ @param aVelocity
+ Velocity with which to stop the note. 0 <= aVelocity <= 127.
+ There is no standard behaviour corresponding with note off velocity.
+ */
+ virtual void MmcNoteOffL(TInt aChannel,TInt aNote,TInt aVelocity) = 0;
+ /**
+ Gets the current playback rate factor of the currently open MIDI resource.
+ The playback rate is independent from tempo,
+ i.e., it can be used to give an overall speed factor for playback.
+
+ @param aPlayBackRate
+ Current playback rate in percent times 1000, i.e., 100000 means original
+ playback speed, 200000 means double speed, and 50000 means half speed playback.
+ */
+ virtual void MmcPlaybackRateL(TInt& aPlayBackRate) = 0;
+ /**
+ Sets the playback rate for the playback of the current MIDI resource.
+ The playback rate is independent from tempo,
+ i.e., it can be used to give an overall speed factor for playback.
+ May be called whether playback is in progress or not.
+
+ @param aPlayBackRate
+ Playback rate in percent times 1000, i.e., 100000 means original playback speed,
+ 200000 means double speed, and 50000 means half speed playback.
+ */
+ virtual void MmcSetPlaybackRateL(TInt aPlayBackRate) = 0;
+ /**
+ Gets the maximum playback rate in milli-percentage from the MIDI engine.
+ @see SetPlaybackRate() for milli-percentage details.
+
+ @param aMaxRate
+ Playback rate supported by MIDI player.
+ */
+ virtual void MmcMaxPlaybackRateL(TInt& aMaxRate) = 0;
+ /**
+ Gets the minimum playback rate in milli-percentage from the MIDI engine.
+ @see SetPlaybackRate() for milli-percentage details.
+
+ @param aMinRate
+ Minimum playback rate supported by MIDI player.
+ */
+ virtual void MmcMinPlaybackRateL(TInt& aMinRate) = 0;
+ /**
+ Gets the current tempo of the currently open MIDI resource. The tempo is independent
+ from the playback rate, i.e., the resulting playback speed will be affected by both.
+
+ @param aMicroBeatsPerMinute
+ Tempo at the current position of the currently open resource in microbeats
+ per minute, i.e. BPM * 1000000. Filled in by the controller framework.
+ */
+ virtual void MmcTempoMicroBeatsPerMinuteL(TInt& aMicroBeatsPerMinute) = 0;
+ /**
+ Sets the tempo at which the current MIDI resource should be played.
+ May be called whether playback is in progress or not. The tempo is
+ independent from the playback rate, i.e., the resulting playback speed
+ will be affected by both.
+
+ @param aMicroBeatsPerMinute
+ Tempo in microbeats per minute (BPM*1000000) to set.
+ */
+ virtual void MmcSetTempoL(TInt aMicroBeatsPerMinute) = 0;
+ /**
+ Gets the pitch shift in use for the currently open MIDI resource.
+
+ @param aPitch
+ Shift in cents, i.e. semitones * 100. One octave equals 1200 cents.
+ @return One of the system-wide error codes.
+ */
+ virtual void MmcPitchTranspositionCentsL(TInt& aPitch) = 0;
+ /**
+ Sets the pitch shift to apply to the currently open MIDI resource.
+ May be called during playback.
+
+ @param aCents
+ Pitch shift in cents, i.e. semitones * 100. One octave equals 1200 cents.
+ @param aCentsApplied
+ Actual pitch shift applied - may differ from the requested value due
+ to limitations of the MIDI engine.
+ */
+ virtual void MmcSetPitchTranspositionL(TInt aCents, TInt& aCentsApplied) = 0;
+ /**
+ Gets the length of the currently open MIDI resource in micro-beats
+
+ @param aDuration
+ Duration in microbeats (beats * 1000000).
+ */
+ virtual void MmcDurationMicroBeatsL(TInt64& aDuration) = 0;
+ /**
+ Gets the number of tracks present in the currently open MIDI resource.
+
+ @param aTracks
+ Number of tracks.
+ */
+ virtual void MmcNumTracksL(TInt& aTracks) = 0;
+ /**
+ Mutes or unmutes a particular track.
+
+ @param aTrack
+ Index of the track to mute - 0 <= aTrack < NumTracks().
+ @param aMuted
+ ETrue to mute the track, EFalse to unmute it.
+ */
+ virtual void MmcSetTrackMuteL(TInt aTrack, TBool aMuted) = 0;
+ /**
+ Gets the MIME type of the MIDI resource currently open.
+
+ @param aMimeType
+ Descriptor containing the MIDI mime type.
+ */
+ virtual void MmcMimeTypeL(TDes8& aMimeType) = 0;
+ /**
+ Sets the frequency at which MMIDIClientUtilityObserver::MmcuoSyncUpdateL() is called
+ to allow other components to synchronise with playback of this MIDI resource.
+
+ @param aMicroSeconds
+ Temporal interval to callback at. Used in preference to aMicroBeats if both are set.
+ @param aMicroBeats
+ Metrical interval to callback at. Set both parameters to zero to cancel.
+ */
+ virtual void MmcSetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats=0) = 0;
+ /**
+ Sends a single MIDI message to the MIDI engine.
+
+ @param aMidiMessage
+ Descriptor containing the MIDI message data. If there are several
+ MIDI messages in the buffer, only the first one is processed.
+ @param aBytes
+ Number of bytes of the message buffer actually processed.
+ */
+ virtual void MmcSendMessageL(const TDesC8& aMidiMessage, TInt& aBytes) = 0;
+ /**
+ Sends a single MIDI message, with time stamp, to the MIDI engine.
+
+ @param aMidiMessage
+ Descriptor containing the MIDI message data. If there are several
+ MIDI messages in the buffer, only the first one is processed.
+ @param aTime
+ The time at which to execute the message, relative to the MIDI resource playing
+ time or the time elapsed since Play() was called if no resource is present.
+ @param aBytes
+ Number of bytes of the message buffer actually processed.
+ */
+ virtual void MmcSendMessageL(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime, TInt& aBytes) = 0;
+ /**
+ Sends a mip message to the MIDI engine. This is a convenience function,
+ because the same functionality could be achieved with the SendMessage() function.
+
+ @param aEntry
+ Array of logical {channel, MIP} value pairs to send, highest priority first.
+ */
+ virtual void MmcSendMipMessageL(const TArray<TMipMessageEntry>& aEntry) = 0;
+ /**
+ Gets the number of standard or custom sound banks currently available.
+
+ @param aCustom
+ Specifies whether to reference a custom or standard sound bank.
+ @param aNumBanks
+ Number of custom or standard sound banks available.
+ */
+ virtual void MmcNumberOfBanksL(TBool aCustom, TInt& aNumBanks) = 0;
+ /**
+ Gets the identifier of a sound bank. Bank identifier (aka bank number) is a
+ 14-bit value consisting of MIDI bank MSB and LSB values.
+
+ @param aCustom
+ Specifies whether to reference a custom or standard sound bank.
+ @param aBankIndex
+ Index of sound bank where 0 <= aBankIndex < NumberOfBanks().
+ @param aBankId
+ Identifier of the specified bank occupying, at most, 14 bits.
+ */
+ virtual void MmcGetBankIdL(TBool aCustom, TInt aBankIndex, TInt& aBankId) = 0;
+ /**
+ Loads one or more custom sound banks from a file into memory for use.
+ If several banks are loaded with consequent LoadCustomBanksL() function calls,
+ the banks are combined if the bank sets have conflicting bank numbers.
+
+ @param aFileName
+ Name of the file containing the custom sound bank.
+ @param aBankId
+ Identifier of the custom sound bank loaded, occupying no more than 14 bits.
+ */
+ virtual void MmcLoadCustomBankL(const TDesC& aFileName,TInt& aBankId) = 0;
+ /**
+ Loads one or more custom sound banks from a descriptor into memory for use.
+ If several banks are loaded with consequent LoadCustomBanksL() function calls,
+ the banks are combined if the bank sets have conflicting bank numbers.
+
+ @param aBankData
+ Descriptor containing the custom sound bank.
+ @param aBankId
+ Identifier of the custom sound bank loaded, occupying no more than 14 bits.
+ */
+ virtual void MmcLoadCustomBankDataL(const TDesC8& aBankData,TInt& aBankId) = 0;
+ /**
+ Removes a custom sound bank from memory. Only valid for sound banks previously
+ loaded from file. Once unloaded the custom sound bank is no longer available for use.
+
+ @param aBankId
+ Identifier of the custom sound bank to unload,occupying no more than 14 bits.
+ */
+ virtual void MmcUnloadCustomBankL(TInt aBankId) = 0;
+ /**
+ Query if a bank has been loaded to the memory.
+
+ @param aBankId
+ Identifier of the custom sound bank to check if it's in memory or not.
+ @param aBankLoaded
+ ETrue if the specified bank is in memory, EFalse otherwise.
+ */
+ virtual void MmcCustomBankLoadedL(TInt aBankId, TBool& aBankLoaded) = 0;
+ /**
+ Removes all custom sound banks from memory.
+ */
+ virtual void MmcUnloadAllCustomBanksL() = 0;
+ /**
+ Gets the number of instruments available in a given sound bank.
+
+ @param aBankId
+ Identifier of sound bank to reference, occupying no more than 14 bits.
+ @param aCustom
+ Specifies whether to reference a custom or standard sound bank.
+ @param aNumInstruments
+ Count of the number of instruments available for the specified sound bank.
+ */
+ virtual void MmcNumberOfInstrumentsL(TInt aBankId, TBool aCustom, TInt& aNumInstruments) = 0;
+ /**
+ Gets the identifier of an instrument.
+
+ @param aBankId
+ Identifier of the sound bank to reference, occupying no more than 14 bits.
+ @param aCustom
+ Specifies whether to reference a custom or standard sound bank.
+ @param aInstrumentIndex
+ Index of the instrument to reference where 0 <= aInstrumentIndex < NumberOfInstrumentsL().
+ @param aInstrumentId
+ Identifier of specified instrument. This may differ from the index since the
+ index simply enumerates the instruments, whereas identifiers may not be
+ contiguous, especially where certain instruments correspond to General MIDI-defined
+ instruments but not all instruments are present. Instrument identifiers are
+ between 0 and 127 inclusive.
+ */
+ virtual void MmcGetInstrumentIdL(TInt aBankId,TBool aCustom,TInt aInstrumentIndex, TInt& aInstrumentId) = 0;
+ /**
+ Gets the name of the given instrument.
+
+ @param aBankId
+ Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
+ @param aCustom
+ Specifies whether to reference a custom or standard sound bank.
+ @param aInstrumentId
+ Identifier of the instrument under scrutiny. 0 <= aInstrumentId <= 127.
+ @return Buffer containing the name of the specified instrument.
+ If it has no name then an empty descriptor is returned.
+ */
+ virtual const TDesC& MmcInstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) = 0;
+ /**
+ Sets a logical channel to use the given instrument.
+
+ @param aChannel
+ Logical channel to set the instrument for. 0 <= aChannel <= 15.
+ @param aBankId
+ Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
+ The bank ID is a concatenation of MIDI bank MSB and LSB values.
+ @param aInstrumentId
+ Identifier of the instrument under scrutiny. 0 <= aInstrumentId <= 127.
+ */
+ virtual void MmcSetInstrumentL(TInt aChannel,TInt aBankId,TInt aInstrumentId) = 0;
+ /**
+ Loads an individual instrument from file into custom sound bank memory for use.
+ The bank and instrument ids given in the file can be mapped into different bank
+ and instrument ids in memory.
+
+ @param aFileName
+ Name of the file containing the instrument.
+ @param aFileBankId
+ Identifier of the bank in the file from which to load the instrument,
+ occupying no more than 14 bits.
+ @param aFileInstrumentId
+ Identifier of the instrument to load. 0 <= aInstrumentId <= 127.
+ @param aMemoryBankId
+ Identifier of the custom bank in memory to load the instrument into,
+ occupying no more than 14 bits.
+ @param aMemoryInstrumentId
+ Identifier of the instrument in memory to load the new instrument into.
+ 0 <= aInstrumentId <= 127.
+ */
+ virtual void MmcLoadCustomInstrumentL(const TDesC& aFileName, TInt aFileBankId, TInt aFileInstrumentId, TInt aMemoryBankId, TInt aMemoryInstrumentId) = 0;
+ /**
+ Loads an individual instrument from descriptor into custom sound bank memory for use.
+ The bank and instrument ids given in the descriptor can be mapped into different bank
+ and instrument ids in memory.
+
+ @param aInstrumentData
+ Descriptor containing the instrument.
+ @param aBankDataId
+ Identifier of the bank in the descriptor from which to load the instrument,
+ occupying no more than 14 bits.
+ @param aInstrumentDataId
+ Identifier of the instrument to load. 0 <= aInstrumentId <= 127.
+ @param aMemoryBankId
+ Identifier of the custom bank in memory to load the instrument into,
+ occupying no more than 14 bits.
+ @param aMemoryInstrumentId
+ Identifier of the instrument in memory to load the new instrument into.
+ 0 <= aInstrumentId <= 127.
+ */
+ virtual void MmcLoadCustomInstrumentDataL(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId) = 0;
+ /**
+ Removes an instrument from custom sound bank memory.
+ Only valid for instruments previously loaded from file.
+ Once unloaded the instrument is no longer available for use.
+
+ @param aCustomBankId
+ Identifier of the custom sound bank containing the instrument
+ to unload, occupying no more than 14 bits.
+ @param aInstrumentId
+ Identifier of the instrument to unload. 0 <= aInstrumentId <= 127.
+ */
+ virtual void MmcUnloadCustomInstrumentL(TInt aCustomBankId,TInt aInstrumentId) = 0;
+ /**
+ Gets the name of a particular percussion key corresponding to a given note.
+
+ @param aNote
+ Note to query. 0 <= aNote <= 127.
+ @param aBankId
+ Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
+ The bank ID is a concatenation of MIDI bank MSB and LSB values.
+ @param aCustom
+ Specifies whether to reference a custom or standard sound bank.
+ @param aInstrumentId
+ Identifier of an instrument.
+ @return Descriptor containing the name of the percussion key.
+ If the key does not have a name then an empty descriptor is returned.
+ */
+ virtual const TDesC& MmcPercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) = 0;
+ /**
+ Get the stop time currently set for the MIDI resource.
+
+ @param aStopTime
+ Time at which playback will stop, relative to the start of the resource.
+ @return Descriptor containing the name of the percussion key. If the key
+ does not have a name then an empty descriptor is returned.
+ */
+ virtual void MmcStopTimeL(TTimeIntervalMicroSeconds& aStopTime) = 0;
+ /**
+ Sets the stop time to use for the currently open MIDI resource
+
+ @param aStopTime
+ Time at which playback will stop, relative to the start of the resource.
+ Clamped to 0 and the duration of the resource.
+ */
+ virtual void MmcSetStopTimeL(const TTimeIntervalMicroSeconds& aStopTime) = 0;
+ /**
+ Gets the number of currently active voices.
+
+ @param aNumNotes
+ The number of currently active voices.
+ */
+ virtual void MmcPolyphonyL(TInt& aNumNotes) = 0;
+ /**
+ Get the maximum number of logical channels supported by the MIDI engine.
+
+ @param aChannels
+ The maximum number of logical channels that the MIDI engine supports, 0 <= aChannels <=15.
+ */
+ virtual void MmcChannelsSupportedL(TInt& aChannels) = 0;
+ /**
+ Get the current volume setting of a logical channel.
+
+ @param aChannel
+ Logical channel to query. 0 <= aChannel <= 15.
+ @param aChannelVol
+ Volume currently set on the specified channel in decibels.
+ */
+ virtual void MmcChannelVolumeL(TInt aChannel, TReal32& aChannelVol) = 0;
+ /**
+ Gets the Maximum volume setting that may be applied to a logical channel.
+
+ @param aMaxVol
+ Maximum volume setting. Minimum value is -infinity dB, which is
+ the smallest possible value that TReal32 supports.
+ */
+ virtual void MmcMaxChannelVolumeL(TReal32& aMaxVol) = 0;
+ /**
+ Set the volume of a channel.
+
+ @param aChannel
+ Logical channel to set the volume on. 0 <= aChannel <= 15.
+ @param aVolume
+ The channel volume can be set within a range. The minimum channel
+ volume is -infinity dB, which is the smallest possible value that
+ TReal32 supports while the maximum channel volume is set via MaxVolumeL()
+ which represents the volume level in dB corresponding to the MIDI Channel
+ Volume controller.
+ */
+ virtual void MmcSetChannelVolumeL(TInt aChannel,TReal32 aVolume) = 0;
+ /**
+ Set the muting state of a channel without changing its volume setting.
+ When unmuted the channel goes back to its previous volume setting.
+
+ @param aChannel
+ Logical channel to set the mute state of. 0 <= aChannel <= 15.
+ @param aMuted
+ ETrue to mute the channel, EFalse to unmute it.
+ */
+ virtual void MmcSetChannelMuteL(TInt aChannel,TBool aMuted) = 0;
+ /**
+ Gets the overall volume of the MIDI client.
+
+ @param aVolume
+ The current overall volume setting.
+ */
+ virtual void MmcVolumeL(TInt& aVolume) = 0;
+ /**
+ Maximum volume setting that may be applied overall.
+
+ @param aMaxVolume
+ Maximum volume setting. Minimum value is always zero which is silent.
+ */
+ virtual void MmcMaxVolumeL(TInt& aMaxVolume) = 0;
+ /**
+ Set the overall volume of the MIDI client.
+ This setting scales all channel volumes respectively so the actual volume
+ that a channel is played at becomes (overall volume * channel volume / max volume).
+
+ @param aVolume Overall volume setting to use.
+ */
+ virtual void MmcSetVolumeL(TInt aVolume) = 0;
+ /**
+ Length of time over which the volume is faded up from zero to the current settings
+ when playback is started.
+
+ @param aRampDuration
+ Duration of the ramping period.
+ */
+ virtual void MmcSetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration) = 0;
+ /**
+ Get the current stereo balance value.
+
+ @param aBalance
+ Balance value ranging from KMMFBalanceMaxLeft to KMMFBalanceMaxRight.
+ */
+ virtual void MmcGetBalanceL(TInt& aBalance) = 0;
+ /**
+ Set the current stereo balance value.
+
+ @param aBalance
+ Balance value to set. Defaults to KMMFBalanceCenter to restore equal left-right balance.
+ */
+ virtual void MmcSetBalanceL(TInt aBalance) = 0;
+ /**
+ Set the max polyphony level the engine can handle.
+
+ @param aMaxNotes
+ Max polyphony level, 0 <= PolyphonyL() <= aMaxNotes.
+ */
+ virtual void MmcSetMaxPolyphonyL(TInt aMaxNotes) = 0;
+ /**
+ Gets the number of times the current opened resources have to be repeated.
+
+ @param aNumRepeats
+ The number of time the current opened resources have to be repeated.
+ */
+ virtual void MmcGetRepeatsL(TInt& aNumRepeats) = 0;
+ /**
+ Set the number of times to repeat the current MIDI resource.
+ After Stop() has been called, repeat number of times and the trailing silence are reset.
+
+ @param aRepeatNumberOfTimes
+ Number of times to repeat the resource during playback. This includes the first playing.
+ @param aTrailingSilence
+ Time in microseconds to pause between repeats.
+ */
+ virtual void MmcSetRepeatsL(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence) = 0;
+ /**
+ Tell the MIDI engine to use a custom bank or a standard bank.
+
+ @param aCustom
+ If Etrue the custom bank in memory is used otherwise the standard bank
+ is used leaving the custom bank in memory.
+ */
+ virtual void MmcSetBankL(TBool aCustom) = 0;
+ /**
+ Gets the muting status of a specific track.
+
+ @param aTrack
+ The track to query.
+ @param aTrackMute
+ The mute status of the track.
+ */
+ virtual void MmcIsTrackMuteL(TInt aTrack, TBool& aTrackMute) = 0;
+ /**
+ Gets the muting status of a specific channel.
+
+ @param aChannel
+ The channel to query.
+ @param aChannelMute
+ The mute status of the channel.
+ */
+ virtual void MmcIsChannelMuteL(TInt aChannel, TBool& aChannelMute) = 0;
+ /**
+ Gets the instrument assigned to a specified channel.
+
+ @param aChannel
+ Logical channel, 0 <= aChannel <= 15.
+ @param aInstrumentId
+ Identifier of the instrument assigned to aChannel. 0 <= aInstrumentId <= 127.
+ @param aBankId
+ Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
+ */
+ virtual void MmcGetInstrumentL(TInt aChannel, TInt& aInstrumentId, TInt& aBankId) = 0;
+ /**
+ Closes any currently open resources, such as files, descriptors or URLs in use.
+ Does nothing if there is nothing currently open.
+ */
+ virtual void MmcCloseL() = 0;
+ /**
+ Stops playback of a resource but does not change the current position or release any resources.
+ Pauses the internal timer if no resource is open.
+
+ @param aFadeOutDuration
+ Length of time over which the volume is faded out from the current settings to zero.
+ */
+ virtual void MmcStopL(const TTimeIntervalMicroSeconds& aFadeOutDuration) = 0;
+ /**
+ Gets the max polyphony level the engine can handle.
+
+ @param aNumNotes
+ Max polyphony level, PolyphonyL() <= aMaxNotes.
+ */
+ virtual void MmcMaxPolyphonyL(TInt& aMaxNotes) = 0;
+ };
+
+
+/**
+@internalComponent
+*/
+class CMidiEventReceiver : public CBase
+ {
+public:
+ static CMidiEventReceiver* NewL(const TMMFMessage& aMessage);
+ ~CMidiEventReceiver();
+ void PrepareEventL(const CMMFMidiEvent& aEvent);
+ void SendEventL(TMMFMessage& aMessage);
+ TBool IsWaitingToSendEvent();
+private:
+ CMidiEventReceiver(const TMMFMessage& aMessage);
+private:
+ TMMFMessage iMessage;
+ CBufFlat* iEventBuf;
+ };
+
+
+/**
+Mixin class to define an object capable of handling a MIDI event within the controller framework.
+
+@publishedAll
+@released
+*/
+class MMidiEventHandler
+ {
+public:
+ /**
+ Send an event to the client.
+
+ @param aEvent
+ The MIDI event.
+ @return One of the system-wide error codes.
+ */
+ virtual TInt SendMidiEventToClient(const CMMFMidiEvent& aEvent) = 0;
+ };
+
+
+/**
+Custom command parser class to be used by controller plugins wishing to support
+MIDI controller commands.
+The controller plugin must be derived from MMidiCustomCommandImplementor
+to use this class. The controller plugin should create an object of this type and add
+it to the list of custom command parsers in the controller framework.
+
+@publishedAll
+@released
+*/
+class CMidiCustomCommandParser : public CMMFCustomCommandParserBase,
+ public MMidiEventHandler
+ {
+public:
+ IMPORT_C static CMidiCustomCommandParser* NewL(MMidiCustomCommandImplementor& aImplementor);
+ IMPORT_C ~CMidiCustomCommandParser();
+ /**
+ @internalTechnology
+ */
+ void HandleRequest(TMMFMessage& aMessage);
+ virtual TInt SendMidiEventToClient(const CMMFMidiEvent& aEvent);
+private:
+ CMidiCustomCommandParser(MMidiCustomCommandImplementor& aImplementor);
+ // Internal request handling methods.
+ void DoHandleRequestL(TMMFMessage& aMessage);
+
+ TBool DoSetPositionMicroBeatsL(TMMFMessage& aMessage);
+ TBool DoPositionMicroBeatsL(TMMFMessage& aMessage);
+ TBool DoPlayNoteL(TMMFMessage& aMessage);
+ TBool DoPlayNoteWithStartTimeL(TMMFMessage& aMessage);
+ TBool DoStopNotesL(TMMFMessage& aMessage);
+ TBool DoNoteOnL(TMMFMessage& aMessage);
+ TBool DoNoteOffL(TMMFMessage& aMessage);
+ TBool DoPlaybackRateL(TMMFMessage& aMessage);
+ TBool DoSetPlaybackRateL(TMMFMessage& aMessage);
+ TBool DoMaxPlaybackRateL(TMMFMessage& aMessage);
+ TBool DoMinPlaybackRateL(TMMFMessage& aMessage);
+ TBool DoTempoMicroBeatsPerMinuteL(TMMFMessage& aMessage);
+ TBool DoSetTempoL(TMMFMessage& aMessage);
+ TBool DoPitchTranspositionCentsL(TMMFMessage& aMessage);
+ TBool DoSetPitchTranspositionL(TMMFMessage& aMessage);
+ TBool DoDurationMicroBeatsL(TMMFMessage& aMessage);
+ TBool DoNumTracksL(TMMFMessage& aMessage);
+ TBool DoSetTrackMuteL(TMMFMessage& aMessage);
+ TBool DoMimeTypeL(TMMFMessage& aMessage);
+ TBool DoSetSyncUpdateCallbackIntervalL(TMMFMessage& aMessage);
+ TBool DoSendMessageL(TMMFMessage& aMessage);
+ TBool DoSendMessageWithTimeStampL(TMMFMessage& aMessage);
+ TBool DoSendMipMessageL(TMMFMessage& aMessage);
+ TBool DoNumberOfBanksL(TMMFMessage& aMessage);
+ TBool DoGetBankIdL(TMMFMessage& aMessage);
+ TBool DoLoadCustomBankL(TMMFMessage& aMessage);
+ TBool DoLoadCustomBankDataL(TMMFMessage& aMessage);
+ TBool DoUnloadCustomBankL(TMMFMessage& aMessage);
+ TBool DoCustomBankLoadedL(TMMFMessage& aMessage);
+ TBool DoUnloadAllCustomBanksL(TMMFMessage& aMessage);
+ TBool DoNumberOfInstrumentsL(TMMFMessage& aMessage);
+ TBool DoGetInstrumentIdL(TMMFMessage& aMessage);
+ TBool DoInstrumentNameL(TMMFMessage& aMessage);
+ TBool DoCopyInstrumentNameL(TMMFMessage& aMessage);
+ TBool DoSetInstrumentL(TMMFMessage& aMessage);
+ TBool DoLoadCustomInstrumentL(TMMFMessage& aMessage);
+ TBool DoLoadCustomInstrumentDataL(TMMFMessage& aMessage);
+ TBool DoUnloadCustomInstrumentL(TMMFMessage& aMessage);
+ TBool DoPercussionKeyNameL(TMMFMessage& aMessage);
+ TBool DoCopyPercussionKeyNameL(TMMFMessage& aMessage);
+ TBool DoStopTimeL(TMMFMessage& aMessage);
+ TBool DoSetStopTimeL(TMMFMessage& aMessage);
+ TBool DoPolyphonyL(TMMFMessage& aMessage);
+ TBool DoChannelsSupportedL(TMMFMessage& aMessage);
+ TBool DoChannelVolumeL(TMMFMessage& aMessage);
+ TBool DoMaxChannelVolumeL(TMMFMessage& aMessage);
+ TBool DoSetChannelVolumeL(TMMFMessage& aMessage);
+ TBool DoSetChannelMuteL(TMMFMessage& aMessage);
+ TBool DoVolumeL(TMMFMessage& aMessage);
+ TBool DoMaxVolumeL(TMMFMessage& aMessage);
+ TBool DoSetVolumeL(TMMFMessage& aMessage);
+ TBool DoSetVolumeRampL(TMMFMessage& aMessage);
+ TBool DoGetBalanceL(TMMFMessage& aMessage);
+ TBool DoSetBalanceL(TMMFMessage& aMessage);
+ TBool DoSetMaxPolyphonyL(TMMFMessage& aMessage);
+ TBool DoGetRepeatsL(TMMFMessage& aMessage);
+ TBool DoSetRepeatsL(TMMFMessage& aMessage);
+ TBool DoSetBankL(TMMFMessage& aMessage);
+ TBool DoIsTrackMuteL(TMMFMessage& aMessage);
+ TBool DoIsChannelMuteL(TMMFMessage& aMessage);
+ TBool DoGetInstrumentL(TMMFMessage& aMessage);
+ TBool DoCloseL(TMMFMessage& aMessage);
+ TBool DoStopL(TMMFMessage& aMessage);
+ TBool DoReceiveEventsL(TMMFMessage& aMessage);
+ TBool DoRetrieveEventL(TMMFMessage& aMessage);
+ TBool DoCancelReceiveEventsL(TMMFMessage& aMessage);
+
+ void DoCreateBufFromUintArrayL(RArray<TUint>& aArray);
+ void DoCreateBufFromFourCCArrayL(RArray<TFourCC>& aArray);
+ TBool DoMaxPolyphonyL(TMMFMessage& aMessage);
+private:
+ /** The object that implements the MIDI controller interface */
+ MMidiCustomCommandImplementor& iImplementor;
+
+ CMidiEventReceiver* iMidiEventReceiver;
+ /** The events waiting to be sent to the client.*/
+ RPointerArray<CMMFMidiEvent> iMidiEvents;
+
+ // variable length data waiting to be copied back to the client
+ CBufFlat* iInstrumentName;
+ CBufFlat* iPercussionKeyName;
+ };
+
+#endif