1.1 --- a/epoc32/include/midiclientutility.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/midiclientutility.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,328 @@
1.4 -midiclientutility.h
1.5 +// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifndef __MIDICLIENTUTILITY_H__
1.21 +#define __MIDICLIENTUTILITY_H__
1.22 +
1.23 +#include <e32std.h>
1.24 +#include <e32base.h>
1.25 +#include <bamdesca.h>
1.26 +#include <mmf/common/mmfcontroller.h>
1.27 +#include <mmf/common/mmfstandardcustomcommands.h>
1.28 +#include <mmf/common/mmfdrmcustomcommands.h>
1.29 +#include <mmf/common/mmfmididatacommon.h>
1.30 +
1.31 +
1.32 +/**
1.33 +General utility class to hold instrument information.
1.34 +
1.35 +@publishedAll
1.36 +@released
1.37 +*/
1.38 +class TInstrumentInfo
1.39 + {
1.40 +public:
1.41 + /**
1.42 + *Identifier of sound bank to reference.
1.43 + */
1.44 + TInt iBankId;
1.45 +
1.46 + /**
1.47 + * Specifies whether to reference a custom or standard sound bank.
1.48 + */
1.49 + TBool iCustom;
1.50 +
1.51 + /**
1.52 + * Identifier of specified instrument.
1.53 + */
1.54 + TInt iInstrumentId;
1.55 + };
1.56 +
1.57 +/**
1.58 +Defines the state of the MIDI client utility with regard to the MIDI resource.
1.59 +
1.60 +@publishedAll
1.61 +@released
1.62 +*/
1.63 +enum TMidiState
1.64 + {
1.65 + /**
1.66 + * No MIDI resource is currently open.
1.67 + * The MIDI engine is not processing midi events.
1.68 + */
1.69 + EMidiStateClosedDisengaged,
1.70 +
1.71 +
1.72 + /**
1.73 + * A MIDI resource is open and primed but not playing.
1.74 + * The MIDI engine is not processing midi events.
1.75 + */
1.76 + EMidiStateOpenDisengaged,
1.77 +
1.78 + /**
1.79 + * A MIDI resource is open and currently playing.
1.80 + * The MIDI engine is currently processing midi events.
1.81 + */
1.82 + EMidiStateOpenPlaying,
1.83 +
1.84 + /**
1.85 + * Not able to play full SP-MIDI or DLS content, but attempting best-effort playback.
1.86 + */
1.87 + EMidiStatePlaybackIncompatible,
1.88 +
1.89 + /**
1.90 + * Due to system resource constraints and SP-MIDI content constraints,
1.91 + * there is no audible MIDI content during playback currently.
1.92 + * The situation may change if resources are freed later.
1.93 + */
1.94 + EMidiStatePlaybackSilent,
1.95 +
1.96 + /**
1.97 + * No MIDI resource is currently open.
1.98 + * The MIDI engine is currently processing midi events.
1.99 + */
1.100 + EMidiStateClosedEngaged,
1.101 +
1.102 + /**
1.103 + * A MIDI resource is open and primed but not playing.
1.104 + * The MIDI engine is currently processing MIDI events.
1.105 + * The transition to this state is only possible from EMidiStateOpenPlaying state,
1.106 + * when the 'playback head' reaches the end of media data or the playback
1.107 + * stops due to stop time set.
1.108 + */
1.109 + EMidiStateOpenEngaged,
1.110 + };
1.111 +
1.112 +/**
1.113 +Active object utility class to allow MIDI events to be signalled asynchronously.
1.114 +@see CMidiClientUtility::NewL().
1.115 +
1.116 +@publishedAll
1.117 +@released
1.118 +*/
1.119 +class MMidiClientUtilityObserver
1.120 + {
1.121 +public:
1.122 + /**
1.123 + A state change has occurred in the MIDI client utility.
1.124 +
1.125 + @param aOldState
1.126 + Old state.
1.127 + @param aNewState
1.128 + New state.
1.129 + @param aTime
1.130 + The time in microseconds at which playback stopped relative to the start of the MIDI resource.
1.131 + @param aError
1.132 + Error code.
1.133 + */
1.134 + virtual void MmcuoStateChanged(TMidiState aOldState,TMidiState aNewState,const TTimeIntervalMicroSeconds& aTime,TInt aError) = 0;
1.135 + /**
1.136 + The MIDI resource has encountered a tempo change message in the MIDI data stream.
1.137 +
1.138 + @param aMicroBeatsPerMinute
1.139 + New tempo value in micro beats per minute (BPM*1000000).
1.140 + */
1.141 + virtual void MmcuoTempoChanged(TInt aMicroBeatsPerMinute) = 0;
1.142 + /**
1.143 + The MIDI resource has encountered a volume change message in the MIDI data stream.
1.144 +
1.145 + @param aChannel
1.146 + Logical channel to which the message applies. 0 <= aChannel < ChannelsSupportedL().
1.147 + @param aVolumeInDecibels
1.148 + New volume setting being used.
1.149 + */
1.150 + virtual void MmcuoVolumeChanged(TInt aChannel,TReal32 aVolumeInDecibels) = 0;
1.151 + /**
1.152 + The MIDI resource has encountered a mute message in the MIDI data stream.
1.153 +
1.154 + @param aChannel
1.155 + Logical channel to which the message applies. 0 <= aChannel < ChannelsSupportedL().
1.156 + @param aMuted
1.157 + New muting state of the channel - ETrue is muted, EFalse is unmuted.
1.158 + */
1.159 + virtual void MmcuoMuteChanged(TInt aChannel,TBool aMuted) = 0;
1.160 + /**
1.161 + Callback in response to a call to CMIDIClientUtility::SetSyncUpdateCallbackIntervalL().
1.162 + By default there are no callbacks. Otherwise the callback is called at an interval set by the client.
1.163 +
1.164 + @param aMicroSeconds
1.165 + Position in microseconds relative to the start of the resource - only set if
1.166 + the sync update set function was called with the microseconds parameter set.
1.167 + @param aMicroBeats
1.168 + Position in microbeats relative to the start of the resource - only set if
1.169 + the sync update set function was called with the microbeats parameter set and
1.170 + the microseconds parameter set to 0.
1.171 + */
1.172 + virtual void MmcuoSyncUpdate(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats) = 0;
1.173 + /**
1.174 + A timed meta data entry has been found in the MIDI data stream, eg a timed song lyric in an SMF file.
1.175 +
1.176 + @param aMetaDataEntryId
1.177 + Index of the meta data entry - if this entry has not been encountere before,
1.178 + it will be added to the list of meta data entries. Previously encountered timed
1.179 + entries still generate this callback.
1.180 + @param aPosition
1.181 + Position in microseconds relative to the start of the MIDI resource that the MIDI
1.182 + meta data entry was found at.
1.183 + */
1.184 + virtual void MmcuoMetaDataEntryFound(const TInt aMetaDataEntryId,const TTimeIntervalMicroSeconds& aPosition) = 0;
1.185 + /**
1.186 + A MIP message has been found in the MIDI data stream.
1.187 +
1.188 + @param aMessage
1.189 + Reference to an array of MIP message entries (logical {channel, MIP} value pairs)
1.190 + contained in the message.
1.191 + */
1.192 + virtual void MmcuoMipMessageReceived(const RArray<TMipMessageEntry>& aMessage) = 0;
1.193 + /**
1.194 + The polyphony of the MIDI engine has changed.
1.195 +
1.196 + @param aNewPolyphony
1.197 + The new polyphony value.
1.198 + */
1.199 + virtual void MmcuoPolyphonyChanged(TInt aNewPolyphony) = 0;
1.200 + /**
1.201 + An instrument has been changed on a channel.
1.202 +
1.203 + @param aChannel
1.204 + Channel where the change of instrument occurred. 0 <= aChannel < ChannelsSupportedL().
1.205 + @param aBankId
1.206 + Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
1.207 + The bank ID is a concatenation of MIDI bank MSB and LSB values.
1.208 + @param aInstrumentId
1.209 + Identifier of the instrument that has been changed. 0 <= aInstrumentId <= 127.
1.210 + */
1.211 + virtual void MmcuoInstrumentChanged(TInt aChannel,TInt aBankId,TInt aInstrumentId) = 0;
1.212 + };
1.213 +
1.214 +
1.215 +/**
1.216 +Utility class to provide a standard client interface to a MIDI controller.
1.217 +
1.218 +@publishedAll
1.219 +@released
1.220 +*/
1.221 +class CMidiClientUtility : public CBase
1.222 + {
1.223 + class CBody;
1.224 +public:
1.225 + IMPORT_C static CMidiClientUtility* NewL(MMidiClientUtilityObserver& aObserver,
1.226 + TInt aPriority = EMdaPriorityNormal,
1.227 + TMdaPriorityPreference aPref = EMdaPriorityPreferenceTimeAndQuality);
1.228 +
1.229 + // alternative NewL for selecting shared/separate controller heap(s)
1.230 + IMPORT_C static CMidiClientUtility* NewL(MMidiClientUtilityObserver& aObserver,
1.231 + TInt aPriority,
1.232 + TMdaPriorityPreference aPref,
1.233 + TBool aUseSharedHeap);
1.234 +
1.235 + /** Destructor */
1.236 + virtual ~CMidiClientUtility();
1.237 + IMPORT_C TMidiState State() const;
1.238 + IMPORT_C void OpenFile(const TDesC& aFileName);
1.239 + IMPORT_C void OpenFile(const RFile& aFile);
1.240 +
1.241 + IMPORT_C void OpenFile(const TMMSource& aSource);
1.242 +
1.243 + IMPORT_C void OpenDes(const TDesC8& aDescriptor);
1.244 + IMPORT_C void OpenUrl(const TDesC& aUrl,TInt aIapId = KUseDefaultIap,const TDesC8& aMimeType=KNullDesC8);
1.245 + IMPORT_C void Close();
1.246 + IMPORT_C void Play();
1.247 + IMPORT_C void Stop(const TTimeIntervalMicroSeconds& aFadeOutDuration);
1.248 + IMPORT_C void PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);
1.249 + IMPORT_C void PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity);
1.250 + IMPORT_C void StopNotes(TInt aChannel);
1.251 + IMPORT_C void NoteOnL(TInt aChannel,TInt aNote,TInt aVelocity);
1.252 + IMPORT_C void NoteOffL(TInt aChannel,TInt aNote,TInt aVelocity);
1.253 + IMPORT_C TInt PlaybackRateL() const;
1.254 + IMPORT_C void SetPlaybackRateL(TInt aRate);
1.255 + IMPORT_C TInt MaxPlaybackRateL() const;
1.256 + IMPORT_C TInt MinPlaybackRateL() const;
1.257 + IMPORT_C TInt TempoMicroBeatsPerMinuteL() const;
1.258 + IMPORT_C void SetTempoL(TInt aMicroBeatsPerMinute);
1.259 + IMPORT_C TInt PitchTranspositionCentsL() const;
1.260 + IMPORT_C TInt SetPitchTranspositionL(TInt aCents);
1.261 + IMPORT_C TTimeIntervalMicroSeconds DurationMicroSecondsL() const;
1.262 + IMPORT_C TInt64 DurationMicroBeatsL() const;
1.263 + IMPORT_C TInt NumTracksL() const;
1.264 + IMPORT_C void SetTrackMuteL(TInt aTrack,TBool aMuted) const;
1.265 + IMPORT_C const TDesC8& MimeTypeL();
1.266 + IMPORT_C TTimeIntervalMicroSeconds PositionMicroSecondsL() const;
1.267 + IMPORT_C void SetPositionMicroSecondsL(const TTimeIntervalMicroSeconds& aPosition);
1.268 + IMPORT_C TInt64 PositionMicroBeatsL() const;
1.269 + IMPORT_C void SetPositionMicroBeatsL(TInt64 aMicroBeats);
1.270 + IMPORT_C void SetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds& aMicroSeconds, TInt64 aMicroBeats=0);
1.271 + IMPORT_C TInt SendMessageL(const TDesC8& aMidiMessage);
1.272 + IMPORT_C TInt SendMessageL(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime);
1.273 + IMPORT_C void SendMipMessageL(const RArray<TMipMessageEntry>& aEntry);
1.274 + IMPORT_C TInt NumberOfBanksL(TBool aCustom) const;
1.275 + IMPORT_C TInt GetBankIdL(TBool aCustom,TInt aBankIndex) const;
1.276 + IMPORT_C void LoadCustomBankL(const TDesC& aFileName,TInt& aBankCollectionIndex);
1.277 + IMPORT_C void LoadCustomBankDataL(const TDesC8& aBankData,TInt& aBankCollectionIndex);
1.278 + IMPORT_C void UnloadCustomBankL(TInt aBankCollectionIndex);
1.279 + IMPORT_C TBool CustomBankLoadedL(TInt aBankCollectionIndex) const;
1.280 + IMPORT_C void UnloadAllCustomBanksL();
1.281 + IMPORT_C TInt NumberOfInstrumentsL(TInt aBankId,TBool aCustom) const;
1.282 + IMPORT_C TInt GetInstrumentIdL(TInt aBankId,TBool aCustom,TInt aInstrumentIndex) const;
1.283 + IMPORT_C HBufC* InstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) const;
1.284 + IMPORT_C void GetInstrumentL(TInt aChannel, TInt& aInstrumentId, TInt& aBankId);
1.285 + IMPORT_C void SetInstrumentL(TInt aChannel,TInt aBankId,TInt aInstrumentId);
1.286 + IMPORT_C void LoadCustomInstrumentL(const TDesC& aFileName,TInt aFileBankId,TInt aFileInstrumentId,TInt aMemoryBankId,TInt aMemoryInstrumentId);
1.287 + IMPORT_C void LoadCustomInstrumentDataL(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId);
1.288 + IMPORT_C void UnloadCustomInstrumentL(TInt aCustomBankId,TInt aInstrumentId);
1.289 + IMPORT_C HBufC* PercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) const;
1.290 + IMPORT_C void StopTimeL(TTimeIntervalMicroSeconds& aStopTime) const;
1.291 + IMPORT_C void SetStopTimeL(const TTimeIntervalMicroSeconds& aStopTime);
1.292 + IMPORT_C void SetRepeatsL(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence);
1.293 + IMPORT_C TInt GetRepeats() const;
1.294 + IMPORT_C TInt PolyphonyL() const;
1.295 + IMPORT_C void SetMaxPolyphonyL(TInt aMaxNotes);
1.296 + IMPORT_C TInt ChannelsSupportedL() const;
1.297 + IMPORT_C TReal32 ChannelVolumeL(TInt aChannel) const;
1.298 + IMPORT_C TReal32 MaxChannelVolumeL() const;
1.299 + IMPORT_C void SetChannelVolumeL(TInt aChannel,TReal32 aVolumeInDecibels);
1.300 + IMPORT_C void SetChannelMuteL(TInt aChannel,TBool aMuted);
1.301 + IMPORT_C TInt VolumeL() const;
1.302 + IMPORT_C TInt MaxVolumeL() const;
1.303 + IMPORT_C void SetVolumeL(TInt aVolume);
1.304 + IMPORT_C void SetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration);
1.305 + IMPORT_C TInt GetBalanceL() const;
1.306 + IMPORT_C void SetBalanceL(TInt aBalance = KMMFBalanceCenter);
1.307 + IMPORT_C void SetPriorityL(TInt aPriority, TMdaPriorityPreference aPref);
1.308 + IMPORT_C TInt NumberOfMetaDataEntriesL() const;
1.309 + IMPORT_C CMMFMetaDataEntry* GetMetaDataEntryL(TInt aMetaDataIndex) const;
1.310 +/**
1.311 + * @deprecated SetBankL is deprecated due to Mobile XMF specification requirement that user instruments (custom instruments) override standard instruments.
1.312 + */
1.313 + IMPORT_C void SetBankL(TBool aCustom);
1.314 + IMPORT_C TBool IsTrackMuteL(TInt aTrack) const;
1.315 + IMPORT_C TBool IsChannelMuteL(TInt aChannel) const;
1.316 + IMPORT_C void CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom);
1.317 + IMPORT_C void CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2);
1.318 + IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus);
1.319 + IMPORT_C void CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus);
1.320 + IMPORT_C TInt MaxPolyphonyL() const;
1.321 +
1.322 + IMPORT_C MMMFDRMCustomCommand* GetDRMCustomCommand();
1.323 +
1.324 +private:
1.325 + /**
1.326 + * a pointer to the implementation.
1.327 + */
1.328 + CBody* iBody;
1.329 + friend class CBody;
1.330 + };
1.331 +
1.332 +#endif