williamr@2: // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #ifndef __MIDICLIENTUTILITY_H__
williamr@2: #define __MIDICLIENTUTILITY_H__
williamr@2: 
williamr@2: #include <e32std.h>
williamr@2: #include <e32base.h>
williamr@2: #include <bamdesca.h> 
williamr@2: #include <mmf/common/mmfcontroller.h>
williamr@2: #include <mmf/common/mmfstandardcustomcommands.h>
williamr@2: #include <mmf/common/mmfdrmcustomcommands.h>
williamr@2: #include <mmf/common/mmfmididatacommon.h>
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: General utility class to hold instrument information.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class TInstrumentInfo
williamr@2: 	{
williamr@2: public:
williamr@2: 	/**
williamr@2: 	 *Identifier of sound bank to reference.
williamr@2: 	 */
williamr@2: 	TInt iBankId;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Specifies whether to reference a custom or standard sound bank.
williamr@2: 	 */
williamr@2: 	TBool iCustom;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Identifier of specified instrument.
williamr@2: 	 */
williamr@2: 	TInt iInstrumentId;
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Defines the state of the MIDI client utility with regard to the MIDI resource.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: enum TMidiState
williamr@2: 	{
williamr@2: 	/**
williamr@2: 	 * No MIDI resource is currently open. 
williamr@2: 	 * The MIDI engine is not processing midi events.
williamr@2: 	 */
williamr@2: 	EMidiStateClosedDisengaged,  
williamr@2: 
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * A MIDI resource is open and primed but not playing.
williamr@2: 	 * The MIDI engine is not processing midi events.
williamr@2: 	 */
williamr@2: 	EMidiStateOpenDisengaged,
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * A MIDI resource is open and currently playing.
williamr@2: 	 * The MIDI engine is currently processing midi events.
williamr@2: 	 */
williamr@2: 	EMidiStateOpenPlaying,  
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Not able to play full SP-MIDI or DLS content, but attempting best-effort playback.
williamr@2: 	 */
williamr@2: 	EMidiStatePlaybackIncompatible,
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Due to system resource constraints and SP-MIDI content constraints,
williamr@2: 	 * there is no audible MIDI content during playback currently.
williamr@2: 	 * The situation may change if resources are freed later.
williamr@2: 	 */
williamr@2: 	EMidiStatePlaybackSilent,
williamr@2: 		
williamr@2: 	/**
williamr@2: 	 * No MIDI resource is currently open. 
williamr@2: 	 * The MIDI engine is currently processing midi events. 
williamr@2: 	 */
williamr@2: 	EMidiStateClosedEngaged, 
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * A MIDI resource is open and primed but not playing. 
williamr@2: 	 * The MIDI engine is currently processing MIDI events. 
williamr@2: 	 * The transition to this state is only possible from EMidiStateOpenPlaying state, 
williamr@2: 	 * when the 'playback head' reaches the end of media data or the playback
williamr@2: 	 * stops due to stop time set.
williamr@2: 	 */
williamr@2: 	EMidiStateOpenEngaged,
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Active object utility class to allow MIDI events to be signalled asynchronously.
williamr@2: @see CMidiClientUtility::NewL().
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class MMidiClientUtilityObserver
williamr@2: 	{
williamr@2: public:
williamr@2:     /**
williamr@2:     A state change has occurred in the MIDI client utility.
williamr@2: 	
williamr@2:     @param aOldState 
williamr@2: 	       Old state.
williamr@2:     @param aNewState 
williamr@2: 	       New state.	 
williamr@2:     @param aTime 
williamr@2: 	       The time in microseconds at which playback stopped relative to the start of the MIDI resource.	
williamr@2:     @param aError	
williamr@2: 	       Error code.
williamr@2:     */
williamr@2: 	virtual void MmcuoStateChanged(TMidiState aOldState,TMidiState aNewState,const TTimeIntervalMicroSeconds& aTime,TInt aError) = 0;
williamr@2:     /**
williamr@2:     The MIDI resource has encountered a tempo change message in the MIDI data stream.
williamr@2: 	
williamr@2:     @param aMicroBeatsPerMinute 
williamr@2: 	       New tempo value in micro beats per minute (BPM*1000000).
williamr@2:     */
williamr@2: 	virtual void MmcuoTempoChanged(TInt aMicroBeatsPerMinute) = 0;
williamr@2:     /**
williamr@2:     The MIDI resource has encountered a volume change message in the MIDI data stream.
williamr@2: 	
williamr@2:     @param aChannel 
williamr@2: 	       Logical channel to which the message applies. 0 <= aChannel < ChannelsSupportedL().
williamr@2:     @param aVolumeInDecibels 
williamr@2: 	       New volume setting being used.
williamr@2:     */
williamr@2: 	virtual void MmcuoVolumeChanged(TInt aChannel,TReal32 aVolumeInDecibels) = 0;
williamr@2:     /**
williamr@2:     The MIDI resource has encountered a mute message in the MIDI data stream.
williamr@2: 	
williamr@2:     @param aChannel
williamr@2: 	       Logical channel to which the message applies. 0 <= aChannel < ChannelsSupportedL().
williamr@2:     @param aMuted 
williamr@2: 	       New muting state of the channel - ETrue is muted, EFalse is unmuted.
williamr@2:     */
williamr@2: 	virtual void MmcuoMuteChanged(TInt aChannel,TBool aMuted) = 0;
williamr@2:     /**
williamr@2:     Callback in response to a call to CMIDIClientUtility::SetSyncUpdateCallbackIntervalL().
williamr@2: 	By default there are no callbacks. Otherwise the callback is called at an interval set by the client. 
williamr@2: 	
williamr@2:     @param aMicroSeconds 
williamr@2: 	       Position in microseconds relative to the start of the resource - only set if 
williamr@2: 	       the sync update set function was called with the microseconds parameter set.
williamr@2:     @param aMicroBeats 
williamr@2: 	       Position in microbeats relative to the start of the resource - only set if
williamr@2: 	       the sync update set function was called with the microbeats parameter set and
williamr@2: 	       the microseconds parameter set to 0.
williamr@2:     */
williamr@2: 	virtual void MmcuoSyncUpdate(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats) = 0;
williamr@2:     /**
williamr@2:     A timed meta data entry has been found in the MIDI data stream, eg a timed song lyric in an SMF file.
williamr@2: 	
williamr@2:     @param aMetaDataEntryId 
williamr@2: 	       Index of the meta data entry - if this entry has not been encountere before,
williamr@2: 	       it will be added to the list of meta data entries. Previously encountered timed 
williamr@2: 		   entries still generate this callback. 
williamr@2:     @param aPosition
williamr@2: 	       Position in microseconds relative to the start of the MIDI resource that the MIDI
williamr@2: 	       meta data entry was found at.
williamr@2:     */
williamr@2: 	virtual void MmcuoMetaDataEntryFound(const TInt aMetaDataEntryId,const TTimeIntervalMicroSeconds& aPosition) = 0;
williamr@2:     /**
williamr@2:     A MIP message has been found in the MIDI data stream.
williamr@2: 	
williamr@2:     @param aMessage 
williamr@2: 	       Reference to an array of MIP message entries (logical {channel, MIP} value pairs) 
williamr@2: 	       contained in the message.
williamr@2:     */
williamr@2: 	virtual void MmcuoMipMessageReceived(const RArray<TMipMessageEntry>& aMessage) = 0;
williamr@2:     /**
williamr@2:     The polyphony of the MIDI engine has changed.
williamr@2: 	
williamr@2:     @param aNewPolyphony 
williamr@2: 	       The new polyphony value.
williamr@2:     */
williamr@2: 	virtual void MmcuoPolyphonyChanged(TInt aNewPolyphony) = 0;
williamr@2:     /**
williamr@2:     An instrument has been changed on a channel.
williamr@2: 	
williamr@2:     @param aChannel 
williamr@2: 	       Channel where the change of instrument occurred. 0 <= aChannel < ChannelsSupportedL().
williamr@2:     @param aBankId 
williamr@2: 	       Identifier of the bank that the instrument belongs to, occupying no more than 14 bits. 
williamr@2: 	       The bank ID is a concatenation of MIDI bank MSB and LSB values.
williamr@2:     @param aInstrumentId 
williamr@2: 	       Identifier of the instrument that has been changed. 0 <= aInstrumentId <= 127.
williamr@2:     */
williamr@2: 	virtual void MmcuoInstrumentChanged(TInt aChannel,TInt aBankId,TInt aInstrumentId) = 0;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Utility class to provide a standard client interface to a MIDI controller.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class CMidiClientUtility : public CBase
williamr@2: 	{
williamr@2: 	class CBody;
williamr@2: public:
williamr@2: 	IMPORT_C static CMidiClientUtility* NewL(MMidiClientUtilityObserver& aObserver,
williamr@2: 											 TInt aPriority = EMdaPriorityNormal,
williamr@4: 											 TInt aPref = EMdaPriorityPreferenceTimeAndQuality);
williamr@2: 	
williamr@2: 	// alternative NewL for selecting shared/separate controller heap(s)
williamr@2: 	IMPORT_C static CMidiClientUtility* NewL(MMidiClientUtilityObserver& aObserver,
williamr@2: 											 TInt aPriority,
williamr@4: 											 TInt aPref,
williamr@2: 											 TBool aUseSharedHeap);
williamr@2: 
williamr@2: 	/**	Destructor */
williamr@2: 	virtual ~CMidiClientUtility();
williamr@2: 	IMPORT_C TMidiState State() const;
williamr@2: 	IMPORT_C void OpenFile(const TDesC& aFileName);
williamr@2: 	IMPORT_C void OpenFile(const RFile& aFile);
williamr@2: 
williamr@2: 	IMPORT_C void OpenFile(const TMMSource& aSource);
williamr@2: 
williamr@2: 	IMPORT_C void OpenDes(const TDesC8& aDescriptor);
williamr@2: 	IMPORT_C void OpenUrl(const TDesC& aUrl,TInt aIapId = KUseDefaultIap,const TDesC8& aMimeType=KNullDesC8);
williamr@2: 	IMPORT_C void Close();
williamr@2: 	IMPORT_C void Play();
williamr@2: 	IMPORT_C void Stop(const TTimeIntervalMicroSeconds& aFadeOutDuration);
williamr@2: 	IMPORT_C void PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);
williamr@2: 	IMPORT_C void PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);
williamr@2: 	IMPORT_C void StopNotes(TInt aChannel);
williamr@2: 	IMPORT_C void NoteOnL(TInt aChannel,TInt aNote,TInt aVelocity);
williamr@2: 	IMPORT_C void NoteOffL(TInt aChannel,TInt aNote,TInt aVelocity);
williamr@2: 	IMPORT_C TInt PlaybackRateL() const;
williamr@2: 	IMPORT_C void SetPlaybackRateL(TInt aRate);
williamr@2: 	IMPORT_C TInt MaxPlaybackRateL() const;
williamr@2: 	IMPORT_C TInt MinPlaybackRateL() const;
williamr@2: 	IMPORT_C TInt TempoMicroBeatsPerMinuteL() const;
williamr@2: 	IMPORT_C void SetTempoL(TInt aMicroBeatsPerMinute);
williamr@2: 	IMPORT_C TInt PitchTranspositionCentsL() const;
williamr@2: 	IMPORT_C TInt SetPitchTranspositionL(TInt aCents);
williamr@2: 	IMPORT_C TTimeIntervalMicroSeconds DurationMicroSecondsL() const;
williamr@2: 	IMPORT_C TInt64 DurationMicroBeatsL() const;
williamr@2: 	IMPORT_C TInt NumTracksL() const;
williamr@2: 	IMPORT_C void SetTrackMuteL(TInt aTrack,TBool aMuted) const;
williamr@2: 	IMPORT_C const TDesC8& MimeTypeL();
williamr@2: 	IMPORT_C TTimeIntervalMicroSeconds PositionMicroSecondsL() const;
williamr@2: 	IMPORT_C void SetPositionMicroSecondsL(const TTimeIntervalMicroSeconds& aPosition);
williamr@2: 	IMPORT_C TInt64 PositionMicroBeatsL() const;
williamr@2: 	IMPORT_C void SetPositionMicroBeatsL(TInt64 aMicroBeats);
williamr@2: 	IMPORT_C void SetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds& aMicroSeconds, TInt64 aMicroBeats=0);		
williamr@2: 	IMPORT_C TInt SendMessageL(const TDesC8& aMidiMessage);
williamr@2: 	IMPORT_C TInt SendMessageL(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime);
williamr@2: 	IMPORT_C void SendMipMessageL(const RArray<TMipMessageEntry>& aEntry);
williamr@2: 	IMPORT_C TInt NumberOfBanksL(TBool aCustom) const;
williamr@2: 	IMPORT_C TInt GetBankIdL(TBool aCustom,TInt aBankIndex) const;
williamr@2: 	IMPORT_C void LoadCustomBankL(const TDesC& aFileName,TInt& aBankCollectionIndex);
williamr@2: 	IMPORT_C void LoadCustomBankDataL(const TDesC8& aBankData,TInt& aBankCollectionIndex);
williamr@2: 	IMPORT_C void UnloadCustomBankL(TInt aBankCollectionIndex);
williamr@2: 	IMPORT_C TBool CustomBankLoadedL(TInt aBankCollectionIndex) const;
williamr@2: 	IMPORT_C void UnloadAllCustomBanksL();
williamr@2: 	IMPORT_C TInt NumberOfInstrumentsL(TInt aBankId,TBool aCustom) const;
williamr@2: 	IMPORT_C TInt GetInstrumentIdL(TInt aBankId,TBool aCustom,TInt aInstrumentIndex) const;
williamr@2: 	IMPORT_C HBufC* InstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) const;
williamr@2: 	IMPORT_C void GetInstrumentL(TInt aChannel, TInt& aInstrumentId, TInt& aBankId);
williamr@2: 	IMPORT_C void SetInstrumentL(TInt aChannel,TInt aBankId,TInt aInstrumentId);
williamr@2: 	IMPORT_C void LoadCustomInstrumentL(const TDesC& aFileName,TInt aFileBankId,TInt aFileInstrumentId,TInt aMemoryBankId,TInt aMemoryInstrumentId);
williamr@2: 	IMPORT_C void LoadCustomInstrumentDataL(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId);
williamr@2: 	IMPORT_C void UnloadCustomInstrumentL(TInt aCustomBankId,TInt aInstrumentId);
williamr@2: 	IMPORT_C HBufC* PercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) const;
williamr@2: 	IMPORT_C void StopTimeL(TTimeIntervalMicroSeconds& aStopTime) const;
williamr@2: 	IMPORT_C void SetStopTimeL(const TTimeIntervalMicroSeconds& aStopTime);
williamr@2: 	IMPORT_C void SetRepeatsL(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence);
williamr@2: 	IMPORT_C TInt GetRepeats() const;
williamr@2: 	IMPORT_C TInt PolyphonyL() const;
williamr@2: 	IMPORT_C void SetMaxPolyphonyL(TInt aMaxNotes);
williamr@2: 	IMPORT_C TInt ChannelsSupportedL() const;
williamr@2: 	IMPORT_C TReal32 ChannelVolumeL(TInt aChannel) const;
williamr@2: 	IMPORT_C TReal32 MaxChannelVolumeL() const;
williamr@2: 	IMPORT_C void SetChannelVolumeL(TInt aChannel,TReal32 aVolumeInDecibels);
williamr@2: 	IMPORT_C void SetChannelMuteL(TInt aChannel,TBool aMuted);
williamr@2: 	IMPORT_C TInt VolumeL() const;
williamr@2: 	IMPORT_C TInt MaxVolumeL() const;
williamr@2: 	IMPORT_C void SetVolumeL(TInt aVolume);
williamr@2: 	IMPORT_C void SetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration);
williamr@2: 	IMPORT_C TInt GetBalanceL() const;
williamr@2: 	IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);
williamr@4: 	IMPORT_C void SetPriorityL(TInt aPriority, TInt aPref);
williamr@2: 	IMPORT_C TInt NumberOfMetaDataEntriesL() const;
williamr@2: 	IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aMetaDataIndex) const;
williamr@2: /**
williamr@2:  * @deprecated SetBankL is deprecated due to Mobile XMF specification requirement that user instruments (custom instruments) override standard instruments.
williamr@2:  */
williamr@2: 	IMPORT_C void SetBankL(TBool aCustom);
williamr@2: 	IMPORT_C TBool IsTrackMuteL(TInt aTrack) const;
williamr@2: 	IMPORT_C TBool IsChannelMuteL(TInt aChannel) const;
williamr@2: 	IMPORT_C void CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom);
williamr@2: 	IMPORT_C void CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2);
williamr@2: 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus);
williamr@2: 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus);
williamr@2: 	IMPORT_C TInt MaxPolyphonyL() const;
williamr@2: 
williamr@2: 	IMPORT_C MMMFDRMCustomCommand* GetDRMCustomCommand();
williamr@2: 	
williamr@2: private:
williamr@2: 	/**
williamr@2: 	 * a pointer to the implementation.
williamr@2: 	 */
williamr@2: 	CBody* iBody;	
williamr@2: 	friend class CBody;
williamr@2: 	}; 
williamr@2: 
williamr@2: #endif