#include <mmf/common/midistandardcustomcommands.h>
class RMidiControllerCustomCommands : public RMMFCustomCommandsBase |
Inherited Attributes | |
---|---|
RMMFCustomCommandsBase::iController | |
RMMFCustomCommandsBase::iDestinationPckg |
Inherited Functions | |
---|---|
RMMFCustomCommandsBase::RMMFCustomCommandsBase(RMMFController &,TUid) |
Client class to access functionality specific to a MIDI controller. The class uses the custom command function of the controller plugin, and removes the necessity for the client to formulate the custom commands.
IMPORT_C | RMidiControllerCustomCommands | ( | RMMFController & | aController | ) |
Constructor.
Parameter | Description |
---|---|
aController | The client side controller object to be used by this custom command interface. |
IMPORT_C TInt | CancelReceiveEvents | ( | ) |
Stop receiving events from the MIDI controller.
Returns: One of the system-wide error codes.
Get the current volume setting of a logical channel.
Parameter | Description |
---|---|
aChannel | Logical channel to query. 0 <= aChannel <= 15. |
aChannelVol | Volume currently set on the specified channel in decibels. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | Close | ( | ) |
Closes any currently open resources, such as files, descriptors or URLs in use. Does nothing if there is nothing currently open.
Returns: One of the system-wide error codes.
Query if a bank has been loaded to the memory.
Parameter | Description |
---|---|
aBankId | Identifier of the custom sound bank to check if it's in memory or not. |
aBankLoaded | ETrue if the specified bank is in memory, EFalse otherwise. |
Returns: One of the system-wide error codes.
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.
Parameter | Description |
---|---|
aCustom | Specifies whether to reference a custom or standard sound bank. |
aBankIndex | Index of sound bank where 0 <= aBankIndex < NumberOfBanks(). |
aBankId | Identifier of the specified bank occupying, at most, 14 bits. |
Returns: One of the system-wide error codes.
Gets the instrument assigned to a specified channel.
Parameter | Description |
---|---|
aChannel | Logical channel, 0 <= aChannel <= 15. |
aInstrumentId | Identifier of the instrument assigned to aChannel. 0 <= aInstrumentId <= 127. |
aBankId | Identifier of the bank that the instrument belongs to, occupying no more than 14 bits. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | GetInstrumentId | ( | TInt | aBankId, |
TBool | aCustom, | |||
TInt | aInstrumentIndex, | |||
TInt & | aInstrumentId | |||
) | const |
Gets the identifier of an instrument.
Parameter | Description |
---|---|
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 < NumberOfInstruments(). |
aInstrumentId | 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. |
Returns: One of the system-wide error codes.
Gets the name of the given instrument.
Parameter | Description |
---|---|
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 <= aInstrumentId <= 127. |
Returns: Buffer containing the name of the specified instrument. If it has no name then an empty descriptor is returned.
Loads one or more custom sound banks from a file into memory for use. If several banks are loaded with consequent LoadCustomBanks() function calls, the banks are combined if the bank sets have conflicting bank numbers.
Parameter | Description |
---|---|
aFileName | Name of the file containing the custom sound bank. |
aBankId | Identifier of the custom sound bank loaded, occupying no more than 14 bits. |
Returns: One of the system-wide error codes.
Loads one or more custom sound banks from a descriptor into memory for use. If several banks are loaded with consequent LoadCustomBanks() function calls, the banks are combined if the bank sets have conflicting bank numbers.
Parameter | Description |
---|---|
aBankData | Descriptor containing the custom sound bank. |
aBankId | Identifier of the custom sound bank loaded, occupying no more than 14 bits. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | LoadCustomInstrument | ( | 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 id given in the file can be mapped into different bank and instrument id in memory.
Parameter | Description |
---|---|
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. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | LoadCustomInstrumentData | ( | 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 id given in the descriptor can be mapped into different bank and instrument id in memory.
Parameter | Description |
---|---|
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. |
Returns: One of the system-wide error codes.
Gets the Maximum volume setting that may be applied to a logical channel.
Parameter | Description |
---|---|
aMaxVol | Maximum volume setting. Minimum value is -infinity dB, which is the smallest possible value that TReal32 supports. |
Returns: One of the system-wide error codes.
Gets the maximum playback rate in milli-percentage from the MIDI engine.
See also: SetPlaybackRate() for milli-percentage details.
Parameter | Description |
---|---|
aMaxRate | Playback rate supported by MIDI player. |
Returns: One of the system-wide error codes.
Gets the current maximum number of notes the engine can handle This can be greater than the value returned by RMidiControllerCustomCommands::Polyphony
Parameter | Description |
---|---|
aNumNotes | The maximum number of notes the engine can handle |
Returns: One of the system-wide error codes.
Gets the minimum playback rate in milli-percentage from the MIDI engine.
See also: SetPlaybackRate() for milli-percentage details.
Parameter | Description |
---|---|
aMinRate | Minimum playback rate supported by MIDI player. |
Returns: One of the system-wide error codes.
Synchronous function to terminate playback of a note. If no corresponding note is found then no error is raised.
Parameter | Description |
---|---|
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. |
Returns: One of the system-wide error codes.
Synchronous function to commence playback of a note. Multiple calls to this function will be accommodated as far as the MIDI engine can manage.
Parameter | Description |
---|---|
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. |
Returns: One of the system-wide error codes.
Gets the number of standard or custom sound banks currently available.
Parameter | Description |
---|---|
aCustom | Specifies whether to reference a custom or standard sound bank. |
aNumBanks | Number of custom or standard sound banks available. |
Returns: One of the system-wide error codes.
Gets the number of instruments available in a given sound bank.
Parameter | Description |
---|---|
aBankId | Identifier of sound bank to reference, occupying no more than 14 bits. |
aCustom | Specifies whether to reference a custom or standard sound bank. |
aNumInstruments | Count of the number of instruments available for the specified sound bank. |
Returns: One of the system-wide error codes.
Gets the name of a particular percussion key corresponding to a given note.
Parameter | Description |
---|---|
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. |
Returns: Descriptor containing the name of the percussion key. If the key does not have a name then an empty descriptor is returned.
IMPORT_C TInt | PlayNote | ( | 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.
Parameter | Description |
---|---|
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. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | PlayNote | ( | 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.
Parameter | Description |
---|---|
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. |
Returns: One of the system-wide error codes.
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.
Parameter | Description |
---|---|
aPlayBackRate | Current playback rate in percent times 1000, i.e., 100000 means original playback speed, 200000 means double speed, and 50000 means half speed playback. |
Returns: One of the system-wide error codes.
IMPORT_C void | ReceiveEvents | ( | TPckgBuf< TInt > & | aEventSize, |
TRequestStatus & | aStatus | |||
) |
Start receiving events from the controller. This can only be called once the controller is open.
Parameter | Description |
---|---|
aEventSize | The size of the MIDI event object. |
aStatus | Status flag belonging to an active object that will have it's RunL() called when this request complete. |
Sends a single MIDI message to the MIDI engine.
Parameter | Description |
---|---|
aMidiMessage | Descriptor containing the MIDI message data. If there are several MIDI messages in the buffer, only the first one is processed. |
aBytes | Number of bytes of the message buffer actually processed. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | SendMessage | ( | const TDesC8 & | aMidiMessage, |
const TTimeIntervalMicroSeconds & | aTime, | |||
TInt & | aBytes | |||
) |
Sends a single MIDI message, with time stamp, to the MIDI engine.
Parameter | Description |
---|---|
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. |
aBytes | Number of bytes of the message buffer actually processed. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | SendMipMessage | ( | 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.
Parameter | Description |
---|---|
aEntry | Array of logical {channel, MIP} value pairs to send, highest priority first. |
Returns: One of the system-wide error codes.
Set the muting state of a channel without changing its volume setting. When unmuted the channel goes back to its previous volume setting.
Parameter | Description |
---|---|
aChannel | Logical channel to set the mute state of. 0 <= aChannel <= 15. |
aMuted | ETrue to mute the channel, EFalse to unmute it. |
Returns: One of the system-wide error codes.
Set the volume of a channel.
Parameter | Description |
---|---|
aChannel | Logical channel to set the volume on. 0 <= aChannel <= 15. |
aVolume | The channel volume can be set within a range. The minimum channel volume is -infinity dB, which is the smallest possible value that TReal32 supports while the maximum channel volume is set via MaxVolumeL() which represents the volume level in dB corresponding to the MIDI Channel Volume controller. |
Returns: One of the system-wide error codes.
Sets a logical channel to use the given instrument.
Parameter | Description |
---|---|
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 <= aInstrumentId <= 127. |
Returns: One of the system-wide error codes.
Sets the pitch shift to apply to the currently open MIDI resource. May be called during playback.
Parameter | Description |
---|---|
aCents | Pitch shift in cents, i.e. semitones * 100. One octave equals 1200 cents. |
aCentsApplied | Actual pitch shift applied - may differ from the requested value due to limitations of the MIDI engine. |
Returns: One of the system-wide error codes.
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.
Parameter | Description |
---|---|
aPlayBackRate | Playback rate in percent times 1000, i.e., 100000 means original playback speed, 200000 means double speed, and 50000 means half speed playback. |
Returns: One of the system-wide error codes.
Change the position of the currently playing MIDI resource to the given position. May be called whenever a MIDI resource is open.
Parameter | Description |
---|---|
aMicroBeats | Metrical position to move to. Clamped to (0, DurationMicroBeats()). |
Returns: One of the system-wide error codes.
IMPORT_C TInt | SetRepeats | ( | 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.
Parameter | Description |
---|---|
aRepeatNumberOfTimes | Number of times to repeat the resource during playback. This includes the first playing. |
aTrailingSilence | Time in microseconds to pause between repeats. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | SetStopTime | ( | const TTimeIntervalMicroSeconds & | aStopTime | ) | const |
Sets the stop time to use for the currently open MIDI resource
Parameter | Description |
---|---|
aStopTime | Time at which playback will stop, relative to the start of the resource. Clamped to 0 and the duration of the resource. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | SetSyncUpdateCallbackInterval | ( | 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.
Parameter | Description |
---|---|
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. |
Returns: One of the system-wide error codes.
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.
Parameter | Description |
---|---|
aMicroBeatsPerMinute | Tempo in microbeats per minute (BPM*1000000) to set. |
Returns: One of the system-wide error codes.
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).
Parameter | Description |
---|---|
aVolume | Overall volume setting to use. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | SetVolumeRamp | ( | const TTimeIntervalMicroSeconds & | aRampDuration | ) |
Length of time over which the volume is faded up from zero to the current setting when playback is started.
Parameter | Description |
---|---|
aRampDuration | Duration of the ramping period. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | 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.
Parameter | Description |
---|---|
aFadeOutDuration | Length of time over which the volume is faded out from the current setting to zero. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | StopTime | ( | TTimeIntervalMicroSeconds & | aStopTime | ) | const |
Get the stop time currently set for the MIDI resource.
Parameter | Description |
---|---|
aStopTime | Time at which playback will stop, relative to the start of the resource. |
Returns: One of the system-wide error codes.
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.
Parameter | Description |
---|---|
aMicroBeatsPerMinute | Tempo at the current position of the currently open resource in microbeats per minute, i.e. BPM * 1000000. Filled in by the controller framework. |
Returns: One of the system-wide error codes.
IMPORT_C TInt | UnloadAllCustomBanks | ( | ) |
Removes all custom sound banks from memory.
Returns: One of the system-wide error codes.
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.
Parameter | Description |
---|---|
aBankId | Identifier of the custom sound bank to unload,occupying no more than 14 bits. |
Returns: One of the system-wide error codes.
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.
Parameter | Description |
---|---|
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. |
Returns: One of the system-wide error codes.