CMidiClientUtility Class Reference

#include <midiclientutility.h>

Link against: midiclient.lib

class CMidiClientUtility : public CBase

Inherits from

CMidiClientUtility
- CBase

Nested Classes and Structures

CMidiClientUtility::CBody

Public Member Functions
virtual	~CMidiClientUtility()
IMPORT_C TReal32	ChannelVolumeL(TInt)
IMPORT_C TInt	ChannelsSupportedL()
IMPORT_C void	Close()
IMPORT_C TBool	CustomBankLoadedL(TInt)
IMPORT_C void	CustomCommandAsync(const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TDes8 &, TRequestStatus &)
IMPORT_C void	CustomCommandAsync(const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TRequestStatus &)
IMPORT_C void	CustomCommandSyncL(const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TDes8 &)
IMPORT_C void	CustomCommandSyncL(const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &)
IMPORT_C TInt64	DurationMicroBeatsL()
IMPORT_C TTimeIntervalMicroSeconds	DurationMicroSecondsL()
IMPORT_C TInt	GetBalanceL()
IMPORT_C TInt	GetBankIdL(TBool, TInt)
IMPORT_C MMMFDRMCustomCommand *	GetDRMCustomCommand()
IMPORT_C TInt	GetInstrumentIdL(TInt, TBool, TInt)
IMPORT_C void	GetInstrumentL(TInt, TInt &, TInt &)
IMPORT_C CMMFMetaDataEntry *	GetMetaDataEntryL(TInt)
IMPORT_C TInt	GetRepeats()
IMPORT_C HBufC *	InstrumentNameL(TInt, TBool, TInt)
IMPORT_C TBool	IsChannelMuteL(TInt)
IMPORT_C TBool	IsTrackMuteL(TInt)
IMPORT_C void	LoadCustomBankDataL(const TDesC8 &, TInt &)
IMPORT_C void	LoadCustomBankL(const TDesC &, TInt &)
IMPORT_C void	LoadCustomInstrumentDataL(const TDesC8 &, TInt, TInt, TInt, TInt)
IMPORT_C void	LoadCustomInstrumentL(const TDesC &, TInt, TInt, TInt, TInt)
IMPORT_C TReal32	MaxChannelVolumeL()
IMPORT_C TInt	MaxPlaybackRateL()
IMPORT_C TInt	MaxPolyphonyL()
IMPORT_C TInt	MaxVolumeL()
IMPORT_C const TDesC8 &	MimeTypeL()
IMPORT_C TInt	MinPlaybackRateL()
IMPORT_C CMidiClientUtility *	NewL(MMidiClientUtilityObserver &, TInt, TInt)
IMPORT_C CMidiClientUtility *	NewL(MMidiClientUtilityObserver &, TInt, TInt, TBool)
IMPORT_C void	NoteOffL(TInt, TInt, TInt)
IMPORT_C void	NoteOnL(TInt, TInt, TInt)
IMPORT_C TInt	NumTracksL()
IMPORT_C TInt	NumberOfBanksL(TBool)
IMPORT_C TInt	NumberOfInstrumentsL(TInt, TBool)
IMPORT_C TInt	NumberOfMetaDataEntriesL()
IMPORT_C void	OpenDes(const TDesC8 &)
IMPORT_C void	OpenFile(const TDesC &)
IMPORT_C void	OpenFile(const RFile &)
IMPORT_C void	OpenFile(const TMMSource &)
IMPORT_C void	OpenUrl(const TDesC &, TInt, const TDesC8 &)
IMPORT_C HBufC *	PercussionKeyNameL(TInt, TInt, TBool, TInt)
IMPORT_C TInt	PitchTranspositionCentsL()
IMPORT_C void	Play()
IMPORT_C void	PlayNoteL(TInt, TInt, const TTimeIntervalMicroSeconds &, TInt, TInt)
IMPORT_C void	PlayNoteL(TInt, TInt, const TTimeIntervalMicroSeconds &, const TTimeIntervalMicroSeconds &, TInt, TInt)
IMPORT_C TInt	PlaybackRateL()
IMPORT_C TInt	PolyphonyL()
IMPORT_C TInt64	PositionMicroBeatsL()
IMPORT_C TTimeIntervalMicroSeconds	PositionMicroSecondsL()
IMPORT_C TInt	SendMessageL(const TDesC8 &)
IMPORT_C TInt	SendMessageL(const TDesC8 &, const TTimeIntervalMicroSeconds &)
IMPORT_C void	SendMipMessageL(const RArray< TMipMessageEntry > &)
IMPORT_C void	SetBalanceL(TInt)
IMPORT_C void	SetBankL(TBool)
IMPORT_C void	SetChannelMuteL(TInt, TBool)
IMPORT_C void	SetChannelVolumeL(TInt, TReal32)
IMPORT_C void	SetInstrumentL(TInt, TInt, TInt)
IMPORT_C void	SetMaxPolyphonyL(TInt)
IMPORT_C TInt	SetPitchTranspositionL(TInt)
IMPORT_C void	SetPlaybackRateL(TInt)
IMPORT_C void	SetPositionMicroBeatsL(TInt64)
IMPORT_C void	SetPositionMicroSecondsL(const TTimeIntervalMicroSeconds &)
IMPORT_C void	SetPriorityL(TInt, TInt)
IMPORT_C void	SetRepeatsL(TInt, const TTimeIntervalMicroSeconds &)
IMPORT_C void	SetStopTimeL(const TTimeIntervalMicroSeconds &)
IMPORT_C void	SetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds &, TInt64)
IMPORT_C void	SetTempoL(TInt)
IMPORT_C void	SetTrackMuteL(TInt, TBool)
IMPORT_C void	SetVolumeL(TInt)
IMPORT_C void	SetVolumeRampL(const TTimeIntervalMicroSeconds &)
IMPORT_C TMidiState	State()
IMPORT_C void	Stop(const TTimeIntervalMicroSeconds &)
IMPORT_C void	StopNotes(TInt)
IMPORT_C void	StopTimeL(TTimeIntervalMicroSeconds &)
IMPORT_C TInt	TempoMicroBeatsPerMinuteL()
IMPORT_C void	UnloadAllCustomBanksL()
IMPORT_C void	UnloadCustomBankL(TInt)
IMPORT_C void	UnloadCustomInstrumentL(TInt, TInt)
IMPORT_C TInt	VolumeL()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

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

Constructor & Destructor Documentation

~CMidiClientUtility ( )

~CMidiClientUtility

(

)

[virtual]

Destructor

Member Function Documentation

ChannelVolumeL ( TInt )

IMPORT_C TReal32

ChannelVolumeL

(

TInt

aChannel

)

const

Get the current volume setting of a logical channel

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

Return Value: Volume currently set on the specified channel in decibels

ChannelsSupportedL ( )

IMPORT_C TInt

ChannelsSupportedL

(

)

const

Gets the maximum number of logical channels supported by the MIDI engine.

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

Close ( )

IMPORT_C void

(

)

Asynchronous function which closes any currently open resources, such as files, descriptors or URLs in use. Does nothing if there is nothing currently open.

CustomBankLoadedL ( TInt )

IMPORT_C TBool

CustomBankLoadedL

(

TInt

aBankCollectionIndex

)

const

Query if a bank has been loaded to the memory

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

Return Value: ETrue if the specified bank is in memory, EFalse otherwise

CustomCommandAsync ( const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TDes8 &, TRequestStatus & )

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

Asynchronously pass implementation-specific commands to the MIDI engine and receive a response

Parameters
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.
aFunction	Index of the function to perform
aDataTo1	First command data buffer to send, eg command parameters
aDataTo2	Second command data buffer to send, eg data parameters
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.
aStatus	Status flag belonging to an active object that will have it's RunL() called when this request complete

CustomCommandAsync ( const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TRequestStatus & )

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

Asynchronously pass implementation-specific commands to the MIDI engine

Parameters
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.
aFunction	Index of the function to perform
aDataTo1	First command data buffer to send, eg command parameters
aDataTo2	Second command data buffer to send, eg data parameters
aStatus	Status flag belonging to an active object that will have it's RunL() called when this request complete

CustomCommandSyncL ( const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 &, TDes8 & )

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

Synchronously pass implementation-specific commands to the MIDI engine and receive a response

Parameters
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.
aFunction	Index of the function to perform
aDataTo1	First command data buffer to send, eg command parameters
aDataTo2	Second command data buffer to send, eg data parameters
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.

CustomCommandSyncL ( const TMMFMessageDestinationPckg &, TInt, const TDesC8 &, const TDesC8 & )

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

Synchronously pass implementation-specific commands to the MIDI engine.

Parameters
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.
aFunction	Index of the function to perform
aDataTo1	First command data buffer to send, eg command parameters
aDataTo2	Second command data buffer to send, eg data parameters

DurationMicroBeatsL ( )

IMPORT_C TInt64

DurationMicroBeatsL

(

)

const

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

Return Value: Duration in microbeats (beats * 1000000).

DurationMicroSecondsL ( )

IMPORT_C TTimeIntervalMicroSeconds

DurationMicroSecondsL

(

)

const

Gets the length of the currently open MIDI resource in micro-seconds

Return Value: Duration in microseconds (seconds * 1000000).

GetBalanceL ( )

IMPORT_C TInt

GetBalanceL

(

)

const

Get the current stereo balance value

Return Value: Balance value ranging from KMMFBalanceMaxLeft to KMMFBalanceMaxRight

GetBankIdL ( TBool, TInt )

IMPORT_C TInt	GetBankIdL	(	TBool	aCustom,
			TInt	aBankIndex
		)	const

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

Parameters
aCustom	Specifies whether to reference a custom or standard sound bank
aBankIndex	Index of sound bank where 0 <= aBankIndex < NumberOfBanksL()

Return Value: Identifier of the specified bank occupying, at most, 14 bits

GetDRMCustomCommand ( )

IMPORT_C MMMFDRMCustomCommand *

GetDRMCustomCommand

(

)

Gets a controller's DRM custom command implementation.

Return Value: A pointer to a controller's DRM custom command implementation or NULL if the interface can not be obtained

GetInstrumentIdL ( TInt, TBool, TInt )

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

Gets the identifier of an instrument.

Parameters
aBankId	Identifier of the sound bank to reference, occupying no more than 14 bits.
aCustom	Specifies whether to reference a custom or standard sound bank.
aInstrumentIndex	Index of the instrument to reference where 0 <= aInstrumentIndex < NumberOfInstrumentsL().

Return Value: 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.

GetInstrumentL ( TInt, TInt &, TInt & )

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

Gets the instrument assigned to a specified channel

Parameters
aChannel	Logical channel, 0 <= aChannel <= 15.
aInstrumentId	Identifier of the instrument assigned to aChannel. 0 <= iInstrumentId <= 127
aBankId	Identifier of the bank that the instrument belongs to, occupying no more than 14 bits

GetMetaDataEntryL ( TInt )

IMPORT_C CMMFMetaDataEntry *

GetMetaDataEntryL

(

TInt

aMetaDataIndex

)

const

Retrieve the specified XMF,SMF meta data entry.

Parameters
aMetaDataIndex	Index of the meta data entry to retrieve

Return Value: Meta data entry. Ownership is passed to the client.

GetRepeats ( )

IMPORT_C TInt

GetRepeats

(

)

const

Gets the number of times the current opened resources has to be repeated

Return Value: The number of time the current opened resources has to be repeated

InstrumentNameL ( TInt, TBool, TInt )

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

Gets the name of the given instrument.

Parameters
aBankId	Identifier of the bank that the instrument belongs to, occupying no more than 14 bits
aCustom	Specifies whether to reference a custom or standard sound bank
aInstrumentId	Identifier of the instrument under scrutiny. 0 <= iInstrumentId <= 127.

Return Value: Buffer containing the name of the specified instrument. If it has no name then an empty descriptor is returned

IsChannelMuteL ( TInt )

IMPORT_C TBool

IsChannelMuteL

(

TInt

aChannel

)

const

Gets the muting status of a specific channel

Parameters
aChannel	The channel to query

Return Value: The mute status of the channel

IsTrackMuteL ( TInt )

IMPORT_C TBool

IsTrackMuteL

(

TInt

aTrack

)

const

Gets the muting status of a specific track

Parameters
aTrack	The track to query

Return Value: The mute status of the track.

LoadCustomBankDataL ( const TDesC8 &, TInt & )

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

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

Parameters
aBankData	Descriptor containing the custom sound bank
aBankCollectionIndex	Identifier of the custom sound bank loaded, occupying no more than 14 bits.

LoadCustomBankL ( const TDesC &, TInt & )

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

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

Parameters
aFileName	Name of the file containing the custom sound bank
aBankCollectionIndex	Identifier of the custom sound bank loaded, occupying no more than 14 bits

LoadCustomInstrumentDataL ( const TDesC8 &, TInt, TInt, TInt, TInt )

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

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

Parameters
aInstrumentData	Descriptor containing the instrument
aBankDataId	Identifier of the bank in the descriptor from which to load the instrument, occupying no more than 14 bits
aInstrumentDataId	Identifier of the instrument to load. 0 <= aInstrumentId <= 127
aMemoryBankId	Identifier of the custom bank in memory to load the instrument into, occupying no more than 14 bits
aMemoryInstrumentId	Identifier of the instrument in memory to load the new instrument into. 0 <= aInstrumentId <= 127.

LoadCustomInstrumentL ( const TDesC &, TInt, TInt, TInt, TInt )

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

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

Parameters
aFileName	Name of the file containing the instrument
aFileBankId	Identifier of the bank in the file from which to load the instrument, occupying no more than 14 bits
aFileInstrumentId	Identifier of the instrument to load. 0 <= aInstrumentId <= 127
aMemoryBankId	Identifier of the custom bank in memory to load the instrument into, occupying no more than 14 bits.
aMemoryInstrumentId	Identifier of the instrument in memory to load the new instrument into. 0 <= aInstrumentId <= 127.

MaxChannelVolumeL ( )

IMPORT_C TReal32

MaxChannelVolumeL

(

)

const

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

Return Value: Maximum volume setting. Minimum value is -infinity dB, which is the smallest possible value that TReal32 supports.

MaxPlaybackRateL ( )

IMPORT_C TInt

MaxPlaybackRateL

(

)

const

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

See also: SetPlaybackRate() for milli-percentage details

Return Value: Maximum playback rate supported by MIDI player

MaxPolyphonyL ( )

IMPORT_C TInt

MaxPolyphonyL

(

)

const

Get the maximum polyphony level that the engine can handle

Return Value: The maximum number of simultaneous notes the engine can handle. 0 <= PolyphonyL() <= MaxPolyphonyL()

MaxVolumeL ( )

IMPORT_C TInt

MaxVolumeL

(

)

const

Maximum volume setting that may be applied overall.

Return Value: Maximum volume setting. Minimum value is always zero which is silent

MimeTypeL ( )

IMPORT_C const TDesC8 &

MimeTypeL

(

)

Gets the MIME type of the MIDI resource currently open

Return Value: Descriptor containing the MIDI mime type

MinPlaybackRateL ( )

IMPORT_C TInt

MinPlaybackRateL

(

)

const

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

See also: SetPlaybackRate() for milli-percentage details.

Return Value: Minimum playback rate supported by MIDI player.

NewL ( MMidiClientUtilityObserver &, TInt, TInt )

IMPORT_C CMidiClientUtility *	NewL	(	MMidiClientUtilityObserver &	aObserver,
			TInt	aPriority = EMdaPriorityNormal,
			TInt	aPref = EMdaPriorityPreferenceTimeAndQuality
		)	[static]

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.

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.

Parameters
aObserver	Reference to an object to receive callbacks on completion of asynchronous functions.
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.
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 Value: Fully constructed utility object ready to have an OpenXxxx() function called.

NewL ( MMidiClientUtilityObserver &, TInt, TInt, TBool )

IMPORT_C CMidiClientUtility *	NewL	(	MMidiClientUtilityObserver &	aObserver,
			TInt	aPriority,
			TInt	aPref,
			TBool	aUseSharedHeap
		)	[static]

Parameters
aObserver	Reference to an object to receive callbacks on completion of asynchronous functions.
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.
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.
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 Value: Fully constructed utility object ready to have an OpenXxxx() function called.

NoteOffL ( TInt, TInt, TInt )

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

Synchronous function to terminate playback of a note. If no corresponding note is found then no error is raised.

Parameters
aChannel	Logical channel on which the note is playing. 0 <= aChannel <= 15.
aNote	Note to terminate. 0 <= aNote <= 127.
aVelocity	Velocity with which to stop the note. 0 <= aVelocity <= 127. There is no standard behaviour corresponding with note off velocity.

NoteOnL ( TInt, TInt, TInt )

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

Synchronous function to commence playback of a note. Multiple calls to this function will be accommodated as far as the MIDI engine can manage

Parameters
aChannel	Logical channel to play note on. 0 <= aChannel <= 15
aNote	Note to play. 0 <= aNote <= 127
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.

NumTracksL ( )

IMPORT_C TInt

NumTracksL

(

)

const

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

Return Value: Number of tracks

NumberOfBanksL ( TBool )

IMPORT_C TInt

NumberOfBanksL

(

TBool

aCustom

)

const

Gets the number of standard or custom sound banks currently available

Parameters
aCustom	Specifies whether to reference a custom or standard sound bank

Return Value: Number of custom or standard sound banks available

NumberOfInstrumentsL ( TInt, TBool )

IMPORT_C TInt	NumberOfInstrumentsL	(	TInt	aBankId,
			TBool	aCustom
		)	const

Gets the number of instruments available in a given sound bank

Parameters
aBankId	Identifier of sound bank to reference, occupying no more than 14 bits
aCustom	Specifies whether to reference a custom or standard sound bank

Return Value: Count of the number of instruments available for the specified sound bank

NumberOfMetaDataEntriesL ( )

IMPORT_C TInt

NumberOfMetaDataEntriesL

(

)

const

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 Value: Number of XMF meta data entries currently known about

OpenDes ( const TDesC8 & )

IMPORT_C void

OpenDes

(

const TDesC8 &

aDescriptor

)

Asynchronous function to open a descriptor containing MIDI data and perform initialisation ready for playback

Parameters
aDescriptor	descriptor containing MIDI data

OpenFile ( const TDesC & )

IMPORT_C void

OpenFile

(

const TDesC &

aFileName

)

Asynchronous function to open a file containing MIDI data and perform initialisation ready for playback

Parameters
aFileName	Name of the MIDI file to open

OpenFile ( const RFile & )

IMPORT_C void

OpenFile

(

const RFile &

aFile

)

Asynchronous function to open a file containing MIDI data and perform initialisation ready for playback

Parameters
aFile	Open shared protected session handle to the midi file to read

OpenFile ( const TMMSource & )

IMPORT_C void

OpenFile

(

const TMMSource &

aSource

)

Asynchronous function to open a file containing MIDI data and perform initialisation ready for playback

OpenUrl ( const TDesC &, TInt, const TDesC8 & )

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

Asynchronous function to open a URL containing MIDI data and perform initialisation ready for playback

Parameters
aUrl	Uniform Resource Locator for a MIDI data stream
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
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.

PercussionKeyNameL ( TInt, TInt, TBool, TInt )

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

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

Parameters
aNote	Note to query. 0 <= aNote <= 127
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.
aCustom	Specifies whether to reference a custom or standard sound bank
aInstrumentId	Identifier of an instrument

Return Value: Descriptor containing the name of the percussion key. If the key does not have a name then an empty descriptor is returned

PitchTranspositionCentsL ( )

IMPORT_C TInt

PitchTranspositionCentsL

(

)

const

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

Return Value: Pitch shift in cents, i.e. semitones * 100. One octave equals 1200 cents

Play ( )

IMPORT_C void

Play

(

)

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

PlayNoteL ( TInt, TInt, const TTimeIntervalMicroSeconds &, TInt, TInt )

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

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

Parameters
aChannel	Logical channel to play note on. 0 <= aChannel <= 15.
aNote	Note to play. 0 <= aNote <= 127
aDuration	Length of time to play note for.
aNoteOnVelocity	Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.
aNoteOffVelocity	Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.

PlayNoteL ( TInt, TInt, const TTimeIntervalMicroSeconds &, const TTimeIntervalMicroSeconds &, TInt, TInt )

IMPORT_C void	PlayNoteL	(	TInt	aChannel,
			TInt	aNote,
			const TTimeIntervalMicroSeconds &	aStartTime,
			const TTimeIntervalMicroSeconds &	aDuration,
			TInt	aNoteOnVelocity,
			TInt	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

Parameters
aChannel	Logical channel to play note on. 0 <= aChannel <= 15.
aNote	Note to play. 0 <= aNote <= 127
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
aDuration	Length of time to play note for.
aNoteOnVelocity	Velocity with which to start the note. 0 <= aNoteOnVelocity <= 127.
aNoteOffVelocity	Velocity with which to stop the note. 0 <= aNoteOffVelocity <= 127.

PlaybackRateL ( )

IMPORT_C TInt

PlaybackRateL

(

)

const

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 Value: Current playback rate in percent times 1000, i.e., 100000 means original playback speed, 200000 means double speed, and 50000 means half speed playback

PolyphonyL ( )

IMPORT_C TInt

PolyphonyL

(

)

const

Gets the number of currently active voices.

Return Value: The number of currently active voices

PositionMicroBeatsL ( )

IMPORT_C TInt64

PositionMicroBeatsL

(

)

const

Gets the current metrical position of the MIDI resource being played

Return Value: Microbeats (BPM*1000000) relative to the start of the resource

PositionMicroSecondsL ( )

IMPORT_C TTimeIntervalMicroSeconds

PositionMicroSecondsL

(

)

const

Gets the current temporal position of the MIDI resource being played.

Return Value: Microseconds relative to the start of the resource

SendMessageL ( const TDesC8 & )

IMPORT_C TInt

SendMessageL

(

const TDesC8 &

aMidiMessage

)

Sends a single MIDI message to the MIDI engine

Parameters
aMidiMessage	Descriptor containing the MIDI message data. If there are several MIDI messages in the buffer, only the first one is processed

SendMessageL ( const TDesC8 &, const TTimeIntervalMicroSeconds & )

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

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

Parameters
aMidiMessage	Descriptor containing the MIDI message data. If there are several MIDI messages in the buffer, only the first one is processed
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

SendMipMessageL ( const RArray< TMipMessageEntry > & )

IMPORT_C void

SendMipMessageL

(

const RArray< TMipMessageEntry > &

aEntry

)

Sends a mip message to the MIDI engine. This is a convenience function, because the same functionality could be achieved with the SendMessage() function

Parameters
aEntry	Array of logical {channel, MIP} value pairs to send, highest priority first

SetBalanceL ( TInt )

IMPORT_C void

SetBalanceL

(

TInt

aBalance = KMMFBalanceCenter

)

Set the current stereo balance value

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

SetBankL ( TBool )

IMPORT_C void

SetBankL

(

TBool

aCustom

)

DeprecatedSetBankL is deprecated due to Mobile XMF specification requirement that user instruments (custom instruments) override standard instruments.

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

Parameters
aCustom	If Etrue the custom bank in memory is used otherwise the standard bank is used leaving the custom bank in memory

SetChannelMuteL ( TInt, TBool )

IMPORT_C void	SetChannelMuteL	(	TInt	aChannel,
			TBool	aMuted
		)

Set the muting state of a channel without changing its volume setting. When unmuted the channel goes back to its previous volume setting

Parameters
aChannel	Logical channel to set the mute state of. 0 <= aChannel <= 15.
aMuted	ETrue to mute the channel, EFalse to unmute it.

SetChannelVolumeL ( TInt, TReal32 )

IMPORT_C void	SetChannelVolumeL	(	TInt	aChannel,
			TReal32	aVolumeInDecibels
		)

Set the volume of a channel.

Parameters
aChannel	Logical channel to set the volume on. 0 <= aChannel <= 15
aVolumeInDecibels	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()

SetInstrumentL ( TInt, TInt, TInt )

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

Sets a logical channel to use the given instrument.

Parameters
aChannel	Logical channel to set the instrument for. 0 <= aChannel <= 15
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
aInstrumentId	Identifier of the instrument under scrutiny. 0 <= iInstrumentId <= 127.

SetMaxPolyphonyL ( TInt )

IMPORT_C void

SetMaxPolyphonyL

(

TInt

aMaxNotes

)

Set the max polyphony the engine can handle

Parameters
aMaxNotes	Max polyphony level, 0 <= PolyphonyL() <= aMaxNotes

SetPitchTranspositionL ( TInt )

IMPORT_C TInt

SetPitchTranspositionL

(

TInt

aCents

)

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.

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

Return Value: Actual pitch shift applied - may differ from the requested value due to limitations of the MIDI engine

SetPlaybackRateL ( TInt )

IMPORT_C void

SetPlaybackRateL

(

TInt

aRate

)

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.

Parameters
aRate	Playback rate in percent times 1000, i.e., 100000 means original playback speed, 200000 means double speed, and 50000 means half speed playback

SetPositionMicroBeatsL ( TInt64 )

IMPORT_C void

SetPositionMicroBeatsL

(

TInt64

aMicroBeats

)

Change the position of the currently playing MIDI resource to the given position. May be called whenever a MIDI resource is open.

Parameters
aMicroBeats	Metrical position to move to. Clamped to (0, DurationMicroBeatsL()).

SetPositionMicroSecondsL ( const TTimeIntervalMicroSeconds & )

IMPORT_C void

SetPositionMicroSecondsL

(

const TTimeIntervalMicroSeconds &

aPosition

)

Change the position of the currently playing MIDI resource to the given position. May be called whenever a MIDI resource is open

Parameters
aPosition	Temporal position to move to. Clamped to (0, DurationMicroSecondsL()).

SetPriorityL ( TInt, TInt )

IMPORT_C void	SetPriorityL	(	TInt	aPriority,
			TInt	aPref
		)

Set the priority with which this client plays MIDI data

SetRepeatsL ( TInt, const TTimeIntervalMicroSeconds & )

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

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

Parameters
aRepeatNumberOfTimes	Number of time to repeat the resource during playback. This includes the first playing
aTrailingSilence	Time in microseconds to pause between repeats

SetStopTimeL ( const TTimeIntervalMicroSeconds & )

IMPORT_C void

SetStopTimeL

(

const TTimeIntervalMicroSeconds &

aStopTime

)

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

Parameters
aStopTime	Time at which playback will stop, relative to the start of the resource. Clamped to 0 and the duration of the resource

SetSyncUpdateCallbackIntervalL ( const TTimeIntervalMicroSeconds &, TInt64 )

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

Sets the frequency at which MMIDIClientUtilityObserver::MmcuoSyncUpdateL() is called to allow other components to synchronise with playback of this MIDI resource

Parameters
aMicroSeconds	Temporal interval to callback at. Used in preference to aMicroBeats if both are set
aMicroBeats	Metrical interval to callback at. Set both parameters to zero to cancel.

SetTempoL ( TInt )

IMPORT_C void

SetTempoL

(

TInt

aMicroBeatsPerMinute

)

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

Parameters
aMicroBeatsPerMinute	Tempo in microbeats per minute (BPM*1000000) to set

SetTrackMuteL ( TInt, TBool )

IMPORT_C void	SetTrackMuteL	(	TInt	aTrack,
			TBool	aMuted
		)	const

Mutes or unmutes a particular track

Parameters
aTrack	Index of the track to mute - 0 <= aTrack < NumTracksL().
aMuted	ETrue to mute the track, EFalse to unmute it.

SetVolumeL ( TInt )

IMPORT_C void

SetVolumeL

(

TInt

aVolume

)

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).

Parameters
aVolume	Overall volume setting to use

SetVolumeRampL ( const TTimeIntervalMicroSeconds & )

IMPORT_C void

SetVolumeRampL

(

const TTimeIntervalMicroSeconds &

aRampDuration

)

Length of time over which the volume is faded up from zero to the current settings when playback is started.

Parameters
aRampDuration	Duration of the ramping period.

State ( )

IMPORT_C TMidiState

State

(

)

const

Gets the current state of the MIDI client utility with regard to MIDI resources

Return Value: The current state of the utility

Stop ( const TTimeIntervalMicroSeconds & )

IMPORT_C void

Stop

(

const TTimeIntervalMicroSeconds &

aFadeOutDuration

)

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

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

StopNotes ( TInt )

IMPORT_C void

StopNotes

(

TInt

aChannel

)

Stops the playback of all notes on the given channel, by means of an All Notes Off MIDI message

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

StopTimeL ( TTimeIntervalMicroSeconds & )

IMPORT_C void

StopTimeL

(

TTimeIntervalMicroSeconds &

aStopTime

)

const

Get the stop time currently set for the MIDI resource

Parameters
aStopTime	Time at which playback will stop, relative to the start of the resource

TempoMicroBeatsPerMinuteL ( )

IMPORT_C TInt

TempoMicroBeatsPerMinuteL

(

)

const

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 Value: Tempo at the current position of the currently open resource in microbeats per minute, i.e. BPM * 1000000. Filled in by the controller framework

UnloadAllCustomBanksL ( )

IMPORT_C void

UnloadAllCustomBanksL

(

)

Removes all custom sound banks from memory.

UnloadCustomBankL ( TInt )

IMPORT_C void

UnloadCustomBankL

(

TInt

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.

Parameters
aBankCollectionIndex	Identifier of the custom sound bank to unload, occupying no more than 14 bits

UnloadCustomInstrumentL ( TInt, TInt )

IMPORT_C void	UnloadCustomInstrumentL	(	TInt	aCustomBankId,
			TInt	aInstrumentId
		)

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

Parameters
aCustomBankId	Identifier of the custom sound bank containing the instrument to unload, occupying no more than 14 bits.
aInstrumentId	Identifier of the instrument to unload. 0 <= aInstrumentId <= 127

VolumeL ( )

IMPORT_C TInt

VolumeL

(

)

const

Gets the overall volume of the MIDI client.

Return Value: The current overall volume setting