// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// which accompanies this distribution, and is available

//

// 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;

	};

/**

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.