diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mmf/common/midistandardcustomcommands.h --- /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 +#include +#include + +/** +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 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& 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& 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& 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& aArray); + void DoCreateBufFromFourCCArrayL(RArray& 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 iMidiEvents; + + // variable length data waiting to be copied back to the client + CBufFlat* iInstrumentName; + CBufFlat* iPercussionKeyName; + }; + +#endif