test: epoc32/include/midiclientutility.h@837f303aceeb

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

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    16 #ifndef __MIDICLIENTUTILITY_H__

    17 #define __MIDICLIENTUTILITY_H__

    19 #include <e32std.h>

    20 #include <e32base.h>

    21 #include <bamdesca.h>

    22 #include <mmf/common/mmfcontroller.h>

    23 #include <mmf/common/mmfstandardcustomcommands.h>

    24 #include <mmf/common/mmfdrmcustomcommands.h>

    25 #include <mmf/common/mmfmididatacommon.h>

    28 /**

    29 General utility class to hold instrument information.

    31 @publishedAll

    32 @released

    33 */

    34 class TInstrumentInfo

    35 	{

    36 public:

    37 	/**

    38 	 *Identifier of sound bank to reference.

    39 	 */

    40 	TInt iBankId;

    42 	/**

    43 	 * Specifies whether to reference a custom or standard sound bank.

    44 	 */

    45 	TBool iCustom;

    47 	/**

    48 	 * Identifier of specified instrument.

    49 	 */

    50 	TInt iInstrumentId;

    51 	};

    53 /**

    54 Defines the state of the MIDI client utility with regard to the MIDI resource.

    56 @publishedAll

    57 @released

    58 */

    59 enum TMidiState

    60 	{

    61 	/**

    62 	 * No MIDI resource is currently open.

    63 	 * The MIDI engine is not processing midi events.

    64 	 */

    65 	EMidiStateClosedDisengaged,

    68 	/**

    69 	 * A MIDI resource is open and primed but not playing.

    70 	 * The MIDI engine is not processing midi events.

    71 	 */

    72 	EMidiStateOpenDisengaged,

    74 	/**

    75 	 * A MIDI resource is open and currently playing.

    76 	 * The MIDI engine is currently processing midi events.

    77 	 */

    78 	EMidiStateOpenPlaying,

    80 	/**

    81 	 * Not able to play full SP-MIDI or DLS content, but attempting best-effort playback.

    82 	 */

    83 	EMidiStatePlaybackIncompatible,

    85 	/**

    86 	 * Due to system resource constraints and SP-MIDI content constraints,

    87 	 * there is no audible MIDI content during playback currently.

    88 	 * The situation may change if resources are freed later.

    89 	 */

    90 	EMidiStatePlaybackSilent,

    92 	/**

    93 	 * No MIDI resource is currently open.

    94 	 * The MIDI engine is currently processing midi events.

    95 	 */

    96 	EMidiStateClosedEngaged,

    98 	/**

    99 	 * A MIDI resource is open and primed but not playing.

   100 	 * The MIDI engine is currently processing MIDI events.

   101 	 * The transition to this state is only possible from EMidiStateOpenPlaying state,

   102 	 * when the 'playback head' reaches the end of media data or the playback

   103 	 * stops due to stop time set.

   104 	 */

   105 	EMidiStateOpenEngaged,

   106 	};

   108 /**

   109 Active object utility class to allow MIDI events to be signalled asynchronously.

   110 @see CMidiClientUtility::NewL().

   112 @publishedAll

   113 @released

   114 */

   115 class MMidiClientUtilityObserver

   116 	{

   117 public:

   118     /**

   119     A state change has occurred in the MIDI client utility.

   121     @param aOldState

   122 	       Old state.

   123     @param aNewState

   124 	       New state.

   125     @param aTime

   126 	       The time in microseconds at which playback stopped relative to the start of the MIDI resource.

   127     @param aError

   128 	       Error code.

   129     */

   130 	virtual void MmcuoStateChanged(TMidiState aOldState,TMidiState aNewState,const TTimeIntervalMicroSeconds& aTime,TInt aError) = 0;

   131     /**

   132     The MIDI resource has encountered a tempo change message in the MIDI data stream.

   134     @param aMicroBeatsPerMinute

   135 	       New tempo value in micro beats per minute (BPM*1000000).

   136     */

   137 	virtual void MmcuoTempoChanged(TInt aMicroBeatsPerMinute) = 0;

   138     /**

   139     The MIDI resource has encountered a volume change message in the MIDI data stream.

   141     @param aChannel

   142 	       Logical channel to which the message applies. 0 <= aChannel < ChannelsSupportedL().

   143     @param aVolumeInDecibels

   144 	       New volume setting being used.

   145     */

   146 	virtual void MmcuoVolumeChanged(TInt aChannel,TReal32 aVolumeInDecibels) = 0;

   147     /**

   148     The MIDI resource has encountered a mute message in the MIDI data stream.

   150     @param aChannel

   151 	       Logical channel to which the message applies. 0 <= aChannel < ChannelsSupportedL().

   152     @param aMuted

   153 	       New muting state of the channel - ETrue is muted, EFalse is unmuted.

   154     */

   155 	virtual void MmcuoMuteChanged(TInt aChannel,TBool aMuted) = 0;

   156     /**

   157     Callback in response to a call to CMIDIClientUtility::SetSyncUpdateCallbackIntervalL().

   158 	By default there are no callbacks. Otherwise the callback is called at an interval set by the client.

   160     @param aMicroSeconds

   161 	       Position in microseconds relative to the start of the resource - only set if

   162 	       the sync update set function was called with the microseconds parameter set.

   163     @param aMicroBeats

   164 	       Position in microbeats relative to the start of the resource - only set if

   165 	       the sync update set function was called with the microbeats parameter set and

   166 	       the microseconds parameter set to 0.

   167     */

   168 	virtual void MmcuoSyncUpdate(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats) = 0;

   169     /**

   170     A timed meta data entry has been found in the MIDI data stream, eg a timed song lyric in an SMF file.

   172     @param aMetaDataEntryId

   173 	       Index of the meta data entry - if this entry has not been encountere before,

   174 	       it will be added to the list of meta data entries. Previously encountered timed

   175 		   entries still generate this callback.

   176     @param aPosition

   177 	       Position in microseconds relative to the start of the MIDI resource that the MIDI

   178 	       meta data entry was found at.

   179     */

   180 	virtual void MmcuoMetaDataEntryFound(const TInt aMetaDataEntryId,const TTimeIntervalMicroSeconds& aPosition) = 0;

   181     /**

   182     A MIP message has been found in the MIDI data stream.

   184     @param aMessage

   185 	       Reference to an array of MIP message entries (logical {channel, MIP} value pairs)

   186 	       contained in the message.

   187     */

   188 	virtual void MmcuoMipMessageReceived(const RArray<TMipMessageEntry>& aMessage) = 0;

   189     /**

   190     The polyphony of the MIDI engine has changed.

   192     @param aNewPolyphony

   193 	       The new polyphony value.

   194     */

   195 	virtual void MmcuoPolyphonyChanged(TInt aNewPolyphony) = 0;

   196     /**

   197     An instrument has been changed on a channel.

   199     @param aChannel

   200 	       Channel where the change of instrument occurred. 0 <= aChannel < ChannelsSupportedL().

   201     @param aBankId

   202 	       Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.

   203 	       The bank ID is a concatenation of MIDI bank MSB and LSB values.

   204     @param aInstrumentId

   205 	       Identifier of the instrument that has been changed. 0 <= aInstrumentId <= 127.

   206     */

   207 	virtual void MmcuoInstrumentChanged(TInt aChannel,TInt aBankId,TInt aInstrumentId) = 0;

   208 	};

   211 /**

   212 Utility class to provide a standard client interface to a MIDI controller.

   214 @publishedAll

   215 @released

   216 */

   217 class CMidiClientUtility : public CBase

   218 	{

   219 	class CBody;

   220 public:

   221 	IMPORT_C static CMidiClientUtility* NewL(MMidiClientUtilityObserver& aObserver,

   222 											 TInt aPriority = EMdaPriorityNormal,

   223 											 TInt aPref = EMdaPriorityPreferenceTimeAndQuality);

   225 	// alternative NewL for selecting shared/separate controller heap(s)

   226 	IMPORT_C static CMidiClientUtility* NewL(MMidiClientUtilityObserver& aObserver,

   227 											 TInt aPriority,

   228 											 TInt aPref,

   229 											 TBool aUseSharedHeap);

   231 	/**	Destructor */

   232 	virtual ~CMidiClientUtility();

   233 	IMPORT_C TMidiState State() const;

   234 	IMPORT_C void OpenFile(const TDesC& aFileName);

   235 	IMPORT_C void OpenFile(const RFile& aFile);

   237 	IMPORT_C void OpenFile(const TMMSource& aSource);

   239 	IMPORT_C void OpenDes(const TDesC8& aDescriptor);

   240 	IMPORT_C void OpenUrl(const TDesC& aUrl,TInt aIapId = KUseDefaultIap,const TDesC8& aMimeType=KNullDesC8);

   241 	IMPORT_C void Close();

   242 	IMPORT_C void Play();

   243 	IMPORT_C void Stop(const TTimeIntervalMicroSeconds& aFadeOutDuration);

   244 	IMPORT_C void PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);

   245 	IMPORT_C void PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);

   246 	IMPORT_C void StopNotes(TInt aChannel);

   247 	IMPORT_C void NoteOnL(TInt aChannel,TInt aNote,TInt aVelocity);

   248 	IMPORT_C void NoteOffL(TInt aChannel,TInt aNote,TInt aVelocity);

   249 	IMPORT_C TInt PlaybackRateL() const;

   250 	IMPORT_C void SetPlaybackRateL(TInt aRate);

   251 	IMPORT_C TInt MaxPlaybackRateL() const;

   252 	IMPORT_C TInt MinPlaybackRateL() const;

   253 	IMPORT_C TInt TempoMicroBeatsPerMinuteL() const;

   254 	IMPORT_C void SetTempoL(TInt aMicroBeatsPerMinute);

   255 	IMPORT_C TInt PitchTranspositionCentsL() const;

   256 	IMPORT_C TInt SetPitchTranspositionL(TInt aCents);

   257 	IMPORT_C TTimeIntervalMicroSeconds DurationMicroSecondsL() const;

   258 	IMPORT_C TInt64 DurationMicroBeatsL() const;

   259 	IMPORT_C TInt NumTracksL() const;

   260 	IMPORT_C void SetTrackMuteL(TInt aTrack,TBool aMuted) const;

   261 	IMPORT_C const TDesC8& MimeTypeL();

   262 	IMPORT_C TTimeIntervalMicroSeconds PositionMicroSecondsL() const;

   263 	IMPORT_C void SetPositionMicroSecondsL(const TTimeIntervalMicroSeconds& aPosition);

   264 	IMPORT_C TInt64 PositionMicroBeatsL() const;

   265 	IMPORT_C void SetPositionMicroBeatsL(TInt64 aMicroBeats);

   266 	IMPORT_C void SetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds& aMicroSeconds, TInt64 aMicroBeats=0);

   267 	IMPORT_C TInt SendMessageL(const TDesC8& aMidiMessage);

   268 	IMPORT_C TInt SendMessageL(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime);

   269 	IMPORT_C void SendMipMessageL(const RArray<TMipMessageEntry>& aEntry);

   270 	IMPORT_C TInt NumberOfBanksL(TBool aCustom) const;

   271 	IMPORT_C TInt GetBankIdL(TBool aCustom,TInt aBankIndex) const;

   272 	IMPORT_C void LoadCustomBankL(const TDesC& aFileName,TInt& aBankCollectionIndex);

   273 	IMPORT_C void LoadCustomBankDataL(const TDesC8& aBankData,TInt& aBankCollectionIndex);

   274 	IMPORT_C void UnloadCustomBankL(TInt aBankCollectionIndex);

   275 	IMPORT_C TBool CustomBankLoadedL(TInt aBankCollectionIndex) const;

   276 	IMPORT_C void UnloadAllCustomBanksL();

   277 	IMPORT_C TInt NumberOfInstrumentsL(TInt aBankId,TBool aCustom) const;

   278 	IMPORT_C TInt GetInstrumentIdL(TInt aBankId,TBool aCustom,TInt aInstrumentIndex) const;

   279 	IMPORT_C HBufC* InstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) const;

   280 	IMPORT_C void GetInstrumentL(TInt aChannel, TInt& aInstrumentId, TInt& aBankId);

   281 	IMPORT_C void SetInstrumentL(TInt aChannel,TInt aBankId,TInt aInstrumentId);

   282 	IMPORT_C void LoadCustomInstrumentL(const TDesC& aFileName,TInt aFileBankId,TInt aFileInstrumentId,TInt aMemoryBankId,TInt aMemoryInstrumentId);

   283 	IMPORT_C void LoadCustomInstrumentDataL(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId);

   284 	IMPORT_C void UnloadCustomInstrumentL(TInt aCustomBankId,TInt aInstrumentId);

   285 	IMPORT_C HBufC* PercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) const;

   286 	IMPORT_C void StopTimeL(TTimeIntervalMicroSeconds& aStopTime) const;

   287 	IMPORT_C void SetStopTimeL(const TTimeIntervalMicroSeconds& aStopTime);

   288 	IMPORT_C void SetRepeatsL(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence);

   289 	IMPORT_C TInt GetRepeats() const;

   290 	IMPORT_C TInt PolyphonyL() const;

   291 	IMPORT_C void SetMaxPolyphonyL(TInt aMaxNotes);

   292 	IMPORT_C TInt ChannelsSupportedL() const;

   293 	IMPORT_C TReal32 ChannelVolumeL(TInt aChannel) const;

   294 	IMPORT_C TReal32 MaxChannelVolumeL() const;

   295 	IMPORT_C void SetChannelVolumeL(TInt aChannel,TReal32 aVolumeInDecibels);

   296 	IMPORT_C void SetChannelMuteL(TInt aChannel,TBool aMuted);

   297 	IMPORT_C TInt VolumeL() const;

   298 	IMPORT_C TInt MaxVolumeL() const;

   299 	IMPORT_C void SetVolumeL(TInt aVolume);

   300 	IMPORT_C void SetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration);

   301 	IMPORT_C TInt GetBalanceL() const;

   302 	IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);

   303 	IMPORT_C void SetPriorityL(TInt aPriority, TInt aPref);

   304 	IMPORT_C TInt NumberOfMetaDataEntriesL() const;

   305 	IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aMetaDataIndex) const;

   306 /**

   307  * @deprecated SetBankL is deprecated due to Mobile XMF specification requirement that user instruments (custom instruments) override standard instruments.

   308  */

   309 	IMPORT_C void SetBankL(TBool aCustom);

   310 	IMPORT_C TBool IsTrackMuteL(TInt aTrack) const;

   311 	IMPORT_C TBool IsChannelMuteL(TInt aChannel) const;

   312 	IMPORT_C void CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom);

   313 	IMPORT_C void CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2);

   314 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus);

   315 	IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus);

   316 	IMPORT_C TInt MaxPolyphonyL() const;

   318 	IMPORT_C MMMFDRMCustomCommand* GetDRMCustomCommand();

   320 private:

   321 	/**

   322 	 * a pointer to the implementation.

   323 	 */

   324 	CBody* iBody;

   325 	friend class CBody;

   326 	};

   328 #endif

author	William Roberts <williamr@symbian.org>
	Wed, 31 Mar 2010 12:33:34 +0100
branch	Symbian3
changeset 4	837f303aceeb
parent 2	2fe1408b6811
permissions	-rw-r--r--