// 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