--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmlibs/mmfw/MIDI/src/midiclientutility.cpp Tue Feb 02 01:56:55 2010 +0200
@@ -0,0 +1,1196 @@
+// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+//
+
+#include <midiclientutility.h>
+#include "midiclientutilitybody.h"
+
+
+/**
+Static factory function for creating a MIDI client utility object.
+This function is synchronous, unlike the other factory functions,
+because it doesn't need to perform any MIDI resource initialisation.
+
+@param aObserver
+ Reference to an object to receive callbacks on completion of asynchronous functions.
+@param aPriority
+ The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and
+ EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request.
+@param aPref
+ The Priority Preference - an additional audio policy parameter. The suggested default is
+ EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional
+ values may be supported by given phones and/or platforms, but should not be depended upon by
+ portable code.
+@param aUseSharedHeap
+ Select if the underlying controller will have its own heap or share a single heap with other
+ controller instances.
+ The default behaviour, or if this value is EFalse, is that each controller is created with
+ its own heap. The alternative, if the value is ETrue, is that controllers share a special
+ heap with other controllers created the same way. Each heap uses a chunk, so this avoids
+ situations where the number of chunks per process is limited. The default behaviour is
+ generally to be preferred, and should give lower overall memory usage. However, if many
+ controllers are to be created for a particular thread, then ETrue should be provided to
+ prevent running out of heaps or chunks.
+@return Fully constructed utility object ready to have an OpenXxxx() function called.
+
+Note: The Priority Value and Priority Preference are used primarily when deciding what to do when
+several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference,
+the adaptation may consider other parameters such as the SecureId and Capabilities of the client process.
+Whatever, the decision as to what to do in such situations is up to the audio adaptation, and may
+vary between different phones. Portable applications are advised not to assume any specific behaviour.
+*/
+EXPORT_C CMidiClientUtility* CMidiClientUtility::NewL(MMidiClientUtilityObserver& aObserver, TInt aPriority, TInt aPref, TBool aUseSharedHeap)
+ {
+ CMidiClientUtility* self = new(ELeave) CMidiClientUtility();
+ CleanupStack::PushL(self);
+ self->iBody = CMidiClientUtility::CBody::NewL(self, aObserver, aPriority, aPref, aUseSharedHeap );
+ CleanupStack::Pop(self);
+ return self;
+ }
+
+/**
+Static factory function for creating a MIDI client utility object.
+This function is synchronous, unlike the other factory functions,
+because it doesn't need to perform any MIDI resource initialisation
+The underlying controller that is created will be given its own heap.
+
+@param aObserver
+ Reference to an object to receive callbacks on completion of asynchronous functions.
+@param aPriority
+ The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and
+ EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request.
+@param aPref
+ The Priority Preference - an additional audio policy parameter. The suggested default is
+ EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional
+ values may be supported by given phones and/or platforms, but should not be depended upon by
+ portable code.
+@return Fully constructed utility object ready to have an OpenXxxx() function called.
+
+Note: The Priority Value and Priority Preference are used primarily when deciding what to do when
+several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference,
+the adaptation may consider other parameters such as the SecureId and Capabilities of the client process.
+Whatever, the decision as to what to do in such situations is up to the audio adaptation, and may
+vary between different phones. Portable applications are advised not to assume any specific behaviour.
+*/
+EXPORT_C CMidiClientUtility* CMidiClientUtility::NewL(MMidiClientUtilityObserver& aObserver, TInt aPriority, TInt aPref)
+ {
+ return NewL( aObserver, aPriority, aPref, EFalse );
+ }
+
+CMidiClientUtility::~CMidiClientUtility()
+ {
+ delete iBody;
+ }
+
+/**
+Asynchronous function to open a file containing MIDI data and perform
+initialisation ready for playback
+
+@param aFileName Name of the MIDI file to open
+*/
+EXPORT_C void CMidiClientUtility::OpenFile(const TDesC& aFileName)
+ {
+ iBody->OpenFile(aFileName);
+ }
+
+/**
+Asynchronous function to open a file containing MIDI data and perform
+initialisation ready for playback
+
+@param aFile Open shared protected session handle to the midi file to read
+*/
+EXPORT_C void CMidiClientUtility::OpenFile(const RFile& aFile)
+ {
+ iBody->OpenFile(const_cast<RFile&>(aFile));
+ }
+
+/**
+Asynchronous function to open a file containing MIDI data and perform
+initialisation ready for playback
+
+@param aFileSource TFileSource object which references either a filename or a
+file handle to the midi file to read
+*/
+EXPORT_C void CMidiClientUtility::OpenFile(const TMMSource& aSource)
+ {
+ iBody->OpenFile(aSource);
+ }
+
+/**
+Asynchronous function to open a descriptor containing MIDI data and perform
+initialisation ready for playback
+
+@param aDescriptor descriptor containing MIDI data
+*/
+EXPORT_C void CMidiClientUtility::OpenDes(const TDesC8& aDescriptor)
+ {
+ iBody->OpenDes(aDescriptor);
+ }
+
+/**
+Asynchronous function to open a URL containing MIDI data and perform
+initialisation ready for playback
+
+@param aUrl
+ Uniform Resource Locator for a MIDI data stream
+@param aIapId
+ Identifier of the Internet Access Point to use -
+ available from CommDB, the comms connections database.
+ Defaults to using the default access point, as defined by CommDB
+@param aMimeType
+ Mime type of the MIDI data stream to be played.
+ Defaults to nothing in which case the an attempt will be made to recognise the type of the MIDI data automatically.
+*/
+EXPORT_C void CMidiClientUtility::OpenUrl(const TDesC& aUrl,TInt aIapId,const TDesC8& aMimeType)
+ {
+ iBody->OpenUrl(aUrl, aIapId, aMimeType);
+ }
+
+/**
+Asynchronous function to initiate or resume playback of a previously opened resource.
+Also used to start an internal timer to establish a zero-time for the media stream
+time relative to which commands with timestamps are timed against
+*/
+EXPORT_C void CMidiClientUtility::Play()
+ {
+ iBody->Play();
+ }
+
+/**
+Stops playback of a resource but does not change the current position or release any resources.
+Pauses the internal timer if no resource is open
+
+@param aFadeOutDuration
+ Length of time over which the volume is faded out from the current settings to zero.
+*/
+EXPORT_C void CMidiClientUtility::Stop(const TTimeIntervalMicroSeconds& aFadeOutDuration)
+ {
+ iBody->Stop(aFadeOutDuration);
+ }
+
+/**
+Asynchronous function which closes any currently open resources, such as files, descriptors or URLs in use.
+Does nothing if there is nothing currently open.
+*/
+EXPORT_C void CMidiClientUtility::Close()
+ {
+ iBody->Close();
+ }
+
+/**
+Gets the current state of the MIDI client utility with regard to MIDI resources
+
+@return The current state of the utility
+*/
+EXPORT_C TMidiState CMidiClientUtility::State() const
+ {
+ return iBody->State();
+ }
+
+/**
+Synchronous function to play a single note.
+Multiple calls to this function will be accommodated as far as the MIDI engine can
+manage. The same functionality could be implemented using the SendMessage function
+
+@param aChannel
+ Logical channel to play note on. 0 <= aChannel <= 15.
+@param aNote
+ Note to play. 0 <= aNote <= 127
+@param aDuration
+ Length of time to play note for.
+@param aNoteOnVelocity
+ Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.
+@param aNoteOffVelocity
+ Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.
+*/
+EXPORT_C void CMidiClientUtility::PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity)
+ {
+ iBody->PlayNoteL(aChannel, aNote, aDuration, aNoteOnVelocity, aNoteOffVelocity);
+ }
+
+/**
+Synchronous function to play a single note at a specified time.
+Multiple calls to this function will be accommodated as far as the MIDI engine can
+manage. The same functionality could be implemented using the SendMessage function
+
+@param aChannel
+ Logical channel to play note on. 0 <= aChannel <= 15.
+@param aNote
+ Note to play. 0 <= aNote <= 127
+@param aStartTime
+ specifies the time at which to start playing the note,
+ relative to the MIDI resource playing time or the time elapsed since Play() was called if no resource is present
+@param aDuration
+ Length of time to play note for.
+@param aNoteOnVelocity
+ Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.
+@param aNoteOffVelocity
+ Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.
+*/
+EXPORT_C void CMidiClientUtility::PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity)
+ {
+ iBody->PlayNoteL(aChannel, aNote, aStartTime, aDuration, aNoteOnVelocity, aNoteOffVelocity);
+ }
+
+/**
+Stops the playback of all notes on the given channel,
+by means of an All Notes Off MIDI message
+
+@param aChannel
+ Logical channel to stop notes on. 0 <= aChannel <= 15
+*/
+EXPORT_C void CMidiClientUtility::StopNotes(TInt aChannel)
+ {
+ iBody->StopNotes(aChannel);
+ }
+
+/**
+Synchronous function to commence playback of a note.
+Multiple calls to this function will be accommodated as far as the MIDI engine can manage
+
+@param aChannel
+ Logical channel to play note on. 0 <= aChannel <= 15
+@param aNote
+ Note to play. 0 <= aNote <= 127
+@param aVelocity
+ Velocity with which to start the note.
+ The legal integer range is 0 <= aVelocity <= 127, but the value zero
+ actually causes the message to be interpreted as a Note Off message
+ instead of a Note On.
+*/
+EXPORT_C void CMidiClientUtility::NoteOnL(TInt aChannel,TInt aNote,TInt aVelocity)
+ {
+ iBody->NoteOnL(aChannel, aNote, aVelocity);
+ }
+
+/**
+Synchronous function to terminate playback of a note. If no corresponding note
+is found then no error is raised.
+
+@param aChannel
+ Logical channel on which the note is playing. 0 <= aChannel <= 15.
+@param aNote
+ Note to terminate. 0 <= aNote <= 127.
+@param aVelocity
+ Velocity with which to stop the note. 0 <= aVelocity <= 127. There is no
+ standard behaviour corresponding with note off velocity.
+*/
+EXPORT_C void CMidiClientUtility::NoteOffL(TInt aChannel,TInt aNote,TInt aVelocity)
+ {
+ iBody->NoteOffL(aChannel, aNote, aVelocity);
+ }
+
+/**
+Gets the current playback rate factor of the currently open MIDI resource.
+The playback rate is independent from tempo,
+i.e., it can be used to give an overall speed factor for playback
+
+@return Current playback rate in percent times 1000,
+ i.e., 100000 means original playback speed, 200000 means double speed,
+ and 50000 means half speed playback
+*/
+EXPORT_C TInt CMidiClientUtility::PlaybackRateL() const
+ {
+ return iBody->PlaybackRateL();
+ }
+
+/**
+Sets the playback rate for the playback of the current MIDI resource.
+The playback rate is independent from tempo,
+i.e., it can be used to give an overall speed factor for playback.
+May be called whether playback is in progress or not.
+
+@param aRate
+ Playback rate in percent times 1000,
+ i.e., 100000 means original playback speed, 200000 means double speed,
+ and 50000 means half speed playback
+*/
+EXPORT_C void CMidiClientUtility::SetPlaybackRateL(TInt aRate)
+ {
+ iBody->SetPlaybackRateL(aRate);
+ }
+
+/**
+Gets the maximum playback rate in milli-percentage from the MIDI engine.
+@see SetPlaybackRate() for milli-percentage details
+
+@return Maximum playback rate supported by MIDI player
+*/
+EXPORT_C TInt CMidiClientUtility::MaxPlaybackRateL() const
+ {
+ return iBody->MaxPlaybackRateL();
+ }
+
+/**
+Gets the minimum playback rate in milli-percentage from the MIDI engine.
+@see SetPlaybackRate() for milli-percentage details.
+
+@return Minimum playback rate supported by MIDI player.
+*/
+EXPORT_C TInt CMidiClientUtility::MinPlaybackRateL() const
+ {
+ return iBody->MinPlaybackRateL();
+ }
+
+/**
+Gets the current tempo of the currently open MIDI resource. The tempo is independent
+from the playback rate, i.e., the resulting playback speed will be affected by both.
+
+@return Tempo at the current position of the currently open resource in microbeats per minute,
+ i.e. BPM * 1000000. Filled in by the controller framework
+*/
+EXPORT_C TInt CMidiClientUtility::TempoMicroBeatsPerMinuteL() const
+ {
+ return iBody->TempoMicroBeatsPerMinuteL();
+ }
+
+/**
+Sets the tempo at which the current MIDI resource should be played.
+May be called whether playback is in progress or not.
+The tempo is independent from the playback rate,
+i.e., the resulting playback speed will be affected by both
+
+@param aMicroBeatsPerMinute
+ Tempo in microbeats per minute (BPM*1000000) to set
+*/
+EXPORT_C void CMidiClientUtility::SetTempoL(TInt aMicroBeatsPerMinute)
+ {
+ iBody->SetTempoL(aMicroBeatsPerMinute);
+ }
+
+/**
+Gets the pitch shift in use for the currently open MIDI resource
+
+@return Pitch shift in cents, i.e. semitones * 100. One octave equals 1200 cents
+*/
+EXPORT_C TInt CMidiClientUtility::PitchTranspositionCentsL() const
+ {
+ return iBody->PitchTranspositionCentsL();
+ }
+
+/**
+Sets the pitch shift to apply to the currently open MIDI resource.
+May be called during playback
+aCents parameter is not checked - if the value is out of range, it is expected KErrArgument is return by MIDI engine.
+
+@param aCents
+ Pitch shift in cents, i.e. semitones * 100. One octave equals 1200 cents
+@return Actual pitch shift applied -
+ may differ from the requested value due to limitations of the MIDI engine
+*/
+EXPORT_C TInt CMidiClientUtility::SetPitchTranspositionL(TInt aCents)
+ {
+ return iBody->SetPitchTranspositionL(aCents);
+ }
+
+/**
+Gets the length of the currently open MIDI resource in micro-seconds
+
+@return Duration in microseconds (seconds * 1000000).
+*/
+EXPORT_C TTimeIntervalMicroSeconds CMidiClientUtility::DurationMicroSecondsL() const
+ {
+ return iBody->DurationMicroSecondsL();
+ }
+
+/**
+Gets the length of the currently open MIDI resource in micro-beats
+
+@return Duration in microbeats (beats * 1000000).
+*/
+EXPORT_C TInt64 CMidiClientUtility::DurationMicroBeatsL() const
+ {
+ return iBody->DurationMicroBeatsL();
+ }
+
+/**
+Gets the number of tracks present in the currently open MIDI resource
+
+@return Number of tracks
+*/
+EXPORT_C TInt CMidiClientUtility::NumTracksL() const
+ {
+ return iBody->NumTracksL();
+ }
+
+/**
+Mutes or unmutes a particular track
+
+@param aTrack
+ Index of the track to mute - 0 <= aTrack < NumTracksL().
+@param aMuted
+ ETrue to mute the track, EFalse to unmute it.
+*/
+EXPORT_C void CMidiClientUtility::SetTrackMuteL(TInt aTrack,TBool aMuted) const
+ {
+ iBody->SetTrackMuteL(aTrack, aMuted);
+ }
+
+
+/**
+Gets the MIME type of the MIDI resource currently open
+
+@return Descriptor containing the MIDI mime type
+*/
+EXPORT_C const TDesC8& CMidiClientUtility::MimeTypeL()
+ {
+ return iBody->MimeTypeL();
+ }
+
+/**
+Gets the current temporal position of the MIDI resource being played.
+
+@return Microseconds relative to the start of the resource
+*/
+EXPORT_C TTimeIntervalMicroSeconds CMidiClientUtility::PositionMicroSecondsL() const
+ {
+ return iBody->PositionMicroSecondsL();
+ }
+
+/**
+Change the position of the currently playing MIDI resource to the given position.
+May be called whenever a MIDI resource is open
+
+@param aPosition
+ Temporal position to move to. Clamped to (0, DurationMicroSecondsL()).
+*/
+EXPORT_C void CMidiClientUtility::SetPositionMicroSecondsL(const TTimeIntervalMicroSeconds& aPosition)
+ {
+ iBody->SetPositionMicroSecondsL(aPosition);
+ }
+
+/**
+Gets the current metrical position of the MIDI resource being played
+
+@return Microbeats (BPM*1000000) relative to the start of the resource
+*/
+EXPORT_C TInt64 CMidiClientUtility::PositionMicroBeatsL() const
+ {
+ return iBody->PositionMicroBeatsL();
+ }
+
+/**
+Change the position of the currently playing MIDI resource to the given position.
+May be called whenever a MIDI resource is open.
+
+@param aMicroBeats
+ Metrical position to move to. Clamped to (0, DurationMicroBeatsL()).
+*/
+EXPORT_C void CMidiClientUtility::SetPositionMicroBeatsL(TInt64 aMicroBeats)
+ {
+ iBody->SetPositionMicroBeatsL(aMicroBeats);
+ }
+
+/**
+Sets the frequency at which MMIDIClientUtilityObserver::MmcuoSyncUpdateL(…) is called
+to allow other components to synchronise with playback of this MIDI resource
+
+@param aMicroSeconds
+ Temporal interval to callback at. Used in preference to aMicroBeats if both are set
+@param aMicroBeats
+ Metrical interval to callback at. Set both parameters to zero to cancel.
+*/
+EXPORT_C void CMidiClientUtility::SetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats)
+ {
+ iBody->SetSyncUpdateCallbackIntervalL(aMicroSeconds, aMicroBeats);
+ }
+
+/**
+Sends a single MIDI message to the MIDI engine
+
+@param aMidiMessage
+ Descriptor containing the MIDI message data.
+ If there are several MIDI messages in the buffer, only the first one is processed
+*/
+EXPORT_C TInt CMidiClientUtility::SendMessageL(const TDesC8& aMidiMessage)
+ {
+ return iBody->SendMessageL(aMidiMessage);
+ }
+
+/**
+Sends a single MIDI message, with time stamp, to the MIDI engine
+
+@param aMidiMessage
+ Descriptor containing the MIDI message data.
+ If there are several MIDI messages in the buffer, only the first one is processed
+@param aTime
+ The time at which to execute the message, relative to the MIDI resource playing
+ time or the time elapsed since Play() was called if no resource is present
+*/
+EXPORT_C TInt CMidiClientUtility::SendMessageL(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime)
+ {
+ return iBody->SendMessageL(aMidiMessage, aTime);
+ }
+
+/**
+Sends a mip message to the MIDI engine. This is a convenience function,
+because the same functionality could be achieved with the SendMessage() function
+
+@param aEntry
+ Array of logical {channel, MIP} value pairs to send, highest priority first
+*/
+EXPORT_C void CMidiClientUtility::SendMipMessageL(const RArray<TMipMessageEntry>& aEntry)
+ {
+ iBody->SendMipMessageL(aEntry);
+ }
+
+/**
+Gets the number of standard or custom sound banks currently available
+
+@param aCustom
+ Specifies whether to reference a custom or standard sound bank
+@return Number of custom or standard sound banks available
+*/
+EXPORT_C TInt CMidiClientUtility::NumberOfBanksL(TBool aCustom) const
+ {
+ return iBody->NumberOfBanksL(aCustom);
+ }
+
+/**
+Gets the identifier of a sound bank. Bank identifier (aka bank number) is a
+14-bit value consisting of MIDI bank MSB and LSB values
+
+@param aCustom
+ Specifies whether to reference a custom or standard sound bank
+@param aBankIndex
+ Index of sound bank where 0 <= aBankIndex < NumberOfBanksL(…)
+@return Identifier of the specified bank occupying, at most, 14 bits
+*/
+EXPORT_C TInt CMidiClientUtility::GetBankIdL(TBool aCustom, TInt aBankIndex) const
+ {
+ return iBody->GetBankIdL(aCustom, aBankIndex);
+ }
+
+/**
+Loads one or more custom sound banks from a file into memory for use.
+If several banks are loaded with consequent LoadCustomBanksL() function calls,
+the banks are combined if the bank sets have colliding bank numbers
+
+@param aFileName
+ Name of the file containing the custom sound bank
+@param aBankCollectionIndex
+ Identifier of the custom sound bank loaded, occupying no more than 14 bits
+*/
+EXPORT_C void CMidiClientUtility::LoadCustomBankL(const TDesC& aFileName, TInt& aBankCollectionIndex)
+ {
+ iBody->LoadCustomBankL(aFileName, aBankCollectionIndex);
+ }
+
+/**
+Removes a custom sound bank from memory.
+Only valid for sound banks previously loaded from file.
+Once unloaded the custom sound bank is no longer available for use.
+
+@param aBankCollectionIndex
+ Identifier of the custom sound bank to unload,
+ occupying no more than 14 bits
+*/
+EXPORT_C void CMidiClientUtility::UnloadCustomBankL(TInt aBankCollectionIndex)
+ {
+ iBody->UnloadCustomBankL(aBankCollectionIndex);
+ }
+
+/**
+Query if a bank has been loaded to the memory
+
+@param aBankCollectionIndex
+ Identifier of the custom sound bank to check if it's in memory or not
+@return ETrue if the specified bank is in memory, EFalse otherwise
+*/
+EXPORT_C TBool CMidiClientUtility::CustomBankLoadedL(TInt aBankCollectionIndex) const
+ {
+ return iBody->CustomBankLoadedL(aBankCollectionIndex);
+ }
+
+/**
+Removes all custom sound banks from memory.
+*/
+EXPORT_C void CMidiClientUtility::UnloadAllCustomBanksL()
+ {
+ iBody->UnloadAllCustomBanksL();
+ }
+
+/**
+Gets the number of instruments available in a given sound bank
+
+@param aBankId
+ Identifier of sound bank to reference, occupying no more than 14 bits
+@param aCustom
+ Specifies whether to reference a custom or standard sound bank
+@return Count of the number of instruments available for the specified sound bank
+*/
+EXPORT_C TInt CMidiClientUtility::NumberOfInstrumentsL(TInt aBankId,TBool aCustom) const
+ {
+ return iBody->NumberOfInstrumentsL(aBankId, aCustom);
+ }
+
+/**
+Gets the identifier of an instrument.
+
+@param aBankId
+ Identifier of the sound bank to reference, occupying no more than 14 bits.
+@param aCustom
+ Specifies whether to reference a custom or standard sound bank.
+@param aInstrumentIndex
+ Index of the instrument to reference where 0 <= aInstrumentIndex < NumberOfInstrumentsL().
+@return Identifier of specified instrument.
+ This may differ from the index since the index simply enumerates the instruments,
+ whereas identifiers may not be contiguous, especially where certain instruments
+ correspond to General MIDI-defined instruments but not all instruments are
+ present. Instrument identifiers are between 0 and 127 inclusive.
+*/
+EXPORT_C TInt CMidiClientUtility::GetInstrumentIdL(TInt aBankId,TBool aCustom,TInt aInstrumentIndex) const
+ {
+ return iBody->GetInstrumentIdL(aBankId, aCustom, aInstrumentIndex);
+ }
+
+/**
+Gets the name of the given instrument.
+
+@param aBankId
+ Identifier of the bank that the instrument belongs to, occupying no more than 14 bits
+@param aCustom
+ Specifies whether to reference a custom or standard sound bank
+@param aInstrumentId
+ Identifier of the instrument under scrutiny. 0 <= iInstrumentId <= 127.
+@return Buffer containing the name of the specified instrument.
+ If it has no name then an empty descriptor is returned
+*/
+EXPORT_C HBufC* CMidiClientUtility::InstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) const
+ {
+ return iBody->InstrumentNameL(aBankId, aCustom, aInstrumentId);
+ }
+
+/**
+Sets a logical channel to use the given instrument.
+
+@param aChannel
+ Logical channel to set the instrument for. 0 <= aChannel <= 15
+@param aBankId
+ Identifier of the bank that the instrument belongs to,
+ occupying no more than 14 bits.
+ The bank ID is a concatenation of MIDI bank MSB and LSB values
+@param aInstrumentId
+ Identifier of the instrument under scrutiny. 0 <= iInstrumentId <= 127.
+*/
+EXPORT_C void CMidiClientUtility::SetInstrumentL(TInt aChannel,TInt aBankId,TInt aInstrumentId)
+ {
+ iBody->SetInstrumentL(aChannel, aBankId, aInstrumentId);
+ }
+
+/**
+Loads an individual instrument from file into custom sound bank memory for use.
+The bank and instrument ids given in the file can be mapped into different bank
+and instrument ids in memory
+
+@param aFileName
+ Name of the file containing the instrument
+@param aFileBankId
+ Identifier of the bank in the file from which to load the instrument,
+ occupying no more than 14 bits
+@param aFileInstrumentId
+ Identifier of the instrument to load. 0 <= aInstrumentId <= 127
+@param aMemoryBankId
+ Identifier of the custom bank in memory to load the instrument into,
+ occupying no more than 14 bits.
+@param aMemoryInstrumentId
+ Identifier of the instrument in memory to load the new
+ instrument into. 0 <= aInstrumentId <= 127.
+*/
+EXPORT_C void CMidiClientUtility::LoadCustomInstrumentL(const TDesC& aFileName,TInt aFileBankId,TInt aFileInstrumentId,TInt aMemoryBankId,TInt aMemoryInstrumentId)
+ {
+ iBody->LoadCustomInstrumentL(aFileName, aFileBankId, aFileInstrumentId, aMemoryBankId, aMemoryInstrumentId);
+ }
+
+/**
+Removes an instrument from custom sound bank memory.
+Only valid for instruments previously loaded from file.
+Once unloaded the instrument is no longer available for use
+
+@param aCustomBankId
+ Identifier of the custom sound bank containing
+ the instrument to unload, occupying no more than 14 bits.
+@param aInstrumentId
+ Identifier of the instrument to unload. 0 <= aInstrumentId <= 127
+*/
+EXPORT_C void CMidiClientUtility::UnloadCustomInstrumentL(TInt aCustomBankId,TInt aInstrumentId)
+ {
+ iBody->UnloadCustomInstrumentL(aCustomBankId, aInstrumentId);
+ }
+
+/**
+Gets the name of a particular percussion key corresponding to a given note.
+
+@param aNote
+ Note to query. 0 <= aNote <= 127
+@param aBankId
+ Identifier of the bank that the instrument belongs to, occupying no more than 14 bits.
+ The bank ID is a concatenation of MIDI bank MSB and LSB values.
+@param aCustom
+ Specifies whether to reference a custom or standard sound bank
+@param aInstrumentId
+ Identifier of an instrument
+@return Descriptor containing the name of the percussion key.
+ If the key does not have a name then an empty descriptor is returned
+*/
+EXPORT_C HBufC* CMidiClientUtility::PercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) const
+ {
+ return iBody->PercussionKeyNameL(aNote, aBankId, aCustom, aInstrumentId);
+ }
+
+/**
+Get the stop time currently set for the MIDI resource
+
+@param aStopTime
+ Time at which playback will stop, relative to the start of the resource
+*/
+EXPORT_C void CMidiClientUtility::StopTimeL(TTimeIntervalMicroSeconds& aStopTime) const
+ {
+ iBody->StopTimeL(aStopTime);
+ }
+
+/**
+Sets the stop time to use for the currently open MIDI resource
+
+@param aStopTime
+ Time at which playback will stop, relative to the start of the resource.
+ Clamped to 0 and the duration of the resource
+*/
+EXPORT_C void CMidiClientUtility::SetStopTimeL(const TTimeIntervalMicroSeconds& aStopTime)
+ {
+ iBody->SetStopTimeL(aStopTime);
+ }
+
+/**
+Set the number of times to repeat the current MIDI resource.
+After Stop() has been called, repeat number of times and the trailing silence are reset
+
+@param aRepeatNumberOfTimes
+ Number of time to repeat the resource during playback.
+ This includes the first playing
+@param aTrailingSilence
+ Time in microseconds to pause between repeats
+*/
+EXPORT_C void CMidiClientUtility::SetRepeatsL(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence)
+ {
+ iBody->SetRepeatsL(aRepeatNumberOfTimes, aTrailingSilence);
+ }
+
+/**
+Gets the number of currently active voices.
+
+@return The number of currently active voices
+*/
+EXPORT_C TInt CMidiClientUtility::PolyphonyL() const
+ {
+ return iBody->PolyphonyL();
+ }
+
+/**
+Gets the maximum number of logical channels supported by the MIDI engine.
+
+@return The maximum number of logical channels that the MIDI engine supports, 0 <= aChannels <=15.
+*/
+EXPORT_C TInt CMidiClientUtility::ChannelsSupportedL() const
+ {
+ return iBody->ChannelsSupportedL();
+ }
+
+/**
+Get the current volume setting of a logical channel
+
+@param aChannel
+ Logical channel to query. 0 <= aChannel <= 15.
+@return Volume currently set on the specified channel in decibels
+*/
+EXPORT_C TReal32 CMidiClientUtility::ChannelVolumeL(TInt aChannel) const
+ {
+ return iBody->ChannelVolumeL(aChannel);
+ }
+
+/**
+Gets the Maximum volume setting that may be applied to a logical channel
+
+@return Maximum volume setting. Minimum value is -infinity dB, which is the
+ smallest possible value that TReal32 supports.
+*/
+EXPORT_C TReal32 CMidiClientUtility::MaxChannelVolumeL() const
+ {
+ return iBody->MaxChannelVolumeL();
+ }
+
+/**
+Set the volume of a channel.
+
+@param aChannel
+ Logical channel to set the volume on. 0 <= aChannel <= 15
+@param aVolume
+ Volume currently set on the specified channel in decibels. The minimum
+ channel volume supported value is -infinity dB, which is the smallest
+ possible value that TReal32 supports.
+ The maximum channel volume can be set via MaxChannelVolumeL()
+*/
+EXPORT_C void CMidiClientUtility::SetChannelVolumeL(TInt aChannel,TReal32 aVolume)
+ {
+ iBody->SetChannelVolumeL(aChannel, aVolume);
+ }
+
+/**
+Set the muting state of a channel without changing its volume setting.
+When unmuted the channel goes back to its previous volume setting
+
+@param aChannel
+ Logical channel to set the mute state of. 0 <= aChannel <= 15.
+@param aMuted
+ ETrue to mute the channel, EFalse to unmute it.
+*/
+EXPORT_C void CMidiClientUtility::SetChannelMuteL(TInt aChannel,TBool aMuted)
+ {
+ iBody->SetChannelMuteL(aChannel, aMuted);
+ }
+
+/**
+Gets the overall volume of the MIDI client.
+
+@return The current overall volume setting
+*/
+EXPORT_C TInt CMidiClientUtility::VolumeL() const
+ {
+ return iBody->VolumeL();
+ }
+
+/**
+Maximum volume setting that may be applied overall.
+
+@return Maximum volume setting. Minimum value is always zero which is silent
+*/
+EXPORT_C TInt CMidiClientUtility::MaxVolumeL() const
+ {
+ return iBody->MaxVolumeL();
+ }
+
+/**
+Set the overall volume of the MIDI client.
+This setting scales all channel volumes respectively so the actual volume
+that a channel is played at is (overall volume * channel volume / max volume).
+
+@param aVolume
+ Overall volume setting to use
+*/
+EXPORT_C void CMidiClientUtility::SetVolumeL(TInt aVolume)
+ {
+ iBody->SetVolumeL(aVolume);
+ }
+
+/**
+Length of time over which the volume is faded up from zero to the current settings
+when playback is started.
+
+@param aRampDuration
+ Duration of the ramping period.
+*/
+EXPORT_C void CMidiClientUtility::SetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration)
+ {
+ iBody->SetVolumeRampL(aRampDuration);
+ }
+
+/**
+Get the current stereo balance value
+
+@return Balance value ranging from KMMFBalanceMaxLeft to KMMFBalanceMaxRight
+*/
+EXPORT_C TInt CMidiClientUtility::GetBalanceL() const
+ {
+ return iBody->GetBalanceL();
+ }
+
+/**
+Set the current stereo balance value
+
+@param aBalance
+ Balance value to set. Defaults to KMMFBalanceCenter to restore equal left-right balance
+*/
+EXPORT_C void CMidiClientUtility::SetBalanceL(TInt aBalance)
+ {
+ iBody->SetBalanceL(aBalance);
+ }
+
+/**
+Set the priority with which this client plays MIDI data
+
+@param aPriority
+ The Priority Value.
+@param aPref
+ The Priority Preference.
+
+@see CMidiClientUtility::NewL()
+*/
+EXPORT_C void CMidiClientUtility::SetPriorityL(TInt aPriority, TInt aPref)
+ {
+ iBody->SetPriorityL(aPriority, aPref);
+ }
+
+/**
+Get the number of meta data entries currently known about in the currently open
+resource. XMF,SMF meta data are part of the XMF,SMF file header and can thus be examined
+before playback. If there is no XMF,SMF resource open, will return zero.
+Standard MIDI file meta data entries encountered during playback will be passed back
+via MMIDIClientUtilityObserver::MmcuoMetaDataEntryFound()
+
+@return Number of XMF meta data entries currently known about
+*/
+EXPORT_C TInt CMidiClientUtility::NumberOfMetaDataEntriesL() const
+ {
+ return iBody->NumberOfMetaDataEntriesL();
+ }
+
+/**
+Retrieve the specified XMF,SMF meta data entry.
+
+@param aMetaDataIndex
+ Index of the meta data entry to retrieve
+@return Meta data entry. Ownership is passed to the client.
+*/
+EXPORT_C CMMFMetaDataEntry* CMidiClientUtility::GetMetaDataEntryL(TInt aMetaDataIndex) const
+ {
+ return iBody->GetMetaDataEntryL(aMetaDataIndex);
+ }
+
+/**
+Synchronously pass implementation-specific commands to the MIDI engine
+and receive a response
+
+@param aDestination
+ Recipient of the message. Should be initialised with KUidInterfaceMIDI
+ and a TInt describing the server-side object to which the command should be delivered.
+ The TInt will usually be KMMFObjectHandleController, to deliver the message to the
+ controller plugin, which is the default value.
+@param aFunction
+ Index of the function to perform
+@param aDataTo1
+ First command data buffer to send, eg command parameters
+@param aDataTo2
+ Second command data buffer to send, eg data parameters
+@param aDataFrom
+ Buffer to receive data in response to the command.
+ The user must ensure that it is large enough to hold all the data returned.
+*/
+EXPORT_C void CMidiClientUtility::CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom)
+ {
+ iBody->CustomCommandSyncL(aDestination, aFunction, aDataTo1, aDataTo2, aDataFrom);
+ }
+
+/**
+Synchronously pass implementation-specific commands to the MIDI engine.
+
+@param aDestination
+ Recipient of the message. Should be initialised with KUidInterfaceMIDI
+ and a TInt describing the server-side object to which the command should be delivered.
+ The TInt will usually be KMMFObjectHandleController, to deliver the message to the
+ controller plugin, which is the default value.
+@param aFunction
+ Index of the function to perform
+@param aDataTo1
+ First command data buffer to send, eg command parameters
+@param aDataTo2
+ Second command data buffer to send, eg data parameters
+*/
+EXPORT_C void CMidiClientUtility::CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2)
+ {
+ iBody->CustomCommandSyncL(aDestination, aFunction, aDataTo1, aDataTo2);
+ }
+
+/**
+Asynchronously pass implementation-specific commands to the MIDI engine
+and receive a response
+
+@param aDestination
+ aDestination Recipient of the message. Should be initialised with KUidInterfaceMIDI
+ and a TInt describing the server-side object to which the command should be delivered.
+ The TInt will usually be KMMFObjectHandleController, to deliver the message to the
+ controller plugin, which is the default value.
+@param aFunction
+ Index of the function to perform
+@param aDataTo1
+ First command data buffer to send, eg command parameters
+@param aDataTo2
+ Second command data buffer to send, eg data parameters
+@param aDataFrom
+ Buffer to receive data in response to the command.
+ The user must ensure that it is large enough to hold all the data returned.
+@param aStatus
+ Status flag belonging to an active object that will have it's RunL() called
+ when this request complete
+*/
+EXPORT_C void CMidiClientUtility::CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus)
+ {
+ iBody->CustomCommandAsync(aDestination, aFunction, aDataTo1, aDataTo2, aDataFrom, aStatus);
+ }
+
+/**
+Asynchronously pass implementation-specific commands to the MIDI engine
+
+@param aDestination
+ aDestination Recipient of the message. Should be initialised with KUidInterfaceMIDI
+ and a TInt describing the server-side object to which the command should be delivered.
+ The TInt will usually be KMMFObjectHandleController, to deliver the message to the
+ controller plugin, which is the default value.
+@param aFunction
+ Index of the function to perform
+@param aDataTo1
+ First command data buffer to send, eg command parameters
+@param aDataTo2
+ Second command data buffer to send, eg data parameters
+@param aStatus
+ Status flag belonging to an active object that will have it's RunL() called
+ when this request complete
+*/
+EXPORT_C void CMidiClientUtility::CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus)
+ {
+ iBody->CustomCommandAsync(aDestination, aFunction, aDataTo1, aDataTo2, aStatus);
+ }
+
+/**
+Gets a controller's DRM custom command implementation.
+
+@return A pointer to a controller's DRM custom command implementation or NULL
+ if the interface can not be obtained
+*/
+EXPORT_C MMMFDRMCustomCommand* CMidiClientUtility::GetDRMCustomCommand()
+ {
+ return iBody->GetDRMCustomCommand();
+ }
+
+/**
+Set the max polyphony the engine can handle
+
+@param aMaxNotes
+ Max polyphony level, 0 <= PolyphonyL() <= aMaxNotes
+*/
+EXPORT_C void CMidiClientUtility::SetMaxPolyphonyL(TInt aMaxNotes)
+ {
+ iBody->SetMaxPolyphonyL(aMaxNotes);
+ }
+
+/**
+Gets the number of times the current opened resources has to be repeated
+
+@return The number of time the current opened resources has to be repeated
+*/
+EXPORT_C TInt CMidiClientUtility::GetRepeats() const
+ {
+ return iBody->GetRepeats();
+ }
+
+/**
+Loads one or more custom sound banks from a descriptor into memory for use.
+If several banks are loaded with consequent LoadCustomBanksL() function calls,
+the banks are combined if the bank sets have colliding bank numbers
+
+@param aBankData
+ Descriptor containing the custom sound bank
+@param aBankId
+ Identifier of the custom sound bank loaded, occupying no more than 14 bits.
+*/
+EXPORT_C void CMidiClientUtility::LoadCustomBankDataL(const TDesC8& aBankData,TInt& aBankId)
+ {
+ iBody->LoadCustomBankDataL(aBankData, aBankId);
+ }
+
+/**
+Loads an individual instrument from descriptor into custom sound bank memory for use.
+The bank and instrument ids given in the descriptor can be mapped into different bank
+and instrument ids in memory
+
+@param aInstrumentData
+ Descriptor containing the instrument
+@param aBankDataId
+ Identifier of the bank in the descriptor from which to load the instrument,
+ occupying no more than 14 bits
+@param aInstrumentDataId
+ Identifier of the instrument to load. 0 <= aInstrumentId <= 127
+@param aMemoryBankId
+ Identifier of the custom bank in memory to load the instrument into,
+ occupying no more than 14 bits
+@param aMemoryInstrumentId
+ Identifier of the instrument in memory to load the new
+ instrument into. 0 <= aInstrumentId <= 127.
+*/
+EXPORT_C void CMidiClientUtility::LoadCustomInstrumentDataL(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId)
+ {
+ iBody->LoadCustomInstrumentDataL(aInstrumentData, aBankDataId, aInstrumentDataId, aMemoryBankId, aMemoryInstrumentId);
+ }
+
+/**
+Tell the MIDI engine to use a custom bank or a standard bank
+
+@param aCustom
+ If Etrue the custom bank in memory is used otherwise the standard bank
+ is used leaving the custom bank in memory
+*/
+EXPORT_C void CMidiClientUtility::SetBankL(TBool aCustom)
+ {
+ iBody->SetBankL(aCustom);
+ }
+
+/**
+Gets the muting status of a specific track
+
+@param aTrack
+ The track to query
+@return The mute status of the track.
+*/
+EXPORT_C TBool CMidiClientUtility::IsTrackMuteL(TInt aTrack) const
+ {
+ return iBody->IsTrackMuteL(aTrack);
+ }
+
+/**
+Gets the muting status of a specific channel
+
+@param aChannel
+ The channel to query
+@return The mute status of the channel
+*/
+EXPORT_C TBool CMidiClientUtility::IsChannelMuteL(TInt aChannel) const
+ {
+ return iBody->IsChannelMuteL(aChannel);
+ }
+
+/**
+Gets the instrument assigned to a specified channel
+
+@param aChannel
+ Logical channel, 0 <= aChannel <= 15.
+@param aInstrumentId
+ Identifier of the instrument assigned to aChannel. 0 <= iInstrumentId <= 127
+@param aBankId
+ Identifier of the bank that the instrument belongs to, occupying no more than 14 bits
+*/
+EXPORT_C void CMidiClientUtility::GetInstrumentL(TInt aChannel, TInt& aInstrumentId, TInt& aBankId)
+ {
+ iBody->GetInstrumentL(aChannel, aInstrumentId, aBankId);
+ }
+
+/**
+Get the maximum polyphony level that the engine can handle
+
+@return The maximum number of simultaneous notes the engine can handle.
+ 0 <= PolyphonyL() <= MaxPolyphonyL()
+*/
+EXPORT_C TInt CMidiClientUtility::MaxPolyphonyL() const
+ {
+ return iBody->MaxPolyphonyL();
+ }
+