epoc32/include/mmf/common/mmfmidi.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 // Mmf\Common\MmfMidi.h
    15 // 
    16 //
    17 
    18 #ifndef __MMF_COMMON_MMFMIDI_H__
    19 #define __MMF_COMMON_MMFMIDI_H__
    20 
    21 // Standard EPOC32 includes
    22 #include <e32base.h>
    23 
    24 // Public Media Server includes
    25 #include <mmf/common/mmfbase.h>
    26 #include <mmf/common/mmfutilities.h>
    27 
    28 #include <midiclientutility.h>
    29 
    30 /**
    31 MIDI event usued by a MIDI controller to signal to a 
    32 client that a MIDI source open request has completed.
    33 
    34 @publishedAll
    35 @released
    36 */
    37 const TUid KMMFEventCategoryMidiOpenDataSourceComplete = {0x101F8F85};
    38 
    39 /**
    40 MIDI event used by a MIDI controller to signal to a 
    41 client that play of a MIDI resource has commenced.
    42 
    43 @publishedAll
    44 @released
    45 */
    46 const TUid KMMFEventCategoryMidiPlaying = {0x101F8F86};
    47 
    48 /**
    49 MIDI event used by a MIDI controller to signal to 
    50 a client that play of a MIDI resource has commenced 
    51 but not all SP-MIDI requirements can be met.
    52 
    53 @publishedAll
    54 @released
    55 */
    56 const TUid KMMFEventCategoryMidiPlaybackIncompatible = {0x101F8F87};
    57 
    58 /**
    59 MIDI event used by a MIDI controller to signal to a client that play
    60 of a MIDI resource has commenced but due to system resource constraints
    61 and SP-MIDI content constraints, there is no audible MIDI content
    62 during playback.
    63 
    64 @publishedAll
    65 @released
    66 */
    67 const TUid KMMFEventCategoryMidiPlaybackSilent = {0x101F8F88};
    68 
    69 /**
    70 MIDI event used by a MIDI controller to signal to
    71 a client that play of a MIDI resource has completed.
    72 
    73 @publishedAll
    74 @released
    75 */
    76 const TUid KMMFEventCategoryMidiPlayingComplete = {0x101F8F89};
    77 
    78 /**
    79 MIDI event used by a MIDI controller to signal to
    80 a client a sync update event. The frequency of this event is
    81 set by the client with SetSyncUpdateCallbackIntervalL.
    82 
    83 @publishedAll
    84 @released
    85 */
    86 const TUid KMMFEventCategoryMidiSyncUpdate = {0x101F8F8A};
    87 
    88 /**
    89 MIDI event used by a MIDI controller to signal to
    90 a client that any currently opened resources have been closed.
    91 
    92 @publishedAll
    93 @released
    94 */
    95 const TUid KMMFEventCategoryMidiClose = {0x101F8F8B};
    96 
    97 /**
    98 MIDI event used by a MIDI controller to signal to a client that the 
    99 MIDI controller has been primed and it's ready to play.
   100 
   101 @publishedAll
   102 @released
   103 */
   104 const TUid KMMFEventCategoryMidiPrime = {0x101F8F8C};
   105 
   106 /**
   107 MIDI event used by a MIDI controller to signal to a client that the MIDI
   108 resource has encountered a tempo change message in the MIDI data stream.
   109 
   110 @publishedAll
   111 @released
   112 */
   113 const TUid KMMFEventCategoryTempoChanged = {0x101F8F8D};
   114 
   115 /**
   116 MIDI event used by a MIDI controller to signal to a client that the MIDI
   117 resource has encountered a volume change message in the MIDI data stream.
   118 
   119 @publishedAll
   120 @released
   121 */
   122 const TUid KMMFEventCategoryVolumeChanged = {0x101F8F8E};
   123 
   124 /**
   125 MIDI event used by a MIDI controller to signal to a client that the 
   126 MIDI resource has encountered a mute message in the MIDI data stream.
   127 
   128 @publishedAll
   129 @released
   130 */
   131 const TUid KMMFEventCategoryMuteChanged = {0x101F8F8F};
   132 
   133 /**
   134 MIDI event used by a MIDI controller to signal to a client that the polyphony
   135 of the MIDI engine has changed.
   136 
   137 @publishedAll
   138 @released
   139 */
   140 const TUid KMMFEventCategoryPolyphonyChanged = {0x101F8F90};
   141 
   142 /**
   143 MIDI event used by a MIDI controller to signal to a client that
   144 an instrument has been changed on a channel.
   145 
   146 @publishedAll
   147 @released
   148 */
   149 const TUid KMMFEventCategoryInstrumentChanged = {0x101F8F91};
   150 
   151 /**
   152 MIDI event used by a MIDI controller to signal to a client that a timed
   153 meta data entry has been found in the MIDI data stream.
   154 
   155 @publishedAll
   156 @released
   157 */
   158 const TUid KMMFEventCategoryMetaDataEntryFound  = {0x101F8F92};
   159 
   160 /**
   161 MIDI event used by a MIDI controller to signal to a client that a 
   162 MIP message has been found in the MIDI data stream.
   163 
   164 @publishedAll
   165 @released
   166 */
   167 const TUid KMMFEventCategoryMipMessageReceived  = {0x101F8F93};
   168 
   169 /**
   170 @internalComponent
   171 */
   172 class TMMFMidiConfig1
   173 	{
   174 public:
   175 	inline TMMFMidiConfig1();
   176 public:
   177 	/** 
   178 	 * Number of tracks present in the currently open MIDI resource.
   179 	 */
   180 	TInt iNumTracks;
   181 
   182 	/** 
   183 	 * Current state of the MIDI client utility object 
   184 	 * (EMidiStateClosedDisengaged,EMidiStateOpenDisengaged,EMidiStateOpenPlaying,EMidiStatePlaybackIncompatible,
   185 	 *  EMidiStatePlaybackSilent, EMidiStateClosedEngaged, EMidiStateOpenEngaged).
   186 	 */
   187 	 
   188 	TInt iState;
   189 
   190 	/** 
   191 	 * Tempo in microbeats per minute (BPM*1000000).
   192 	 */
   193 	TInt iTempo;
   194 
   195 	/** 
   196 	 * Pitch shift in cents, i.e. semitones * 100. One octave equals 1200 cents.
   197 	 */
   198 	TInt iPitch;
   199 
   200 	/** 
   201 	 * Array of logical {channel, MIP} value pairs to send SP-MIDI MIP message to the MIDI engine.
   202 	 */
   203 	const TArray<TMipMessageEntry>* iMipMessage; 
   204 
   205 	/** 
   206 	 * The maximum number of notes that the MIDI engine supports simultaneously (polyphony).
   207 	 */
   208 	TInt iNumNotes; 
   209 
   210 	/** 
   211 	 * Max polyphony level: 0 <= PolyphonyL() <= iMaxNotes.
   212 	 */
   213 	TInt iMaxNotes;
   214 
   215 	/** 
   216 	 * Overall volume of the MIDI client.
   217 	 */
   218 	TInt iVolume;
   219 
   220 	/** 
   221 	 * Maximum volume that may be applied overall to the MIDI client.
   222 	 */
   223 	TInt iMaxVolume;
   224 
   225 	/** 
   226 	 * Length of time over which the volume is faded up from zero to the current settings when playback is started.
   227 	 */
   228 	TTimeIntervalMicroSeconds iRampDuration;
   229 
   230 	/** 
   231 	 * Stereo balance value: KMMFBalanceMaxLeft <= iBalance <= KMMFBalanceMaxRight.
   232 	 */
   233 	TInt iBalance;
   234 
   235 	/** 
   236 	 * The number of times the current opened resources has to be repeated.
   237 	 * This includes the first instance of playing.
   238 	 */
   239 	TInt iNumRepeats;
   240 
   241 	/** 
   242 	 * Length of time over which the volume is faded out from the current settings to zero.
   243 	 */
   244 	TTimeIntervalMicroSeconds iFadeOutDuration;
   245 	};
   246 
   247 /**
   248 @internalComponent
   249 */
   250 class TMMFMidiConfig2
   251 	{
   252 public:
   253 	inline TMMFMidiConfig2();
   254 public:
   255 	/** 
   256 	 * Index of the track to mute: 0 <= iTrack < NumTracksL().
   257 	 */
   258 	TInt iTrack;
   259 
   260 	/** 
   261 	 * ETrue to mute the track/channel, EFalse to unmute it.
   262 	 */
   263 	TBool iMuted;
   264 
   265 	/** 
   266 	 * Note to play ot to terminate: 0 <= iNote <= 127.
   267 	 */
   268 	TInt iNote;
   269 
   270 	/** 
   271 	 * Length of time to play the note for.
   272 	 */
   273 	TTimeIntervalMicroSeconds iDurationMicroSeconds;
   274 
   275 	/** 
   276 	 * Specifying the time at which to start playing the note.
   277 	 * It's relative to the MIDI resource playing time or the time elapsed
   278 	 * since Play() was called if no resource is present.
   279 	 */
   280 	TTimeIntervalMicroSeconds iStartTime;
   281 
   282 	/** 
   283 	 * Velocity with which to start the note: 0 <= iNoteOnVelocity <= 127.
   284 	 */
   285 	TInt iNoteOnVelocity;
   286 
   287 	/** 
   288 	 * Velocity with which to stop the note: 0 <= iNoteOffVelocity <= 127.
   289 	 */
   290 	TInt iNoteOffVelocity;
   291 
   292 	/** 
   293 	 * Number of standard or custom sound banks currently available.
   294 	 */
   295 	TInt iNumBanks;
   296 
   297 	/** 
   298 	 * Specifies whether to reference a custom or standard sound bank.
   299 	 */
   300 	TBool iCustom;
   301 
   302 	/** 
   303 	 * Index of custom/deault bank: 0 <= iBankIndex < NumberOfBanksL()
   304 	 */
   305 	TInt iBankIndex;
   306 
   307 	/** 
   308 	 * Custom/deault Bank's Identifier.
   309 	 */
   310 	TInt iBankId;
   311 
   312 	/** 
   313 	 * Identifier of the custom bank in memory.
   314 	 */
   315 	TInt iMemoryBankId;
   316 
   317 	/** 
   318 	 * Name of the file containing the custom sound bank or the name 
   319 	 * of the file containing the instrument. Includes the directory path. 
   320 	 */
   321 	const TDesC* iFileName;
   322 
   323 	/** 
   324 	 * Descriptor containing the custom sound bank.
   325 	 */
   326 	const TDesC8* iBankData;
   327 
   328 	/** 
   329 	 * Descriptor containing the instrument.
   330 	 */
   331 	const TDesC8* iInstrumentData;
   332 
   333 	/** 
   334 	 * ETrue if the specified bank is in memory, EFalse otherwise.
   335 	 */
   336 	TBool iBankLoaded;
   337 
   338 	/** 
   339 	 * Number of instruments available for the specified sound bank.
   340 	 */
   341 	TInt iNumInstruments;
   342 
   343 	/** 
   344 	 * Index of the instrument to reference: 0 <= aInstrumentIndex < NumberOfInstrumentsL().
   345 	 */
   346 	TInt iInstrumentIndex;
   347 
   348 	/** 
   349 	 * Identifier of specified instrument. This may differ from the index 
   350 	 * since the index simply enumerates the instruments, whereas identifiers 
   351 	 * may not be contiguous, especially where certain instruments correspond 
   352 	 * to General MIDI-defined instruments but not all instruments are present.
   353 	 * 0 <= iInstrumentId <= 127.
   354 	 */
   355 	TInt iInstrumentId;
   356 
   357 	/** 
   358 	 * Identifier of the instrument in memory.
   359 	 */
   360 	TInt iMemoryInstrumentId;
   361 
   362 	/** 
   363 	 * Current metrical position of the MIDI resource being played.
   364 	 * Microbeats (BPM*1000000) relative to the start of the resource.
   365 	 */
   366 	TInt64 iPositionMicroBeats;
   367 
   368 	/** 
   369 	 * Length of the currently open MIDI resource.
   370 	 * Duration in microbeats (beats * 1000000).
   371 	 */
   372 	TInt64 iDurationMicroBeats;
   373 
   374 	/** 
   375 	 * Time at which playback will stop, relative to the start of the resource.
   376 	 * Clamped to 0 and the duration of the resource.
   377 	 */
   378 	TTimeIntervalMicroSeconds iStopTime;
   379 
   380 	/** 
   381 	 * Logical channel: 0 <= iChannel < ChannelsSupportedL().
   382 	 */
   383 	TInt iChannel;
   384 
   385 	/** 
   386 	 * Volume level in dB corresponding to the MIDI Channel:
   387 	 * -infinity <= iChannelVol <= MaxVolumeL().
   388 	 */
   389 	TReal32 iChannelVol;
   390 
   391 	/** 
   392 	 * Maximum volume setting in dB, should always be 0 dB and 
   393 	 * correspond to the MIDI Channel Volume controller maximum value.
   394 	 */
   395 	TReal32 iMaxChannelVol;
   396 	};
   397 
   398 /**
   399 @internalComponent
   400 */
   401 class TMMFMidiConfig3
   402 	{
   403 public:
   404 	inline TMMFMidiConfig3();
   405 public:
   406 	/** 
   407 	 * Temporal interval between MmcuoSyncUpdate callback.
   408 	 */
   409 	TTimeIntervalMicroSeconds iCallbackIntervalMicroSeconds;
   410 
   411 	/** 
   412 	 * Metrical interval between MmcuoSyncUpdate callback.
   413 	 */
   414 	TInt64 iCallbackIntervalMicroBeats;
   415 
   416 	/** 
   417 	 * Number of bytes of the MIDI message buffer actually processed when client
   418 	 * calls SendMessageL.
   419 	 */
   420 	TInt iBytesProcessed;
   421 
   422 	/** 
   423 	 * Time at which to execute the MIDI message sent by SendMessageL.
   424 	 * It's relative to the MIDI resource playing time or the time elapsed 
   425 	 * since Play() was called if no resource is present.
   426 	 */
   427 	TTimeIntervalMicroSeconds iTimeStamp;
   428 
   429 	/** 
   430 	 * Number of time to repeat the resource during playback. This includes the first playing.
   431 	 */
   432 	TInt iRepeatNumberOfTimes;
   433 
   434 	/** 
   435 	 * Time in microseconds to pause between repeats.
   436 	 */
   437 	TTimeIntervalMicroSeconds iTrailingSilence;
   438 
   439 	/** 
   440 	 * Playback rate for the playback of the current MIDI resource
   441 	 * in percent times 1000, i.e., 100000 means original playback speed,
   442 	 * 200000 means double speed, and 50000 means half speed playback.
   443 	 */
   444 	TInt iPlayBackRate;
   445 
   446 	/** 
   447 	 * Maximum playback rate supported by MIDI player.
   448 	 */
   449 	TInt iPlayBackMaxRate;
   450 
   451 	/** 
   452 	 * Minimum playback rate supported by MIDI player.
   453 	 */
   454 	TInt iPlayBackMinRate;
   455 
   456 	/** 
   457 	 * Descriptor containing a MIDI message data. If there
   458 	 * are several MIDI messages in the buffer, only the first
   459 	 * one is processed.
   460 	 */
   461 	const TDesC8* iMidiMessage;
   462 	};
   463 
   464 inline TMMFMidiConfig1::TMMFMidiConfig1()
   465 {};
   466 
   467 inline TMMFMidiConfig2::TMMFMidiConfig2()
   468 {};
   469 
   470 inline TMMFMidiConfig3::TMMFMidiConfig3()
   471 {};
   472 
   473 #endif