test: epoc32/include/mmf/common/midistandardcustomcommands.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 __MIDISTANDARDCUSTOMCOMMANDS_H__

    17 #define __MIDISTANDARDCUSTOMCOMMANDS_H__

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

    20 #include <midiclientutility.h>

    21 #include <mmf/common/mmfmidi.h>

    23 /**

    24 Interface UID for the Midi Controller API.

    26 @publishedAll

    27 @released

    28 */

    29 const TUid KUidInterfaceMidi = { 0x101F945C };

    31 /**

    32 Describe a MIDI event.

    33 Contains a UID to define the actual event type, and an integer to define the event code.

    35 @publishedAll

    36 @released

    37 */

    38 class CMMFMidiEvent: public CBase

    39 	{

    40 public:

    41 	IMPORT_C CMMFMidiEvent(TUid aEventType, TInt aErrorCode);

    42 	IMPORT_C CMMFMidiEvent();

    43 	IMPORT_C ~CMMFMidiEvent();

    44 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

    45 	IMPORT_C void InternalizeL(RReadStream& aStream);

    46 	IMPORT_C void CopyL(const CMMFMidiEvent& aOther);

    47 	/**

    48     @internalTechnology

    49     */

    50 	void ZeroMembers();

    51 public:

    52    /**

    53     * A UID to define the type of MIDI event.

    54     */

    55 	TUid iEventType;

    56    /**

    57     * The error code associated with the MIDI event.

    58     */

    59 	TInt iErrorCode;

    60    /**

    61     * Old state of the MIDI client utility object.

    62     */

    63 	TMidiState iOldState;

    64    /**

    65     * Current state of the MIDI client utility object.

    66     */

    67 	TMidiState iNewState;

    68    /**

    69     * General purpose time stamp in microseconds.

    70     */

    71 	TTimeIntervalMicroSeconds iMicroSeconds;

    72    /**

    73     * General purpose time stamp in micro beats per minute.

    74     */

    75 	TInt64 iMicroBeats;

    76    /**

    77     * Channel

    78     */

    79 	TInt iChannel;

    80    /**

    81     * Volume in decibel of a logical channel.

    82     */

    83 	TReal32 iVolumeInDecibels;

    84    /**

    85     * Mute state of a track or of a channel.

    86     */

    87 	TBool iMute;

    88    /**

    89     * Meta data entry.

    90 	* Client will retrieve meta data entry by calling GetMetaDataEntryL()

    91 	* using this TInt to indicate which meta data entry to retrieve.

    92     */

    93 	TInt iMetaDataEntryId;

    94    /**

    95     * Array of logical {channel, MIP} value pairs.

    96     */

    97 	RArray<TMipMessageEntry> iMipMessage;

    98    /**

    99     * Polyphony of the MIDI engine.

   100     */

   101 	TInt iPolyphony;

   102    /**

   103     * Identifier of a bank occupying, at most, 14 bits.

   104     */

   105 	TInt iBankId;

   106    /**

   107     * Identifier of a specific instrument.

   108     */

   109 	TInt iInstrumentId;

   110    /**

   111     * Tempo value in micro beats per minute.

   112     */

   113 	TInt iTempoMicroBeats;

   114 	};

   116 /**

   117 Client class to access functionality specific to a MIDI controller.

   118 The class uses the custom command function of the controller plugin, and removes the necessity

   119 for the client to formulate the custom commands.

   121 @publishedAll

   122 @released

   123 */

   124 class RMidiControllerCustomCommands : public RMMFCustomCommandsBase

   125 	{

   126 public:

   127 	IMPORT_C RMidiControllerCustomCommands(RMMFController& aController);

   128 	IMPORT_C TInt SetPositionMicroBeats(TInt64 aMicroBeats) const;

   129 	IMPORT_C TInt PositionMicroBeats(TInt64& aMicroBeats) const;

   130 	IMPORT_C TInt PlayNote(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);

   131 	IMPORT_C TInt PlayNote(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime, const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);

   132 	IMPORT_C TInt StopNotes(TInt aChannel);

   133 	IMPORT_C TInt NoteOn(TInt aChannel,TInt aNote,TInt aVelocity);

   134 	IMPORT_C TInt NoteOff(TInt aChannel,TInt aNote,TInt aVelocity);

   135 	IMPORT_C TInt PlaybackRate(TInt& aPlayBackRate) const;

   136 	IMPORT_C TInt SetPlaybackRate(TInt aPlayBackRate);

   137 	IMPORT_C TInt MaxPlaybackRate(TInt& aMaxRate) const;

   138 	IMPORT_C TInt MinPlaybackRate(TInt& aMinRate) const;

   139 	IMPORT_C TInt TempoMicroBeatsPerMinute(TInt& aMicroBeatsPerMinute) const;

   140 	IMPORT_C TInt SetTempo(TInt aMicroBeatsPerMinute);

   141 	IMPORT_C TInt PitchTranspositionCents(TInt& aPitch) const;

   142 	IMPORT_C TInt SetPitchTransposition(TInt aCents, TInt& aCentsApplied);

   143 	IMPORT_C TInt DurationMicroBeats(TInt64& aDuration) const;

   144 	IMPORT_C TInt NumTracks(TInt& aTracks) const;

   145 	IMPORT_C TInt SetTrackMute(TInt aTrack, TBool aMuted) const;

   146 	IMPORT_C TInt MimeType(TDes8& aMimeType) const;

   147 	IMPORT_C TInt SetSyncUpdateCallbackInterval(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats=0);

   148 	IMPORT_C TInt SendMessage(const TDesC8& aMidiMessage, TInt& aBytes);

   149 	IMPORT_C TInt SendMessage(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime, TInt& aBytes);

   150 	IMPORT_C TInt SendMipMessage(const RArray<TMipMessageEntry>& aEntry);

   151 	IMPORT_C TInt NumberOfBanks(TBool aCustom, TInt& aNumBanks) const;

   152 	IMPORT_C TInt GetBankId(TBool aCustom, TInt aBankIndex, TInt& aBankId) const;

   153 	IMPORT_C TInt LoadCustomBank(const TDesC& aFileName,TInt& aBankId);

   154 	IMPORT_C TInt LoadCustomBankData(const TDesC8& aBankData,TInt& aBankId);

   155 	IMPORT_C TInt UnloadCustomBank(TInt aBankId);

   156 	IMPORT_C TInt CustomBankLoaded(TInt aBankId, TBool& aBankLoaded) const;

   157 	IMPORT_C TInt UnloadAllCustomBanks();

   158 	IMPORT_C TInt NumberOfInstruments(TInt aBankId, TBool aCustom, TInt& aNumInstruments) const;

   159 	IMPORT_C TInt GetInstrumentId(TInt aBankId,TBool aCustom,TInt aInstrumentIndex, TInt& aInstrumentId) const;

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

   161 	IMPORT_C TInt SetInstrument(TInt aChannel,TInt aBankId,TInt aInstrumentId);

   162 	IMPORT_C TInt LoadCustomInstrument(const TDesC& aFileName, TInt aFileBankId, TInt aFileInstrumentId, TInt aMemoryBankId, TInt aMemoryInstrumentId);

   163 	IMPORT_C TInt LoadCustomInstrumentData(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId);

   164 	IMPORT_C TInt UnloadCustomInstrument(TInt aCustomBankId,TInt aInstrumentId);

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

   166 	IMPORT_C TInt StopTime(TTimeIntervalMicroSeconds& aStopTime) const;

   167 	IMPORT_C TInt SetStopTime(const TTimeIntervalMicroSeconds& aStopTime) const;

   168 	IMPORT_C TInt Polyphony(TInt& aNumNotes) const;

   169 	IMPORT_C TInt ChannelsSupported(TInt& aChannels) const;

   170 	IMPORT_C TInt ChannelVolume(TInt aChannel, TReal32& aChannelVol) const;

   171 	IMPORT_C TInt MaxChannelVolume(TReal32& aMaxVol) const;

   172 	IMPORT_C TInt SetChannelVolume(TInt aChannel,TReal32 aVolume);

   173 	IMPORT_C TInt SetChannelMute(TInt aChannel,TBool aMuted);

   174 	IMPORT_C TInt Volume(TInt& aVolume) const;

   175 	IMPORT_C TInt MaxVolume(TInt& aMaxVolume) const;

   176 	IMPORT_C TInt SetVolume(TInt aVolume);

   177 	IMPORT_C TInt SetVolumeRamp(const TTimeIntervalMicroSeconds& aRampDuration);

   178 	IMPORT_C TInt GetBalance(TInt& aBalance) const;

   179 	IMPORT_C TInt SetBalance(TInt aBalance);

   180 	IMPORT_C TInt SetMaxPolyphony(TInt aMaxNotes);

   181 	IMPORT_C TInt GetRepeats(TInt& aNumRepeats) const;

   182 	IMPORT_C TInt SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence);

   183  	IMPORT_C TInt SetBank(TBool aCustom);

   184 	IMPORT_C TInt IsTrackMute(TInt aTrack, TBool& aTrackMute) const;

   185 	IMPORT_C TInt IsChannelMute(TInt aChannel, TBool& aChannelMute) const;

   186 	IMPORT_C TInt GetInstrument(TInt aChannel, TInt& aInstrumentId, TInt& aBankId);

   187 	IMPORT_C TInt Close();

   188 	IMPORT_C TInt Stop(const TTimeIntervalMicroSeconds& aFadeOutDuration);

   189 	IMPORT_C void ReceiveEvents(TPckgBuf<TInt>& aEventSize, TRequestStatus& aStatus);

   190 	IMPORT_C TInt RetrieveEvent(TDes8& aMidiEventPckg);

   191 	IMPORT_C TInt CancelReceiveEvents();

   192 	IMPORT_C TInt MaxPolyphony(TInt& aNumNotes) const;

   193 	};

   196 /**

   197 Mixin class to be derived from by controller plugins wishing

   198 to support the MIDI controller custom commands.

   200 @publishedAll

   201 @released

   202 */

   203 class MMidiCustomCommandImplementor

   204 	{

   205 public:

   206     /**

   207     Change the position of the currently playing MIDI resource to the given position.

   208     May be called whenever a MIDI resource is open.

   210     @param aMicroBeats

   211 	       Metrical position to move to. Clamped to (0, DurationMicroBeats()).

   212     */

   213 	virtual void  MmcSetPositionMicroBeatsL(TInt64 aMicroBeats) = 0;

   214     /**

   215     Gets the current metrical position of the MIDI resource being played

   217     @param aMicroBeats

   218 	       (BPM*1000000) relative to the start of the resource

   219     */

   220 	virtual void  MmcPositionMicroBeatsL(TInt64& aMicroBeats) = 0;

   221     /**

   222     Synchronous function to play a single note.

   223     Multiple calls to this function will be accommodated as far as the MIDI engine can

   224     manage. The same functionality could be implemented using the SendMessage function

   226     @param aChannel

   227 	       Logical channel to play note on. 0 <= aChannel <= 15.

   228     @param aNote

   229 	       Note to play. 0 <= aNote <= 127

   230     @param aDuration

   231 	       Length of time to play note for.

   232     @param aNoteOnVelocity

   233 	       Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.

   234     @param aNoteOffVelocity

   235 	       Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.

   236     */

   237 	virtual void  MmcPlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity) = 0;

   238     /**

   239     Synchronous function to play a single note at a specified time.

   240     Multiple calls to this function will be accommodated as far as the MIDI engine can

   241     manage. The same functionality could be implemented using the SendMessage function

   243     @param aChannel

   244 	       Logical channel to play note on. 0 <= aChannel <= 15.

   245     @param aNote

   246 	       Note to play. 0 <= aNote <= 127

   247     @param aStartTime

   248 	       Specifies the time at which to start playing the note, relative to the MIDI

   249 		   resource playing time or the time elapsed since Play() was called if no resource is present.

   250     @param aDuration

   251 	       Length of time to play note for.

   252     @param aNoteOnVelocity

   253 	       Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.

   254     @param aNoteOffVelocity

   255 	       Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.

   256     */

   257 	virtual void  MmcPlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime, const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity) = 0;

   258     /**

   259     Stops the playback of all notes on the given channel,

   260     by means of an All Notes Off MIDI message

   262     @param aChannel

   263 	       Logical channel to stop notes on. 0 <= aChannel <= 15

   264     */

   265 	virtual void  MmcStopNotesL(TInt aChannel) = 0;

   266     /**

   267     Synchronous function to commence playback of a note.

   268     Multiple calls to this function will be accommodated as far as the MIDI engine can manage

   270     @param aChannel

   271 	       Logical channel to play note on. 0 <= aChannel <= 15.

   272     @param aNote

   273 	       Note to play. 0 <= aNote <= 127.

   274     @param aVelocity

   275 	       Velocity with which to start the note. The legal integer range

   276 		   is 0 <= aVelocity <= 127, but the value zero actually causes the

   277 		   message to be interpreted as a Note Off message instead of a Note On.

   278     */

   279 	virtual void  MmcNoteOnL(TInt aChannel,TInt aNote,TInt aVelocity) = 0;

   280     /**

   281     Synchronous function to terminate playback of a note.

   282     If no corresponding note is found then no error is raised

   284     @param aChannel

   285 	       Logical channel on which the note is playing. 0 <= aChannel <= 15.

   286     @param aNote

   287 	       Note to terminate. 0 <= aNote <= 127.

   288     @param aVelocity

   289 	       Velocity with which to stop the note. 0 <= aVelocity <= 127.

   290            There is no standard behaviour corresponding with note off velocity.

   291     */

   292 	virtual void  MmcNoteOffL(TInt aChannel,TInt aNote,TInt aVelocity) = 0;

   293     /**

   294     Gets the current playback rate factor of the currently open MIDI resource.

   295     The playback rate is independent from tempo,

   296     i.e., it can be used to give an overall speed factor for playback.

   298     @param aPlayBackRate

   299 	       Current playback rate in percent times 1000, i.e., 100000 means original

   300 		   playback speed, 200000 means double speed, and 50000 means half speed playback.

   301     */

   302 	virtual void  MmcPlaybackRateL(TInt& aPlayBackRate) = 0;

   303     /**

   304     Sets the playback rate for the playback of the current MIDI resource.

   305     The playback rate is independent from tempo,

   306     i.e., it can be used to give an overall speed factor for playback.

   307     May be called whether playback is in progress or not.

   309     @param aPlayBackRate

   310 	       Playback rate in percent times 1000, i.e., 100000 means original playback speed,

   311 		   200000 means double speed, and 50000 means half speed playback.

   312     */

   313 	virtual void  MmcSetPlaybackRateL(TInt aPlayBackRate) = 0;

   314     /**

   315     Gets the maximum playback rate in milli-percentage from the MIDI engine.

   316     @see SetPlaybackRate() for milli-percentage details.

   318     @param aMaxRate

   319 	       Playback rate supported by MIDI player.

   320     */

   321 	virtual void  MmcMaxPlaybackRateL(TInt& aMaxRate) = 0;

   322     /**

   323     Gets the minimum playback rate in milli-percentage from the MIDI engine.

   324     @see SetPlaybackRate() for milli-percentage details.

   326     @param aMinRate

   327 	       Minimum playback rate supported by MIDI player.

   328     */

   329 	virtual void  MmcMinPlaybackRateL(TInt& aMinRate) = 0;

   330     /**

   331     Gets the current tempo of the currently open MIDI resource. The tempo is independent

   332     from the playback rate, i.e., the resulting playback speed will be affected by both.

   334     @param  aMicroBeatsPerMinute

   335 	        Tempo at the current position of the currently open resource in microbeats

   336 			per minute, i.e. BPM * 1000000. Filled in by the controller framework.

   337     */

   338 	virtual void  MmcTempoMicroBeatsPerMinuteL(TInt& aMicroBeatsPerMinute) = 0;

   339     /**

   340     Sets the tempo at which the current MIDI resource should be played.

   341     May be called whether playback is in progress or not. The tempo is

   342 	independent from the playback rate, i.e., the resulting playback speed

   343 	will be affected by both.

   345     @param aMicroBeatsPerMinute

   346 	       Tempo in microbeats per minute (BPM*1000000) to set.

   347     */

   348 	virtual void  MmcSetTempoL(TInt aMicroBeatsPerMinute) = 0;

   349     /**

   350     Gets the pitch shift in use for the currently open MIDI resource.

   352     @param aPitch

   353 	       Shift in cents, i.e. semitones * 100. One octave equals 1200 cents.

   354     @return One of the system-wide error codes.

   355     */

   356 	virtual void  MmcPitchTranspositionCentsL(TInt& aPitch) = 0;

   357     /**

   358     Sets the pitch shift to apply to the currently open MIDI resource.

   359     May be called during playback.

   361     @param aCents

   362 	       Pitch shift in cents, i.e. semitones * 100. One octave equals 1200 cents.

   363     @param aCentsApplied

   364 	       Actual pitch shift applied - may differ from the requested value due

   365 		   to limitations of the MIDI engine.

   366     */

   367 	virtual void  MmcSetPitchTranspositionL(TInt aCents, TInt& aCentsApplied) = 0;

   368     /**

   369     Gets the length of the currently open MIDI resource in micro-beats

   371     @param aDuration

   372 	       Duration in microbeats (beats * 1000000).

   373     */

   374 	virtual void  MmcDurationMicroBeatsL(TInt64& aDuration) = 0;

   375     /**

   376     Gets the number of tracks present in the currently open MIDI resource.

   378     @param aTracks

   379 	       Number of tracks.

   380     */

   381 	virtual void  MmcNumTracksL(TInt& aTracks) = 0;

   382     /**

   383     Mutes or unmutes a particular track.

   385     @param aTrack

   386 	       Index of the track to mute - 0 <= aTrack < NumTracks().

   387     @param aMuted

   388 	       ETrue to mute the track, EFalse to unmute it.

   389     */

   390 	virtual void  MmcSetTrackMuteL(TInt aTrack, TBool aMuted) = 0;

   391     /**

   392     Gets the MIME type of the MIDI resource currently open.

   394     @param aMimeType

   395 	       Descriptor containing the MIDI mime type.

   396     */

   397 	virtual void  MmcMimeTypeL(TDes8& aMimeType) = 0;

   398     /**

   399     Sets the frequency at which MMIDIClientUtilityObserver::MmcuoSyncUpdateL() is called

   400     to allow other components to synchronise with playback of this MIDI resource.

   402     @param aMicroSeconds

   403 	       Temporal interval to callback at. Used in preference to aMicroBeats if both are set.

   404     @param aMicroBeats

   405 	       Metrical interval to callback at. Set both parameters to zero to cancel.

   406     */

   407 	virtual void  MmcSetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats=0) = 0;

   408     /**

   409     Sends a single MIDI message to the MIDI engine.

   411     @param aMidiMessage

   412 	       Descriptor containing the MIDI message data. If there are several

   413            MIDI messages in the buffer, only the first one is processed.

   414     @param aBytes

   415 	       Number of bytes of the message buffer actually processed.

   416     */

   417 	virtual void  MmcSendMessageL(const TDesC8& aMidiMessage, TInt& aBytes) = 0;

   418     /**

   419     Sends a single MIDI message, with time stamp, to the MIDI engine.

   421     @param aMidiMessage

   422 	       Descriptor containing the MIDI message data. If there are several

   423 		   MIDI messages in the buffer, only the first one is processed.

   424     @param aTime

   425 	       The time at which to execute the message, relative to the MIDI resource playing

   426            time or the time elapsed since Play() was called if no resource is present.

   427     @param aBytes

   428 	       Number of bytes of the message buffer actually processed.

   429     */

   430 	virtual void  MmcSendMessageL(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime, TInt& aBytes) = 0;

   431     /**

   432     Sends a mip message to the MIDI engine. This is a convenience function,

   433     because the same functionality could be achieved with the SendMessage() function.

   435     @param aEntry

   436 	       Array of logical {channel, MIP} value pairs to send, highest priority first.

   437     */

   438 	virtual void  MmcSendMipMessageL(const TArray<TMipMessageEntry>& aEntry) = 0;

   439     /**

   440     Gets the number of standard or custom sound banks currently available.

   442     @param aCustom

   443 	       Specifies whether to reference a custom or standard sound bank.

   444     @param aNumBanks

   445 	       Number of custom or standard sound banks available.

   446     */

   447 	virtual void  MmcNumberOfBanksL(TBool aCustom, TInt& aNumBanks) = 0;

   448     /**

   449     Gets the identifier of a sound bank. Bank identifier (aka bank number) is a

   450     14-bit value consisting of MIDI bank MSB and LSB values.

   452     @param  aCustom

   453             Specifies whether to reference a custom or standard sound bank.

   454     @param  aBankIndex

   455 	        Index of sound bank where 0 <= aBankIndex < NumberOfBanks().

   456     @param  aBankId

   457             Identifier of the specified bank occupying, at most, 14 bits.

   458     */

   459 	virtual void  MmcGetBankIdL(TBool aCustom, TInt aBankIndex, TInt& aBankId) = 0;

   460     /**

   461     Loads one or more custom sound banks from a file into memory for use.

   462     If several banks are loaded with consequent LoadCustomBanksL() function calls,

   463     the banks are combined if the bank sets have conflicting bank numbers.

   465     @param aFileName

   466 	       Name of the file containing the custom sound bank.

   467     @param aBankId

   468 	       Identifier of the custom sound bank loaded, occupying no more than 14 bits.

   469     */

   470 	virtual void  MmcLoadCustomBankL(const TDesC& aFileName,TInt& aBankId) = 0;

   471     /**

   472     Loads one or more custom sound banks from a descriptor into memory for use.

   473     If several banks are loaded with consequent LoadCustomBanksL() function calls,

   474     the banks are combined if the bank sets have conflicting bank numbers.

   476     @param aBankData

   477 	       Descriptor containing the custom sound bank.

   478     @param aBankId

   479 	       Identifier of the custom sound bank loaded, occupying no more than 14 bits.

   480     */

   481 	virtual void  MmcLoadCustomBankDataL(const TDesC8& aBankData,TInt& aBankId) = 0;

   482     /**

   483     Removes a custom sound bank from memory. Only valid for sound banks previously

   484 	loaded from file. Once unloaded the custom sound bank is no longer available for use.

   486     @param aBankId

   487 	       Identifier of the custom sound bank to unload,occupying no more than 14 bits.

   488     */

   489 	virtual void  MmcUnloadCustomBankL(TInt aBankId) = 0;

   490     /**

   491     Query if a bank has been loaded to the memory.

   493     @param aBankId

   494 	       Identifier of the custom sound bank to check if it's in memory or not.

   495     @param aBankLoaded

   496 	       ETrue if the specified bank is in memory, EFalse otherwise.

   497     */

   498 	virtual void  MmcCustomBankLoadedL(TInt aBankId, TBool& aBankLoaded) = 0;

   499     /**

   500     Removes all custom sound banks from memory.

   501     */

   502 	virtual void  MmcUnloadAllCustomBanksL() = 0;

   503     /**

   504     Gets the number of instruments available in a given sound bank.

   506     @param aBankId

   507 	       Identifier of sound bank to reference, occupying no more than 14 bits.

   508     @param aCustom

   509 	       Specifies whether to reference a custom or standard sound bank.

   510     @param aNumInstruments

   511 	       Count of the number of instruments available for the specified sound bank.

   512     */

   513 	virtual void  MmcNumberOfInstrumentsL(TInt aBankId, TBool aCustom, TInt& aNumInstruments) = 0;

   514     /**

   515     Gets the identifier of an instrument.

   517     @param aBankId

   518 	       Identifier of the sound bank to reference, occupying no more than 14 bits.

   519     @param aCustom

   520 	       Specifies whether to reference a custom or standard sound bank.

   521     @param aInstrumentIndex

   522 	       Index of the instrument to reference where 0 <= aInstrumentIndex < NumberOfInstrumentsL().

   523     @param aInstrumentId

   524 	       Identifier of specified instrument. This may differ from the index since the

   525 		   index simply enumerates the instruments, whereas identifiers may not be

   526 		   contiguous, especially where certain instruments correspond to General MIDI-defined

   527 		   instruments but not all instruments are present. Instrument identifiers are

   528 		   between 0 and 127 inclusive.

   529     */

   530 	virtual void  MmcGetInstrumentIdL(TInt aBankId,TBool aCustom,TInt aInstrumentIndex, TInt& aInstrumentId) = 0;

   531     /**

   532     Gets the name of the given instrument.

   534     @param  aBankId

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

   536     @param  aCustom

   537 	        Specifies whether to reference a custom or standard sound bank.

   538     @param  aInstrumentId

   539 	        Identifier of the instrument under scrutiny. 0 <= aInstrumentId <= 127.

   540     @return Buffer containing the name of the specified instrument.

   541             If it has no name then an empty descriptor is returned.

   542     */

   543 	virtual const TDesC& MmcInstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) = 0;

   544     /**

   545     Sets a logical channel to use the given instrument.

   547     @param aChannel

   548 	       Logical channel to set the instrument for. 0 <= aChannel <= 15.

   549     @param aBankId

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

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

   552     @param aInstrumentId

   553 	       Identifier of the instrument under scrutiny. 0 <= aInstrumentId <= 127.

   554     */

   555 	virtual void  MmcSetInstrumentL(TInt aChannel,TInt aBankId,TInt aInstrumentId) = 0;

   556     /**

   557     Loads an individual instrument from file into custom sound bank memory for use.

   558     The bank and instrument ids given in the file can be mapped into different bank

   559     and instrument ids in memory.

   561     @param aFileName

   562 	       Name of the file containing the instrument.

   563     @param aFileBankId

   564 	       Identifier of the bank in the file from which to load the instrument,

   565            occupying no more than 14 bits.

   566     @param aFileInstrumentId

   567 	       Identifier of the instrument to load. 0 <= aInstrumentId <= 127.

   568     @param aMemoryBankId

   569 	       Identifier of the custom bank in memory to load the instrument into,

   570            occupying no more than 14 bits.

   571     @param aMemoryInstrumentId

   572 	       Identifier of the instrument in memory to load the new instrument into.

   573 		   0 <= aInstrumentId <= 127.

   574     */

   575 	virtual void  MmcLoadCustomInstrumentL(const TDesC& aFileName, TInt aFileBankId, TInt aFileInstrumentId, TInt aMemoryBankId, TInt aMemoryInstrumentId) = 0;

   576     /**

   577     Loads an individual instrument from descriptor into custom sound bank memory for use.

   578     The bank and instrument ids given in the descriptor can be mapped into different bank

   579     and instrument ids in memory.

   581     @param aInstrumentData

   582 	       Descriptor containing the instrument.

   583     @param aBankDataId

   584 	       Identifier of the bank in the descriptor from which to load the instrument,

   585            occupying no more than 14 bits.

   586     @param aInstrumentDataId

   587 	       Identifier of the instrument to load. 0 <= aInstrumentId <= 127.

   588     @param aMemoryBankId

   589 	       Identifier of the custom bank in memory to load the instrument into,

   590            occupying no more than 14 bits.

   591     @param aMemoryInstrumentId

   592 	       Identifier of the instrument in memory to load the new instrument into.

   593 		   0 <= aInstrumentId <= 127.

   594     */

   595 	virtual void  MmcLoadCustomInstrumentDataL(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId) = 0;

   596     /**

   597     Removes an instrument from custom sound bank memory.

   598     Only valid for instruments previously loaded from file.

   599     Once unloaded the instrument is no longer available for use.

   601     @param aCustomBankId

   602 	       Identifier of the custom sound bank containing the instrument

   603            to unload, occupying no more than 14 bits.

   604     @param aInstrumentId

   605 	       Identifier of the instrument to unload. 0 <= aInstrumentId <= 127.

   606     */

   607 	virtual void  MmcUnloadCustomInstrumentL(TInt aCustomBankId,TInt aInstrumentId) = 0;

   608     /**

   609     Gets the name of a particular percussion key corresponding to a given note.

   611     @param aNote

   612 	       Note to query. 0 <= aNote <= 127.

   613     @param aBankId

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

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

   616     @param aCustom

   617 	       Specifies whether to reference a custom or standard sound bank.

   618     @param aInstrumentId

   619 	       Identifier of an instrument.

   620     @return Descriptor containing the name of the percussion key.

   621             If the key does not have a name then an empty descriptor is returned.

   622     */

   623 	virtual const TDesC& MmcPercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) = 0;

   624     /**

   625     Get the stop time currently set for the MIDI resource.

   627     @param aStopTime

   628 	       Time at which playback will stop, relative to the start of the resource.

   629     @return Descriptor containing the name of the percussion key. If the key

   630             does not have a name then an empty descriptor is returned.

   631     */

   632 	virtual void  MmcStopTimeL(TTimeIntervalMicroSeconds& aStopTime) = 0;

   633     /**

   634     Sets the stop time to use for the currently open MIDI resource

   636     @param aStopTime

   637 	       Time at which playback will stop, relative to the start of the resource.

   638            Clamped to 0 and the duration of the resource.

   639     */

   640 	virtual void  MmcSetStopTimeL(const TTimeIntervalMicroSeconds& aStopTime) = 0;

   641     /**

   642     Gets the number of currently active voices.

   644     @param aNumNotes

   645 	       The number of currently active voices.

   646     */

   647 	virtual void  MmcPolyphonyL(TInt& aNumNotes) = 0;

   648     /**

   649     Get the maximum number of logical channels supported by the MIDI engine.

   651     @param aChannels

   652 	       The maximum number of logical channels that the MIDI engine supports, 0 <= aChannels <=15.

   653     */

   654 	virtual void  MmcChannelsSupportedL(TInt& aChannels) = 0;

   655     /**

   656     Get the current volume setting of a logical channel.

   658     @param aChannel

   659 	       Logical channel to query. 0 <= aChannel <= 15.

   660     @param aChannelVol

   661 	       Volume currently set on the specified channel in decibels.

   662     */

   663 	virtual void  MmcChannelVolumeL(TInt aChannel, TReal32& aChannelVol) = 0;

   664     /**

   665     Gets the Maximum volume setting that may be applied to a logical channel.

   667     @param aMaxVol

   668 	       Maximum volume setting. Minimum value is -infinity dB, which is

   669 	       the smallest possible value that TReal32 supports.

   670     */

   671 	virtual void  MmcMaxChannelVolumeL(TReal32& aMaxVol) = 0;

   672     /**

   673     Set the volume of a channel.

   675     @param aChannel

   676 	       Logical channel to set the volume on. 0 <= aChannel <= 15.

   677     @param aVolume

   678 	       The channel volume can be set within a range. The minimum channel

   679 	       volume is -infinity dB, which is the smallest possible value that

   680 	       TReal32 supports while the maximum channel volume is set via MaxVolumeL()

   681 	       which represents the volume level in dB corresponding to the MIDI Channel

   682 	       Volume controller.

   683     */

   684 	virtual void  MmcSetChannelVolumeL(TInt aChannel,TReal32 aVolume) = 0;

   685     /**

   686     Set the muting state of a channel without changing its volume setting.

   687     When unmuted the channel goes back to its previous volume setting.

   689     @param aChannel

   690 	       Logical channel to set the mute state of. 0 <= aChannel <= 15.

   691     @param aMuted

   692 	       ETrue to mute the channel, EFalse to unmute it.

   693     */

   694 	virtual void  MmcSetChannelMuteL(TInt aChannel,TBool aMuted) = 0;

   695     /**

   696     Gets the overall volume of the MIDI client.

   698     @param aVolume

   699 	       The current overall volume setting.

   700     */

   701 	virtual void  MmcVolumeL(TInt& aVolume) = 0;

   702     /**

   703     Maximum volume setting that may be applied overall.

   705     @param aMaxVolume

   706 	       Maximum volume setting. Minimum value is always zero which is silent.

   707     */

   708 	virtual void  MmcMaxVolumeL(TInt& aMaxVolume) = 0;

   709     /**

   710     Set the overall volume of the MIDI client.

   711     This setting scales all channel volumes respectively so the actual volume

   712     that a channel is played at becomes (overall volume * channel volume / max volume).

   714     @param aVolume Overall volume setting to use.

   715     */

   716 	virtual void  MmcSetVolumeL(TInt aVolume) = 0;

   717     /**

   718     Length of time over which the volume is faded up from zero to the current settings

   719     when playback is started.

   721     @param aRampDuration

   722 	       Duration of the ramping period.

   723     */

   724 	virtual void  MmcSetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration) = 0;

   725     /**

   726     Get the current stereo balance value.

   728     @param aBalance

   729 	       Balance value ranging from KMMFBalanceMaxLeft to KMMFBalanceMaxRight.

   730     */

   731 	virtual void  MmcGetBalanceL(TInt& aBalance) = 0;

   732     /**

   733     Set the current stereo balance value.

   735     @param aBalance

   736 	       Balance value to set. Defaults to KMMFBalanceCenter to restore equal left-right balance.

   737     */

   738 	virtual void  MmcSetBalanceL(TInt aBalance) = 0;

   739     /**

   740     Set the max polyphony level the engine can handle.

   742     @param aMaxNotes

   743 	       Max polyphony level,  0 <= PolyphonyL() <= aMaxNotes.

   744     */

   745 	virtual void  MmcSetMaxPolyphonyL(TInt aMaxNotes) = 0;

   746     /**

   747     Gets the number of times the current opened resources have to be repeated.

   749     @param aNumRepeats

   750 	       The number of time the current opened resources have to be repeated.

   751     */

   752 	virtual void  MmcGetRepeatsL(TInt& aNumRepeats) = 0;

   753     /**

   754     Set the number of times to repeat the current MIDI resource.

   755     After Stop() has been called, repeat number of times and the trailing silence are reset.

   757     @param aRepeatNumberOfTimes

   758 	       Number of times to repeat the resource during playback. This includes the first playing.

   759     @param aTrailingSilence

   760 	       Time in microseconds to pause between repeats.

   761     */

   762 	virtual void  MmcSetRepeatsL(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence) = 0;

   763     /**

   764     Tell the MIDI engine to use a custom bank or a standard bank.

   766     @param aCustom

   767 	       If Etrue the custom bank in memory is used otherwise the standard bank

   768 		   is used leaving the custom bank in memory.

   769     */

   770 	virtual void  MmcSetBankL(TBool aCustom) = 0;

   771     /**

   772     Gets the muting status of a specific track.

   774     @param aTrack

   775 	       The track to query.

   776     @param aTrackMute

   777 	       The mute status of the track.

   778     */

   779 	virtual void  MmcIsTrackMuteL(TInt aTrack, TBool& aTrackMute) = 0;

   780     /**

   781     Gets the muting status of a specific channel.

   783     @param aChannel

   784 	       The channel to query.

   785     @param aChannelMute

   786 	       The mute status of the channel.

   787     */

   788 	virtual void  MmcIsChannelMuteL(TInt aChannel, TBool& aChannelMute) = 0;

   789     /**

   790     Gets the instrument assigned to a specified channel.

   792     @param aChannel

   793 	       Logical channel, 0 <= aChannel <= 15.

   794     @param aInstrumentId

   795 	       Identifier of the instrument assigned to aChannel. 0 <= aInstrumentId <= 127.

   796     @param aBankId

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

   798     */

   799 	virtual void  MmcGetInstrumentL(TInt aChannel, TInt& aInstrumentId, TInt& aBankId) = 0;

   800     /**

   801     Closes any currently open resources, such as files, descriptors or URLs in use.

   802     Does nothing if there is nothing currently open.

   803     */

   804 	virtual void  MmcCloseL() = 0;

   805     /**

   806     Stops playback of a resource but does not change the current position or release any resources.

   807     Pauses the internal timer if no resource is open.

   809     @param aFadeOutDuration

   810 	       Length of time over which the volume is faded out from the current settings to zero.

   811     */

   812 	virtual void  MmcStopL(const TTimeIntervalMicroSeconds& aFadeOutDuration) = 0;

   813     /**

   814     Gets the max polyphony level the engine can handle.

   816     @param aNumNotes

   817 	       Max polyphony level,  PolyphonyL() <= aMaxNotes.

   818     */

   819 	virtual void  MmcMaxPolyphonyL(TInt& aMaxNotes) = 0;

   820 	};

   823 /**

   824 Mixin class to define an object capable of handling a MIDI event within the controller framework.

   826 @publishedAll

   827 @released

   828 */

   829 class MMidiEventHandler

   830 	{

   831 public:

   832     /**

   833     Send an event to the client.

   835     @param aEvent

   836 	       The MIDI event.

   837 	@return One of the system-wide error codes.

   838     */

   839 	virtual TInt SendMidiEventToClient(const CMMFMidiEvent& aEvent) = 0;

   840 	};

   842 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

   843 #include <mmf/common/midieventreceiver.h>

   844 #endif

   846 class CMidiEventReceiver;

   848 /**

   849 Custom command parser class to be used by controller plugins wishing to support

   850 MIDI controller commands.

   851 The controller plugin must be derived from MMidiCustomCommandImplementor

   852 to use this class. The controller plugin should create an object of this type and add

   853 it to the list of custom command parsers in the controller framework.

   855 @publishedAll

   856 @released

   857 */

   858 class CMidiCustomCommandParser : public CMMFCustomCommandParserBase,

   859 								 public MMidiEventHandler

   860 	{

   861 public:

   862 	IMPORT_C static CMidiCustomCommandParser* NewL(MMidiCustomCommandImplementor& aImplementor);

   863 	IMPORT_C ~CMidiCustomCommandParser();

   864 	/**

   865     @internalTechnology

   866     */

   867 	void HandleRequest(TMMFMessage& aMessage);

   868 	virtual TInt SendMidiEventToClient(const CMMFMidiEvent& aEvent);

   869 private:

   870 	CMidiCustomCommandParser(MMidiCustomCommandImplementor& aImplementor);

   871 	// Internal request handling methods.

   872 	void DoHandleRequestL(TMMFMessage& aMessage);

   874 	TBool DoSetPositionMicroBeatsL(TMMFMessage& aMessage);

   875 	TBool DoPositionMicroBeatsL(TMMFMessage& aMessage);

   876 	TBool DoPlayNoteL(TMMFMessage& aMessage);

   877 	TBool DoPlayNoteWithStartTimeL(TMMFMessage& aMessage);

   878 	TBool DoStopNotesL(TMMFMessage& aMessage);

   879 	TBool DoNoteOnL(TMMFMessage& aMessage);

   880 	TBool DoNoteOffL(TMMFMessage& aMessage);

   881 	TBool DoPlaybackRateL(TMMFMessage& aMessage);

   882 	TBool DoSetPlaybackRateL(TMMFMessage& aMessage);

   883 	TBool DoMaxPlaybackRateL(TMMFMessage& aMessage);

   884 	TBool DoMinPlaybackRateL(TMMFMessage& aMessage);

   885 	TBool DoTempoMicroBeatsPerMinuteL(TMMFMessage& aMessage);

   886 	TBool DoSetTempoL(TMMFMessage& aMessage);

   887 	TBool DoPitchTranspositionCentsL(TMMFMessage& aMessage);

   888 	TBool DoSetPitchTranspositionL(TMMFMessage& aMessage);

   889 	TBool DoDurationMicroBeatsL(TMMFMessage& aMessage);

   890 	TBool DoNumTracksL(TMMFMessage& aMessage);

   891 	TBool DoSetTrackMuteL(TMMFMessage& aMessage);

   892 	TBool DoMimeTypeL(TMMFMessage& aMessage);

   893 	TBool DoSetSyncUpdateCallbackIntervalL(TMMFMessage& aMessage);

   894 	TBool DoSendMessageL(TMMFMessage& aMessage);

   895 	TBool DoSendMessageWithTimeStampL(TMMFMessage& aMessage);

   896 	TBool DoSendMipMessageL(TMMFMessage& aMessage);

   897 	TBool DoNumberOfBanksL(TMMFMessage& aMessage);

   898 	TBool DoGetBankIdL(TMMFMessage& aMessage);

   899 	TBool DoLoadCustomBankL(TMMFMessage& aMessage);

   900 	TBool DoLoadCustomBankDataL(TMMFMessage& aMessage);

   901 	TBool DoUnloadCustomBankL(TMMFMessage& aMessage);

   902 	TBool DoCustomBankLoadedL(TMMFMessage& aMessage);

   903 	TBool DoUnloadAllCustomBanksL(TMMFMessage& aMessage);

   904 	TBool DoNumberOfInstrumentsL(TMMFMessage& aMessage);

   905 	TBool DoGetInstrumentIdL(TMMFMessage& aMessage);

   906 	TBool DoInstrumentNameL(TMMFMessage& aMessage);

   907 	TBool DoCopyInstrumentNameL(TMMFMessage& aMessage);

   908 	TBool DoSetInstrumentL(TMMFMessage& aMessage);

   909 	TBool DoLoadCustomInstrumentL(TMMFMessage& aMessage);

   910 	TBool DoLoadCustomInstrumentDataL(TMMFMessage& aMessage);

   911 	TBool DoUnloadCustomInstrumentL(TMMFMessage& aMessage);

   912 	TBool DoPercussionKeyNameL(TMMFMessage& aMessage);

   913 	TBool DoCopyPercussionKeyNameL(TMMFMessage& aMessage);

   914 	TBool DoStopTimeL(TMMFMessage& aMessage);

   915 	TBool DoSetStopTimeL(TMMFMessage& aMessage);

   916 	TBool DoPolyphonyL(TMMFMessage& aMessage);

   917 	TBool DoChannelsSupportedL(TMMFMessage& aMessage);

   918 	TBool DoChannelVolumeL(TMMFMessage& aMessage);

   919 	TBool DoMaxChannelVolumeL(TMMFMessage& aMessage);

   920 	TBool DoSetChannelVolumeL(TMMFMessage& aMessage);

   921 	TBool DoSetChannelMuteL(TMMFMessage& aMessage);

   922 	TBool DoVolumeL(TMMFMessage& aMessage);

   923 	TBool DoMaxVolumeL(TMMFMessage& aMessage);

   924 	TBool DoSetVolumeL(TMMFMessage& aMessage);

   925 	TBool DoSetVolumeRampL(TMMFMessage& aMessage);

   926 	TBool DoGetBalanceL(TMMFMessage& aMessage);

   927 	TBool DoSetBalanceL(TMMFMessage& aMessage);

   928 	TBool DoSetMaxPolyphonyL(TMMFMessage& aMessage);

   929 	TBool DoGetRepeatsL(TMMFMessage& aMessage);

   930 	TBool DoSetRepeatsL(TMMFMessage& aMessage);

   931 	TBool DoSetBankL(TMMFMessage& aMessage);

   932 	TBool DoIsTrackMuteL(TMMFMessage& aMessage);

   933 	TBool DoIsChannelMuteL(TMMFMessage& aMessage);

   934 	TBool DoGetInstrumentL(TMMFMessage& aMessage);

   935 	TBool DoCloseL(TMMFMessage& aMessage);

   936 	TBool DoStopL(TMMFMessage& aMessage);

   937 	TBool DoReceiveEventsL(TMMFMessage& aMessage);

   938 	TBool DoRetrieveEventL(TMMFMessage& aMessage);

   939 	TBool DoCancelReceiveEventsL(TMMFMessage& aMessage);

   941 	void DoCreateBufFromUintArrayL(RArray<TUint>& aArray);

   942 	void DoCreateBufFromFourCCArrayL(RArray<TFourCC>& aArray);

   943 	TBool DoMaxPolyphonyL(TMMFMessage& aMessage);

   944 private:

   945 	/** The object that implements the MIDI controller interface */

   946 	MMidiCustomCommandImplementor& iImplementor;

   948 	CMidiEventReceiver* iMidiEventReceiver;

   949 	/** The events waiting to be sent to the client.*/

   950 	RPointerArray<CMMFMidiEvent> iMidiEvents;

   952 	// variable length data waiting to be copied back to the client

   953 	CBufFlat* iInstrumentName;

   954 	CBufFlat* iPercussionKeyName;

   955 	};

   957 #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--