1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #include <midiclientutility.h>

    17 #include "midiclientutilitybody.h"

    18 

    19 

    20 /**

    21 Static factory function for creating a MIDI client utility object.

    22 This function is synchronous, unlike the other factory functions,

    23 because it doesn't need to perform any MIDI resource initialisation.

    24 

    25 @param aObserver

    26        Reference to an object to receive callbacks on completion of asynchronous functions.

    27 @param aPriority

    28        The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and 

    29        EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request.

    30 @param aPref

    31        The Priority Preference - an additional audio policy parameter. The suggested default is 

    32        EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional 

    33        values may be supported by given phones and/or platforms, but should not be depended upon by 

    34        portable code.

    35 @param aUseSharedHeap

    36 	   Select if the underlying controller will have its own heap or share a single heap with other

    37 	   controller instances.

    38 	   The default behaviour, or if this value is EFalse, is that each controller is created with

    39 	   its own heap. The alternative, if the value is ETrue, is that controllers share a special

    40 	   heap with other controllers created the same way. Each heap uses a chunk, so this avoids

    41 	   situations where the number of chunks per process is limited. The default behaviour is

    42 	   generally to be preferred, and should give lower overall memory usage. However, if many

    43 	   controllers are to be created for a particular thread, then ETrue should be provided to

    44 	   prevent running out of heaps or chunks.

    45 @return Fully constructed utility object ready to have an OpenXxxx() function called.

    46 

    47 Note: The Priority Value and Priority Preference are used primarily when deciding what to do when

    48 several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference, 

    49 the adaptation may consider other parameters such as the SecureId and Capabilities of the client process. 

    50 Whatever, the decision  as to what to do in such situations is up to the audio adaptation, and may

    51 vary between different phones. Portable applications are advised not to assume any specific behaviour. 

    52 */

    53 EXPORT_C CMidiClientUtility* CMidiClientUtility::NewL(MMidiClientUtilityObserver& aObserver, TInt aPriority, TInt aPref, TBool aUseSharedHeap)

    54 	{

    55 	CMidiClientUtility* self = new(ELeave) CMidiClientUtility();

    56 	CleanupStack::PushL(self);

    57 	self->iBody = CMidiClientUtility::CBody::NewL(self, aObserver, aPriority, aPref, aUseSharedHeap );

    58 	CleanupStack::Pop(self);

    59 	return self;

    60 	}

    61 	

    62 /**

    63 Static factory function for creating a MIDI client utility object.

    64 This function is synchronous, unlike the other factory functions,

    65 because it doesn't need to perform any MIDI resource initialisation

    66 The underlying controller that is created will be given its own heap.

    67 

    68 @param aObserver

    69        Reference to an object to receive callbacks on completion of asynchronous functions.

    70 @param aPriority

    71        The Priority Value - this client's relative priority. This is a value between EMdaPriorityMin and 

    72        EMdaPriorityMax and represents a relative priority. A higher value indicates a more important request.

    73 @param aPref

    74        The Priority Preference - an additional audio policy parameter. The suggested default is 

    75        EMdaPriorityPreferenceNone. Further values are given by TMdaPriorityPreference, and additional 

    76        values may be supported by given phones and/or platforms, but should not be depended upon by 

    77        portable code.

    78 @return Fully constructed utility object ready to have an OpenXxxx() function called.

    79 

    80 Note: The Priority Value and Priority Preference are used primarily when deciding what to do when

    81 several audio clients attempt to play or record simultaneously. In addition to the Priority Value and Preference, 

    82 the adaptation may consider other parameters such as the SecureId and Capabilities of the client process. 

    83 Whatever, the decision  as to what to do in such situations is up to the audio adaptation, and may

    84 vary between different phones. Portable applications are advised not to assume any specific behaviour. 

    85 */

    86 EXPORT_C CMidiClientUtility* CMidiClientUtility::NewL(MMidiClientUtilityObserver& aObserver, TInt aPriority, TInt aPref)

    87 	{

    88 	return NewL( aObserver, aPriority, aPref, EFalse );

    89 	}

    90 

    91 CMidiClientUtility::~CMidiClientUtility()

    92 	{

    93 	delete iBody;

    94 	}

    95 

    96 /**

    97 Asynchronous function to open a file containing MIDI data and perform

    98 initialisation ready for playback

    99 

   100 @param aFileName Name of the MIDI file to open

   101 */

   102 EXPORT_C void CMidiClientUtility::OpenFile(const TDesC& aFileName)

   103 	{

   104 	iBody->OpenFile(aFileName);

   105 	}

   106 	

   107 /**

   108 Asynchronous function to open a file containing MIDI data and perform

   109 initialisation ready for playback

   110 

   111 @param aFile Open shared protected session handle to the midi file to read

   112 */

   113 EXPORT_C void CMidiClientUtility::OpenFile(const RFile& aFile)

   114 	{

   115 	iBody->OpenFile(const_cast<RFile&>(aFile));

   116 	}

   117 

   118 /**

   119 Asynchronous function to open a file containing MIDI data and perform

   120 initialisation ready for playback

   121 

   122 @param aFileSource TFileSource object which references either a filename or a

   123 file handle to the midi file to read

   124 */

   125 EXPORT_C void CMidiClientUtility::OpenFile(const TMMSource& aSource)

   126 	{

   127 	iBody->OpenFile(aSource);

   128 	}

   129 

   130 /**

   131 Asynchronous function to open a descriptor containing MIDI data and perform

   132 initialisation ready for playback

   133 

   134 @param aDescriptor descriptor containing MIDI data

   135 */

   136 EXPORT_C void CMidiClientUtility::OpenDes(const TDesC8& aDescriptor)

   137 	{

   138 	iBody->OpenDes(aDescriptor);

   139 	}

   140 

   141 /**

   142 Asynchronous function to open a URL containing MIDI data and perform

   143 initialisation ready for playback

   144 

   145 @param  aUrl

   146         Uniform Resource Locator for a MIDI data stream

   147 @param  aIapId

   148         Identifier of the Internet Access Point to use -

   149         available from CommDB, the comms connections database.

   150         Defaults to using the default access point, as defined by CommDB

   151 @param  aMimeType

   152         Mime type of the MIDI data stream to be played.

   153         Defaults to nothing in which case the an attempt will be made to recognise the type of the MIDI data automatically.

   154 */

   155 EXPORT_C void CMidiClientUtility::OpenUrl(const TDesC& aUrl,TInt aIapId,const TDesC8& aMimeType)

   156 	{

   157 	iBody->OpenUrl(aUrl, aIapId, aMimeType);

   158 	}

   159 

   160 /**

   161 Asynchronous function to initiate or resume playback of a previously opened resource.

   162 Also used to start an internal timer to establish a zero-time for the media stream

   163 time relative to which commands with timestamps are timed against

   164 */

   165 EXPORT_C void CMidiClientUtility::Play()

   166 	{

   167 	iBody->Play();

   168 	}

   169 

   170 /**

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

   172 Pauses the internal timer if no resource is open

   173 

   174 @param aFadeOutDuration

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

   176 */

   177 EXPORT_C void CMidiClientUtility::Stop(const TTimeIntervalMicroSeconds& aFadeOutDuration)

   178 	{

   179 	iBody->Stop(aFadeOutDuration);

   180 	}

   181 

   182 /**

   183 Asynchronous function which closes any currently open resources, such as files, descriptors or URLs in use.

   184 Does nothing if there is nothing currently open.

   185 */

   186 EXPORT_C void CMidiClientUtility::Close()

   187 	{

   188 	iBody->Close();

   189 	}

   190 

   191 /**

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

   193 

   194 @return The current state of the utility

   195 */

   196 EXPORT_C TMidiState CMidiClientUtility::State() const

   197 	{

   198 	return iBody->State();

   199 	}

   200 

   201 /**

   202 Synchronous function to play a single note.

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

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

   205 

   206 @param aChannel 

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

   208 @param aNote 

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

   210 @param aDuration 

   211        Length of time to play note for.

   212 @param aNoteOnVelocity 

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

   214 @param aNoteOffVelocity 

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

   216 */

   217 EXPORT_C void CMidiClientUtility::PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity)

   218 	{

   219 	iBody->PlayNoteL(aChannel, aNote, aDuration, aNoteOnVelocity, aNoteOffVelocity);

   220 	}

   221 

   222 /**

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

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

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

   226 

   227 @param aChannel 

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

   229 @param aNote 

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

   231 @param aStartTime 

   232        specifies the time at which to start playing the note,

   233        relative to the MIDI resource playing time or the time elapsed since Play() was called if no resource is present

   234 @param aDuration

   235        Length of time to play note for.

   236 @param aNoteOnVelocity 

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

   238 @param aNoteOffVelocity

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

   240 */

   241 EXPORT_C void CMidiClientUtility::PlayNoteL(TInt aChannel,TInt aNote,const TTimeIntervalMicroSeconds& aStartTime,const TTimeIntervalMicroSeconds& aDuration,TInt aNoteOnVelocity,TInt aNoteOffVelocity)

   242 	{

   243 	iBody->PlayNoteL(aChannel, aNote, aStartTime, aDuration, aNoteOnVelocity, aNoteOffVelocity);

   244 	}

   245 

   246 /**

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

   248 by means of an All Notes Off MIDI message

   249 

   250 @param aChannel 

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

   252 */

   253 EXPORT_C void CMidiClientUtility::StopNotes(TInt aChannel)

   254 	{

   255 	iBody->StopNotes(aChannel);

   256 	}

   257 

   258 /**

   259 Synchronous function to commence playback of a note.

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

   261 

   262 @param aChannel 

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

   264 @param aNote 

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

   266 @param aVelocity 

   267        Velocity with which to start the note.

   268        The legal integer range is 0 <= aVelocity <= 127, but the value zero

   269        actually causes the message to be interpreted as a Note Off message

   270        instead of a Note On.

   271 */

   272 EXPORT_C void CMidiClientUtility::NoteOnL(TInt aChannel,TInt aNote,TInt aVelocity)

   273 	{

   274 	iBody->NoteOnL(aChannel, aNote, aVelocity);

   275 	}

   276 

   277 /**

   278 Synchronous function to terminate playback of a note. If no corresponding note

   279 is found then no error is raised.

   280 

   281 @param aChannel 

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

   283 @param aNote 

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

   285 @param aVelocity 

   286        Velocity with which to stop the note. 0 <= aVelocity <= 127. There is no 

   287 	   standard behaviour corresponding with note off velocity.

   288 */

   289 EXPORT_C void CMidiClientUtility::NoteOffL(TInt aChannel,TInt aNote,TInt aVelocity)

   290 	{

   291 	iBody->NoteOffL(aChannel, aNote, aVelocity);

   292 	}

   293 

   294 /**

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

   296 The playback rate is independent from tempo,

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

   298 

   299 @return Current playback rate in percent times 1000,

   300         i.e., 100000 means original playback speed, 200000 means double speed,

   301         and 50000 means half speed playback

   302 */

   303 EXPORT_C TInt CMidiClientUtility::PlaybackRateL() const

   304 	{

   305 	return iBody->PlaybackRateL();

   306 	}

   307 

   308 /**

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

   310 The playback rate is independent from tempo,

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

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

   313 

   314 @param aRate 

   315        Playback rate in percent times 1000,

   316        i.e., 100000 means original playback speed, 200000 means double speed,

   317        and 50000 means half speed playback

   318 */

   319 EXPORT_C void CMidiClientUtility::SetPlaybackRateL(TInt aRate)

   320 	{

   321 	iBody->SetPlaybackRateL(aRate);

   322 	}

   323 

   324 /**

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

   326 @see SetPlaybackRate() for milli-percentage details

   327 

   328 @return Maximum playback rate supported by MIDI player

   329 */

   330 EXPORT_C TInt CMidiClientUtility::MaxPlaybackRateL() const

   331 	{

   332 	return iBody->MaxPlaybackRateL();

   333 	}

   334 

   335 /**

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

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

   338 

   339 @return Minimum playback rate supported by MIDI player.

   340 */

   341 EXPORT_C TInt CMidiClientUtility::MinPlaybackRateL() const

   342 	{

   343 	return iBody->MinPlaybackRateL();

   344 	}

   345 

   346 /**

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

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

   349 

   350 @return Tempo at the current position of the currently open resource in microbeats per minute,

   351         i.e. BPM * 1000000. Filled in by the controller framework

   352 */

   353 EXPORT_C TInt CMidiClientUtility::TempoMicroBeatsPerMinuteL() const

   354 	{

   355 	return iBody->TempoMicroBeatsPerMinuteL();

   356 	}

   357 

   358 /**

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

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

   361 The tempo is independent from the playback rate,

   362 i.e., the resulting playback speed will be affected by both

   363 

   364 @param aMicroBeatsPerMinute 

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

   366 */

   367 EXPORT_C void CMidiClientUtility::SetTempoL(TInt aMicroBeatsPerMinute)

   368 	{

   369 	iBody->SetTempoL(aMicroBeatsPerMinute);

   370 	}

   371 

   372 /**

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

   374 

   375 @return Pitch shift in cents, i.e. semitones * 100. One octave equals 1200 cents

   376 */

   377 EXPORT_C TInt CMidiClientUtility::PitchTranspositionCentsL() const

   378 	{

   379 	return iBody->PitchTranspositionCentsL();

   380 	}

   381 

   382 /**

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

   384 May be called during playback

   385 aCents parameter is not checked - if the value is out of range, it is expected KErrArgument is return by MIDI engine.

   386 

   387 @param aCents 

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

   389 @return Actual pitch shift applied -

   390         may differ from the requested value due to limitations of the MIDI engine

   391 */

   392 EXPORT_C TInt CMidiClientUtility::SetPitchTranspositionL(TInt aCents)

   393 	{

   394 	return iBody->SetPitchTranspositionL(aCents);

   395 	}

   396 

   397 /**

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

   399 

   400 @return Duration in microseconds (seconds * 1000000).

   401 */

   402 EXPORT_C TTimeIntervalMicroSeconds CMidiClientUtility::DurationMicroSecondsL() const

   403 	{

   404 	return iBody->DurationMicroSecondsL();

   405 	}

   406 

   407 /**

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

   409 

   410 @return Duration in microbeats (beats * 1000000).

   411 */

   412 EXPORT_C TInt64 CMidiClientUtility::DurationMicroBeatsL() const

   413 	{

   414 	return iBody->DurationMicroBeatsL();

   415 	}

   416 

   417 /**

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

   419 

   420 @return Number of tracks

   421 */

   422 EXPORT_C TInt CMidiClientUtility::NumTracksL() const

   423 	{

   424 	return iBody->NumTracksL();

   425 	}

   426 

   427 /**

   428 Mutes or unmutes a particular track

   429 

   430 @param aTrack

   431        Index of the track to mute - 0 <= aTrack < NumTracksL().

   432 @param aMuted

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

   434 */

   435 EXPORT_C void CMidiClientUtility::SetTrackMuteL(TInt aTrack,TBool aMuted) const

   436 	{

   437 	iBody->SetTrackMuteL(aTrack, aMuted);

   438 	}

   439 

   440 

   441 /**

   442 Gets the MIME type of the MIDI resource currently open

   443 

   444 @return Descriptor containing the MIDI mime type

   445 */

   446 EXPORT_C const TDesC8& CMidiClientUtility::MimeTypeL()

   447 	{

   448 	return iBody->MimeTypeL();

   449 	}

   450 

   451 /**

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

   453 

   454 @return Microseconds relative to the start of the resource

   455 */

   456 EXPORT_C TTimeIntervalMicroSeconds CMidiClientUtility::PositionMicroSecondsL() const

   457 	{

   458 	return iBody->PositionMicroSecondsL();

   459 	}

   460 

   461 /**

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

   463 May be called whenever a MIDI resource is open

   464 

   465 @param aPosition

   466        Temporal position to move to. Clamped to (0, DurationMicroSecondsL()).

   467 */

   468 EXPORT_C void CMidiClientUtility::SetPositionMicroSecondsL(const TTimeIntervalMicroSeconds& aPosition)

   469 	{

   470 	iBody->SetPositionMicroSecondsL(aPosition);

   471 	}

   472 

   473 /**

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

   475 

   476 @return Microbeats (BPM*1000000) relative to the start of the resource

   477 */

   478 EXPORT_C TInt64 CMidiClientUtility::PositionMicroBeatsL() const

   479 	{

   480 	return iBody->PositionMicroBeatsL();

   481 	}

   482 

   483 /**

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

   485 May be called whenever a MIDI resource is open.

   486 

   487 @param aMicroBeats 

   488        Metrical position to move to. Clamped to (0, DurationMicroBeatsL()).

   489 */

   490 EXPORT_C void CMidiClientUtility::SetPositionMicroBeatsL(TInt64 aMicroBeats)

   491 	{

   492 	iBody->SetPositionMicroBeatsL(aMicroBeats);

   493 	}

   494 

   495 /**

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

   497 to allow other components to synchronise with playback of this MIDI resource

   498 

   499 @param aMicroSeconds 

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

   501 @param aMicroBeats 

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

   503 */

   504 EXPORT_C void CMidiClientUtility::SetSyncUpdateCallbackIntervalL(const TTimeIntervalMicroSeconds& aMicroSeconds,TInt64 aMicroBeats)

   505 	{

   506 	iBody->SetSyncUpdateCallbackIntervalL(aMicroSeconds, aMicroBeats);

   507 	}

   508 

   509 /**

   510 Sends a single MIDI message to the MIDI engine

   511 

   512 @param aMidiMessage 

   513        Descriptor containing the MIDI message data.

   514        If there are several MIDI messages in the buffer, only the first one is processed

   515 */

   516 EXPORT_C TInt CMidiClientUtility::SendMessageL(const TDesC8& aMidiMessage)

   517 	{

   518 	return iBody->SendMessageL(aMidiMessage);

   519 	}

   520 

   521 /**

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

   523 

   524 @param aMidiMessage 

   525        Descriptor containing the MIDI message data.

   526        If there are several MIDI messages in the buffer, only the first one is processed

   527 @param aTime 

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

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

   530 */

   531 EXPORT_C TInt CMidiClientUtility::SendMessageL(const TDesC8& aMidiMessage,const TTimeIntervalMicroSeconds& aTime)

   532 	{

   533 	return iBody->SendMessageL(aMidiMessage, aTime);

   534 	}

   535 

   536 /**

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

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

   539 

   540 @param aEntry 

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

   542 */

   543 EXPORT_C void CMidiClientUtility::SendMipMessageL(const RArray<TMipMessageEntry>& aEntry)

   544 	{

   545 	iBody->SendMipMessageL(aEntry);

   546 	}

   547 

   548 /**

   549 Gets the number of standard or custom sound banks currently available

   550 

   551 @param aCustom 

   552        Specifies whether to reference a custom or standard sound bank

   553 @return Number of custom or standard sound banks available

   554 */

   555 EXPORT_C TInt CMidiClientUtility::NumberOfBanksL(TBool aCustom) const

   556 	{

   557 	return iBody->NumberOfBanksL(aCustom);

   558 	}

   559 

   560 /**

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

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

   563 

   564 @param  aCustom 

   565         Specifies whether to reference a custom or standard sound bank

   566 @param  aBankIndex

   567         Index of sound bank where 0 <= aBankIndex < NumberOfBanksL(…)

   568 @return Identifier of the specified bank occupying, at most, 14 bits

   569 */

   570 EXPORT_C TInt CMidiClientUtility::GetBankIdL(TBool aCustom, TInt aBankIndex) const

   571 	{

   572 	return iBody->GetBankIdL(aCustom, aBankIndex);

   573 	}

   574 

   575 /**

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

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

   578 the banks are combined if the bank sets have colliding bank numbers

   579 

   580 @param aFileName 

   581        Name of the file containing the custom sound bank

   582 @param aBankCollectionIndex 

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

   584 */

   585 EXPORT_C void CMidiClientUtility::LoadCustomBankL(const TDesC& aFileName, TInt& aBankCollectionIndex)

   586 	{

   587 	iBody->LoadCustomBankL(aFileName, aBankCollectionIndex);

   588 	}

   589 

   590 /**

   591 Removes a custom sound bank from memory.

   592 Only valid for sound banks previously loaded from file.

   593 Once unloaded the custom sound bank is no longer available for use.

   594 

   595 @param aBankCollectionIndex 

   596        Identifier of the custom sound bank to unload,

   597        occupying no more than 14 bits

   598 */

   599 EXPORT_C void CMidiClientUtility::UnloadCustomBankL(TInt aBankCollectionIndex)

   600 	{

   601 	iBody->UnloadCustomBankL(aBankCollectionIndex);

   602 	}

   603 

   604 /**

   605 Query if a bank has been loaded to the memory

   606 

   607 @param aBankCollectionIndex 

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

   609 @return ETrue if the specified bank is in memory, EFalse otherwise

   610 */

   611 EXPORT_C TBool CMidiClientUtility::CustomBankLoadedL(TInt aBankCollectionIndex) const

   612 	{

   613 	return iBody->CustomBankLoadedL(aBankCollectionIndex);

   614 	}

   615 

   616 /**

   617 Removes all custom sound banks from memory.

   618 */

   619 EXPORT_C void CMidiClientUtility::UnloadAllCustomBanksL()

   620 	{

   621 	iBody->UnloadAllCustomBanksL();

   622 	}

   623 

   624 /**

   625 Gets the number of instruments available in a given sound bank

   626 

   627 @param aBankId 

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

   629 @param aCustom 

   630        Specifies whether to reference a custom or standard sound bank

   631 @return Count of the number of instruments available for the specified sound bank

   632 */

   633 EXPORT_C TInt CMidiClientUtility::NumberOfInstrumentsL(TInt aBankId,TBool aCustom) const

   634 	{

   635 	return iBody->NumberOfInstrumentsL(aBankId, aCustom);

   636 	}

   637 

   638 /**

   639 Gets the identifier of an instrument.

   640 

   641 @param aBankId 

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

   643 @param aCustom 

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

   645 @param aInstrumentIndex 

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

   647 @return Identifier of specified instrument.

   648         This may differ from the index since the index simply enumerates the instruments,

   649         whereas identifiers may not be contiguous, especially where certain instruments

   650         correspond to General MIDI-defined instruments but not all instruments are

   651         present. Instrument identifiers are between 0 and 127 inclusive.

   652 */

   653 EXPORT_C TInt CMidiClientUtility::GetInstrumentIdL(TInt aBankId,TBool aCustom,TInt aInstrumentIndex) const

   654 	{

   655 	return iBody->GetInstrumentIdL(aBankId, aCustom, aInstrumentIndex);

   656 	}

   657 

   658 /**

   659 Gets the name of the given instrument.

   660 

   661 @param  aBankId

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

   663 @param  aCustom

   664         Specifies whether to reference a custom or standard sound bank

   665 @param  aInstrumentId

   666         Identifier of the instrument under scrutiny. 0 <= iInstrumentId <= 127.

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

   668         If it has no name then an empty descriptor is returned

   669 */

   670 EXPORT_C HBufC* CMidiClientUtility::InstrumentNameL(TInt aBankId, TBool aCustom, TInt aInstrumentId) const

   671 	{

   672 	return iBody->InstrumentNameL(aBankId, aCustom, aInstrumentId);

   673 	}

   674 

   675 /**

   676 Sets a logical channel to use the given instrument.

   677 

   678 @param aChannel 

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

   680 @param aBankId 

   681        Identifier of the bank that the instrument belongs to,

   682        occupying no more than 14 bits.

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

   684 @param aInstrumentId 

   685        Identifier of the instrument under scrutiny. 0 <= iInstrumentId <= 127.

   686 */

   687 EXPORT_C void CMidiClientUtility::SetInstrumentL(TInt aChannel,TInt aBankId,TInt aInstrumentId)

   688 	{

   689 	iBody->SetInstrumentL(aChannel, aBankId, aInstrumentId);

   690 	}

   691 

   692 /**

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

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

   695 and instrument ids in memory

   696 

   697 @param aFileName 

   698        Name of the file containing the instrument

   699 @param aFileBankId 

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

   701        occupying no more than 14 bits

   702 @param aFileInstrumentId 

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

   704 @param aMemoryBankId 

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

   706        occupying no more than 14 bits.

   707 @param aMemoryInstrumentId 

   708        Identifier of the instrument in memory to load the new

   709        instrument into. 0 <= aInstrumentId <= 127.

   710 */

   711 EXPORT_C void CMidiClientUtility::LoadCustomInstrumentL(const TDesC& aFileName,TInt aFileBankId,TInt aFileInstrumentId,TInt aMemoryBankId,TInt aMemoryInstrumentId)

   712 	{

   713 	iBody->LoadCustomInstrumentL(aFileName, aFileBankId, aFileInstrumentId, aMemoryBankId, aMemoryInstrumentId);

   714 	}

   715 

   716 /**

   717 Removes an instrument from custom sound bank memory.

   718 Only valid for instruments previously loaded from file.

   719 Once unloaded the instrument is no longer available for use

   720 

   721 @param aCustomBankId 

   722        Identifier of the custom sound bank containing

   723        the instrument to unload, occupying no more than 14 bits.

   724 @param aInstrumentId 

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

   726 */

   727 EXPORT_C void CMidiClientUtility::UnloadCustomInstrumentL(TInt aCustomBankId,TInt aInstrumentId)

   728 	{

   729 	iBody->UnloadCustomInstrumentL(aCustomBankId, aInstrumentId);

   730 	}

   731 

   732 /**

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

   734 

   735 @param aNote 

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

   737 @param aBankId 

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

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

   740 @param aCustom 

   741        Specifies whether to reference a custom or standard sound bank

   742 @param aInstrumentId 

   743        Identifier of an instrument

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

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

   746 */

   747 EXPORT_C HBufC* CMidiClientUtility::PercussionKeyNameL(TInt aNote, TInt aBankId, TBool aCustom, TInt aInstrumentId) const

   748 	{

   749 	return iBody->PercussionKeyNameL(aNote, aBankId, aCustom, aInstrumentId);

   750 	}

   751 

   752 /**

   753 Get the stop time currently set for the MIDI resource

   754 

   755 @param aStopTime 

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

   757 */

   758 EXPORT_C void CMidiClientUtility::StopTimeL(TTimeIntervalMicroSeconds& aStopTime) const

   759 	{

   760 	iBody->StopTimeL(aStopTime);

   761 	}

   762 

   763 /**

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

   765 

   766 @param aStopTime 

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

   768        Clamped to 0 and the duration of the resource

   769 */

   770 EXPORT_C void CMidiClientUtility::SetStopTimeL(const TTimeIntervalMicroSeconds& aStopTime)

   771 	{

   772 	iBody->SetStopTimeL(aStopTime);

   773 	}

   774 

   775 /**

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

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

   778 

   779 @param aRepeatNumberOfTimes 

   780        Number of time to repeat the resource during playback.

   781        This includes the first playing

   782 @param aTrailingSilence 

   783        Time in microseconds to pause between repeats

   784 */

   785 EXPORT_C void CMidiClientUtility::SetRepeatsL(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds& aTrailingSilence)

   786 	{

   787 	iBody->SetRepeatsL(aRepeatNumberOfTimes, aTrailingSilence);

   788 	}

   789 

   790 /**

   791 Gets the number of currently active voices.

   792 

   793 @return The number of currently active voices

   794 */

   795 EXPORT_C TInt CMidiClientUtility::PolyphonyL() const

   796 	{

   797 	return iBody->PolyphonyL();

   798 	}

   799 

   800 /**

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

   802 

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

   804 */

   805 EXPORT_C TInt CMidiClientUtility::ChannelsSupportedL() const

   806 	{

   807 	return iBody->ChannelsSupportedL();

   808 	}

   809 

   810 /**

   811 Get the current volume setting of a logical channel

   812 

   813 @param aChannel 

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

   815 @return Volume currently set on the specified channel in decibels

   816 */

   817 EXPORT_C TReal32 CMidiClientUtility::ChannelVolumeL(TInt aChannel) const

   818 	{

   819 	return iBody->ChannelVolumeL(aChannel);

   820 	}

   821 

   822 /**

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

   824 

   825 @return Maximum volume setting. Minimum value is -infinity dB, which is the

   826        smallest possible value that TReal32 supports.

   827 */

   828 EXPORT_C TReal32 CMidiClientUtility::MaxChannelVolumeL() const

   829 	{

   830 	return iBody->MaxChannelVolumeL();

   831 	}

   832 

   833 /**

   834 Set the volume of a channel.

   835 

   836 @param aChannel 

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

   838 @param aVolume 

   839        Volume currently set on the specified channel in decibels. The minimum

   840        channel volume supported value is -infinity dB, which is the smallest

   841        possible value that TReal32 supports. 

   842 	   The maximum channel volume can be set via MaxChannelVolumeL()

   843 */

   844 EXPORT_C void CMidiClientUtility::SetChannelVolumeL(TInt aChannel,TReal32 aVolume)

   845 	{

   846 	iBody->SetChannelVolumeL(aChannel, aVolume);

   847 	}

   848 

   849 /**

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

   851 When unmuted the channel goes back to its previous volume setting

   852 

   853 @param aChannel 

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

   855 @param aMuted 

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

   857 */

   858 EXPORT_C void CMidiClientUtility::SetChannelMuteL(TInt aChannel,TBool aMuted)

   859 	{

   860 	iBody->SetChannelMuteL(aChannel, aMuted);

   861 	}

   862 

   863 /**

   864 Gets the overall volume of the MIDI client.

   865 

   866 @return The current overall volume setting

   867 */

   868 EXPORT_C TInt CMidiClientUtility::VolumeL() const

   869 	{

   870 	return iBody->VolumeL();

   871 	}

   872 

   873 /**

   874 Maximum volume setting that may be applied overall.

   875 

   876 @return Maximum volume setting. Minimum value is always zero which is silent

   877 */

   878 EXPORT_C TInt CMidiClientUtility::MaxVolumeL() const

   879 	{

   880 	return iBody->MaxVolumeL();

   881 	}

   882 

   883 /**

   884 Set the overall volume of the MIDI client.

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

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

   887 

   888 @param aVolume 

   889        Overall volume setting to use

   890 */

   891 EXPORT_C void CMidiClientUtility::SetVolumeL(TInt aVolume)

   892 	{

   893 	iBody->SetVolumeL(aVolume);

   894 	}

   895 

   896 /**

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

   898 when playback is started.

   899 

   900 @param aRampDuration 

   901        Duration of the ramping period.

   902 */

   903 EXPORT_C void CMidiClientUtility::SetVolumeRampL(const TTimeIntervalMicroSeconds& aRampDuration)

   904 	{

   905 	iBody->SetVolumeRampL(aRampDuration);

   906 	}

   907 

   908 /**

   909 Get the current stereo balance value

   910 

   911 @return Balance value ranging from KMMFBalanceMaxLeft to KMMFBalanceMaxRight

   912 */

   913 EXPORT_C TInt CMidiClientUtility::GetBalanceL() const

   914 	{

   915 	return iBody->GetBalanceL();

   916 	}

   917 

   918 /**

   919 Set the current stereo balance value

   920 

   921 @param aBalance 

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

   923 */

   924 EXPORT_C void CMidiClientUtility::SetBalanceL(TInt aBalance)

   925 	{

   926 	iBody->SetBalanceL(aBalance);

   927 	}

   928 

   929 /**

   930 Set the priority with which this client plays MIDI data

   931 

   932 @param  aPriority

   933         The Priority Value.

   934 @param  aPref

   935         The Priority Preference.

   936         

   937 @see CMidiClientUtility::NewL()

   938 */

   939 EXPORT_C void CMidiClientUtility::SetPriorityL(TInt aPriority, TInt aPref)

   940 	{

   941 	iBody->SetPriorityL(aPriority, aPref);

   942 	}

   943 

   944 /**

   945 Get the number of meta data entries currently known about in the currently open

   946 resource. XMF,SMF meta data are part of the XMF,SMF file header and can thus be examined

   947 before playback. If there is no XMF,SMF resource open, will return zero.

   948 Standard MIDI file meta data entries encountered during playback will be passed back

   949 via MMIDIClientUtilityObserver::MmcuoMetaDataEntryFound()

   950 

   951 @return Number of XMF meta data entries currently known about

   952 */

   953 EXPORT_C TInt CMidiClientUtility::NumberOfMetaDataEntriesL() const

   954 	{

   955 	return iBody->NumberOfMetaDataEntriesL();

   956 	}

   957 

   958 /**

   959 Retrieve the specified XMF,SMF meta data entry.

   960 

   961 @param aMetaDataIndex 

   962        Index of the meta data entry to retrieve

   963 @return Meta data entry. Ownership is passed to the client.

   964 */

   965 EXPORT_C CMMFMetaDataEntry* CMidiClientUtility::GetMetaDataEntryL(TInt aMetaDataIndex) const

   966 	{

   967 	return iBody->GetMetaDataEntryL(aMetaDataIndex);

   968 	}

   969 

   970 /**

   971 Synchronously pass implementation-specific commands to the MIDI engine

   972 and receive a response

   973 

   974 @param aDestination 

   975        Recipient of the message. Should be initialised with KUidInterfaceMIDI

   976        and a TInt describing the server-side object to which the command should be delivered.

   977        The TInt will usually be KMMFObjectHandleController, to deliver the message to the

   978        controller plugin, which is the default value.

   979 @param aFunction 

   980        Index of the function to perform

   981 @param aDataTo1 

   982        First command data buffer to send, eg command parameters

   983 @param aDataTo2 

   984        Second command data buffer to send, eg data parameters

   985 @param aDataFrom 

   986        Buffer to receive data in response to the command.

   987        The user must ensure that it is large enough to hold all the data returned.

   988 */

   989 EXPORT_C void CMidiClientUtility::CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom)

   990 	{

   991 	iBody->CustomCommandSyncL(aDestination, aFunction, aDataTo1, aDataTo2, aDataFrom);

   992 	}

   993 

   994 /**

   995 Synchronously pass implementation-specific commands to the MIDI engine.

   996 

   997 @param aDestination 

   998        Recipient of the message. Should be initialised with KUidInterfaceMIDI

   999        and a TInt describing the server-side object to which the command should be delivered.

  1000        The TInt will usually be KMMFObjectHandleController, to deliver the message to the

  1001        controller plugin, which is the default value.

  1002 @param aFunction 

  1003        Index of the function to perform

  1004 @param aDataTo1 

  1005        First command data buffer to send, eg command parameters

  1006 @param aDataTo2 

  1007        Second command data buffer to send, eg data parameters

  1008 */

  1009 EXPORT_C void CMidiClientUtility::CustomCommandSyncL(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2)

  1010 	{

  1011 	iBody->CustomCommandSyncL(aDestination, aFunction, aDataTo1, aDataTo2);

  1012 	}

  1013 

  1014 /**

  1015 Asynchronously pass implementation-specific commands to the MIDI engine

  1016 and receive a response

  1017 

  1018 @param aDestination 

  1019        aDestination Recipient of the message. Should be initialised with KUidInterfaceMIDI

  1020        and a TInt describing the server-side object to which the command should be delivered.

  1021        The TInt will usually be KMMFObjectHandleController, to deliver the message to the

  1022        controller plugin, which is the default value.

  1023 @param aFunction 

  1024        Index of the function to perform

  1025 @param aDataTo1 

  1026        First command data buffer to send, eg command parameters

  1027 @param aDataTo2 

  1028        Second command data buffer to send, eg data parameters

  1029 @param aDataFrom 

  1030        Buffer to receive data in response to the command.

  1031        The user must ensure that it is large enough to hold all the data returned.

  1032 @param aStatus

  1033        Status flag belonging to an active object that will have it's RunL() called

  1034        when this request complete

  1035 */

  1036 EXPORT_C void CMidiClientUtility::CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus)

  1037 	{

  1038 	iBody->CustomCommandAsync(aDestination, aFunction, aDataTo1, aDataTo2, aDataFrom, aStatus);

  1039 	}

  1040 

  1041 /**

  1042 Asynchronously pass implementation-specific commands to the MIDI engine

  1043 

  1044 @param aDestination 

  1045        aDestination Recipient of the message. Should be initialised with KUidInterfaceMIDI

  1046        and a TInt describing the server-side object to which the command should be delivered.

  1047        The TInt will usually be KMMFObjectHandleController, to deliver the message to the

  1048        controller plugin, which is the default value.

  1049 @param aFunction 

  1050        Index of the function to perform

  1051 @param aDataTo1 

  1052        First command data buffer to send, eg command parameters

  1053 @param aDataTo2 

  1054        Second command data buffer to send, eg data parameters

  1055 @param aStatus 

  1056        Status flag belonging to an active object that will have it's RunL() called

  1057        when this request complete

  1058 */

  1059 EXPORT_C void CMidiClientUtility::CustomCommandAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus)

  1060 	{

  1061 	iBody->CustomCommandAsync(aDestination, aFunction, aDataTo1, aDataTo2, aStatus);

  1062 	}

  1063 

  1064 /**

  1065 Gets a controller's DRM custom command implementation.

  1066 

  1067 @return A pointer to a controller's DRM custom command implementation or NULL

  1068 		if the interface can not be obtained

  1069 */

  1070 EXPORT_C MMMFDRMCustomCommand* CMidiClientUtility::GetDRMCustomCommand()

  1071 	{

  1072 	return iBody->GetDRMCustomCommand();

  1073 	}

  1074 

  1075 /**

  1076 Set the max polyphony the engine can handle

  1077 

  1078 @param aMaxNotes 

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

  1080 */

  1081 EXPORT_C void CMidiClientUtility::SetMaxPolyphonyL(TInt aMaxNotes)

  1082 	{

  1083 	iBody->SetMaxPolyphonyL(aMaxNotes);

  1084 	}

  1085 

  1086 /**

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

  1088 

  1089 @return The number of time the current opened resources has to be repeated

  1090 */

  1091 EXPORT_C TInt CMidiClientUtility::GetRepeats() const

  1092 	{

  1093 	return iBody->GetRepeats();

  1094 	}

  1095 

  1096 /**

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

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

  1099 the banks are combined if the bank sets have colliding bank numbers

  1100 

  1101 @param aBankData 

  1102        Descriptor containing the custom sound bank

  1103 @param aBankId 

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

  1105 */

  1106 EXPORT_C void CMidiClientUtility::LoadCustomBankDataL(const TDesC8& aBankData,TInt& aBankId)

  1107 	{

  1108 	iBody->LoadCustomBankDataL(aBankData, aBankId);

  1109 	}

  1110 

  1111 /**

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

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

  1114 and instrument ids in memory

  1115 

  1116 @param aInstrumentData 

  1117        Descriptor containing the instrument

  1118 @param aBankDataId 

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

  1120        occupying no more than 14 bits

  1121 @param aInstrumentDataId 

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

  1123 @param aMemoryBankId 

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

  1125        occupying no more than 14 bits

  1126 @param aMemoryInstrumentId 

  1127        Identifier of the instrument in memory to load the new

  1128        instrument into. 0 <= aInstrumentId <= 127.

  1129 */

  1130 EXPORT_C void CMidiClientUtility::LoadCustomInstrumentDataL(const TDesC8& aInstrumentData, TInt aBankDataId, TInt aInstrumentDataId, TInt aMemoryBankId, TInt aMemoryInstrumentId)

  1131 	{

  1132 	iBody->LoadCustomInstrumentDataL(aInstrumentData, aBankDataId, aInstrumentDataId, aMemoryBankId, aMemoryInstrumentId);

  1133 	}

  1134 

  1135 /**