COutputport


Purpose:
Handles all output midi ports and performs DLS load and unload.
Remark: The returns values are based on the DirectX9 constants except DM_FAILED
The functions raise a CDMusicException exception type with the error data.
Member functions:



Function:
Initialize
Declaration: void COutputPort::Initialize(CDirectMusic &pDMusic)
Purpose:
Initializes the output port object
Parameters: 

Returns:   

S_OK

Succeeds

Throws:    

DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetNumPorts
Declaration: DWORD COutputPort::GetNumPorts()
Purpose:
Returns the number of output midi ports in the system
Parameters:  none

Returns:

Number of ports

Number of ouput midi ports, if 0 is returned, no ouput ports present

Throws:    

E_INVALIDARG Invalid argument
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_NOINTERFACE No object interface is available
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetPortInfo
Declaration: HRESULT COutputPort::GetPortInfo(DWORD dwNumPort,LPINFOPORT lpInfoPort)
Purpose:
Gets the port info structure of a given number of midi port
Parameters:      

Returns:  

S_FALSE There is no port with that index value
S_OK

Succeeds

Throws:    

DM_FAILED Error, see DirectMidi causes
E_INVALIDARG Invalid argument
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_NOINTERFACE No object interface is available

Top    Index

Function: GetActivatedPortInfo
Declaration: HRESULT COuputPort::GetActivatedPortInfo(LPINFOPORT lpInfoPort)
Purpose:
Gets the port info structure of the current activated midi port
Parameters:    

Returns:  

S_OK

Succeeds

Throws:

DM_FAILED Error, see DirectMidi causes
E_INVALIDARG Invalid argument
E_POINTER An invalid pointer, usually NULL, was passed as a parameter

Top    Index

Function: ActivatePort
Declaration: HRESULT COutputPort::ActivatePort(LPINFOPORT InfoPort,DWORD dwSysExSize)
Purpose:
Activate the output midi port providing a pointer to an INFOPORT structure with the port identification.
Allocate the buffer memory for outgoing system exclusive data
Parameters:      

Returns:  

S_OK

Succeeds

Throws:

S_FALSE Error
DSERR_NODRIVER No sound driver is available for use, or the given GUID is not a valid DirectSound device ID
E_NOINTERFACE No object interface is available
DM_FAILED Error, see DirectMidi causes
E_INVALIDARG Invalid argument
DMUS_E_DSOUND_NOT_SET The port could not be created because no DirectSound object has been specified
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY Insufficient memory to complete the task

Top    Index

Function: ActivatePortFromInterface
Declaration: HRESULT COuputtPort::ActivatePortFromInterface(IDirectMusicPort8* pPort,DWORD dwSysExSize)
Purpose:
Activate the output midi port providing a pointer to an IDirectMusicPort8 interface pointer.
Allocate the buffer memory for outgoing system exclusive events.
Parameters:      

Remarks:

    The external IDirectMusicPort8 interface pointer doesn't have to be explicitly released

Returns:  

S_OK

Succeeds

Throws:

S_FALSE Error
DSERR_NODRIVER No sound driver is available for use, or the given GUID is not a valid DirectSound device ID
E_NOINTERFACE No object interface is available
DM_FAILED Error, see DirectMidi causes
E_INVALIDARG Invalid argument
DMUS_E_DSOUND_NOT_SET The port could not be created because no DirectSound object has been specified
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY Insufficient memory to complete the task

Top    Index

Function: ReleasePort
Declaration: HRESULT COutputPort::ReleasePort()
Purpose:
Releases the DirectMidi internal COM interfaces for a new port selection, this method is also called by the destructor
Parameters:     none
Remarks: Call this member function to deactivate the selected output midi port in run-time

Returns:  

S_OK

Succeeds

DM_FAILED Error, see DirectMidi causes

Throws:

DSERR_NODRIVER No sound driver is available for use, or the given GUID is not a valid DirectSound device ID

Top    Index

Function: KsProperty
Declaration: HRESULT COutputPort::KsProperty(GUID Set,ULONG Id,ULONG Flags,LPVOID pvPropertyData,ULONG ulDataLength,PULONG pulBytesReturned)

Purpose:
The KsProperty method retrieves or sets the value of a property for the midi port
Parameters:    

Set [in]:Identifier of the property set. The following property-set GUIDs are predefined by DirectMusic: See table
Id  [in]: Item within the property set
Flags [in]: One of the following flags to specify the operation: See table
pvPropertyData [in/out]: For a set operation, the address of a memory buffer containing data that represents the new value of the property. For a get operation, the address of a memory buffer big enough to hold the value of the property. For a basic support query, the address of a buffer at least a DWORD in size
ulDataLength [in]: Length of the buffer pointed to by pvPropertyData
pulBytesReturned [out]: On a KSPROPERTY_TYPE_GET or KSPROPERTY_TYPE_BASICSUPPORT call, address of a variable that receives the number of bytes returned in pvPropertyData by the port    

                                                     
Example:
The following example code demonstrates the use of this property by setting a new latency for the synthesizer in milliseconds.                       

COutputPort.KsProperty(GUID_DMUS_PROP_WriteLatency,0,KSPROPERTY_TYPE_SET,(LPVOID)&dwLatency,sizeof(dwLatency),&ulDummy);      

Returns:  

S_OK

Succeeds

DMUS_E_UNKNOWN_PROPERTY The property set or item is not implemented by this port

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY Insufficient memory to complete the task
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL The method did not succeed
DM_FAILED Error, see DirectMidi causes 

Top    Index

Function: SetBuffer
Declaration: HRESULT COutputPort::SetBuffer(DWORD dwBufferSize)
Purpose:
Sets internal buffer for storing outgoing MIDI messages 
Parameters:     

Returns:  

S_OK

Succeeds

Throws:

E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY Insufficient memory to complete the task
E_NOINTERFACE No object interface is available
DM_FAILED

Error, see DirectMidi causes

Function: RemoveBuffer
Declaration: HRESULT COutputPort::RemoveBuffer()
Purpose:
Removes the internal buffer  
Returns:  

S_FALSE Error
S_OK

Succeeds

Function: SetPortParams
Declaration: HRESULT COutputPort::SetPortParams(DWORD dwVoices,DWORD dwAudioChannels,DWORD dwChannelGroups,DWORD dwEffectFlags,DWORD dwSampleRate)
Purpose:
Sets the port synthesis parameters 
Parameters:      

dwVoices [in]:  Number of voices required on this port. This is not an absolute maximum; the port can create additional temporary voices to enable smooth transitions when lower-priority voices have to be dropped
dwAudioChannels [in]: Desired number of output channels
dwChannelGroups [in]: Number of channel groups to be allocated on this port
dwEffectFlags [in]:
Flags indicating which special effects are wanted. The following values are defined:
Flag Description
DMUS_EFFECT_NONE No effects are wanted
DMUS_EFFECT_REVERB Reverb is wanted
DMUS_EFFECT_CHORUS Chorus is wanted
DMUS_EFFECT_DELAY Delay is wanted

Or one of the followings defined in CDirectMidi.h: Synthesizer Effects
dwSampleRate [in]: Desired sample rate, in hertz

Returns:  None

Throws: None

Top    Index

Function: SetNumChannelGroups
Declaration: HRESULT COutputPort::SetNumChannelGroups(DWORD dwChannelGroups)
Purpose:
This method changes the number of channel groups that the application needs on the port
Parameters:   


Returns:  

S_OK

Succeeds

Throws:

E_OUTOFMEMORY Insufficient memory to complete the task
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL The method did not succeed
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetNumChannelGroups
Declaration: HRESULT COutputPort::GetNumChannelGroups(LPDWORD pdwChannelGroups)
Purpose:
This method retrieves the number of channel groups on the port
Parameters:  


Returns:  

S_OK

Succeeds

Throws:

E_OUTOFMEMORY Insufficient memory to complete the task
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL The method did not succeed
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: SetChannelPriority
Declaration:
HRESULT COutputPort::SetChannelPriority(DWORD dwChannelGroup,DWORD dwChannel,DWORD dwPriority)
Purpose: This method sets the priority of a MIDI channel
Parameters:  


Returns:  

S_OK

Succeeds

Throws:

E_OUTOFMEMORY Insufficient memory to complete the task
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL The method did not succeed
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetChannelPriority
Declaration:
HRESULT COutputPort::GetChannelPriority(DWORD dwChannelGroup,DWORD dwChannel,LPDWORD pdwPriority)
Purpose: This method retrieves the priority of a MIDI channel
Parameters:  

Remarks: 

The following values, defined in Dmusicc.h, each represent a range of priorities. They are listed here in descending order of priority.

Value
DAUD_CRITICAL_VOICE_PRIORITY
DAUD_HIGH_VOICE_PRIORITY
DAUD_STANDARD_VOICE_PRIORITY
DAUD_LOW_VOICE_PRIORITY
DAUD_PERSIST_VOICE_PRIORITY

The following values express the default ranking of the channels within a range, according to the DLS standard. They are listed here in descending order. Channel 10, the percussion channel, has the highest priority
Value
DAUD_CHAN10_VOICE_PRIORITY_OFFSET
DAUD_CHAN1_VOICE_PRIORITY_OFFSET
DAUD_CHAN2_VOICE_PRIORITY_OFFSET
DAUD_CHAN3_VOICE_PRIORITY_OFFSET
DAUD_CHAN4_VOICE_PRIORITY_OFFSET
DAUD_CHAN5_VOICE_PRIORITY_OFFSET
DAUD_CHAN6_VOICE_PRIORITY_OFFSET
DAUD_CHAN7_VOICE_PRIORITY_OFFSET
DAUD_CHAN8_VOICE_PRIORITY_OFFSET
DAUD_CHAN9_VOICE_PRIORITY_OFFSET
DAUD_CHAN11_VOICE_PRIORITY_OFFSET
DAUD_CHAN12_VOICE_PRIORITY_OFFSET
DAUD_CHAN13_VOICE_PRIORITY_OFFSET
DAUD_CHAN14_VOICE_PRIORITY_OFFSET
DAUD_CHAN15_VOICE_PRIORITY_OFFSET
DAUD_CHAN16_VOICE_PRIORITY_OFFSET

The priority of a channel is represented by a range plus an offset. For example, DAUD_HIGH_VOICE_PRIORITY combined with DAUD_CHAN10_VOICE_PRIORITY_OFFSET represents the highest priority within the high range. Combined range and offset values for the standard range are defined for convenience in Dmusicc.h as DAUD_CHAN1_DEF_VOICE_PRIORITY, .DAUD_CHAN2_DEF_VOICE_PRIORITY, and so on.

Channels that have the same priority value have equal priority, regardless of which channel group they belong to

Returns:  

S_OK

Succeeds

Throws:

DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetSynthStats
Declaration:
HRESULT COutputPort::GetSynthStats(LPSYNTHSTATS SynthStats)
Purpose: This method retrieves information about the state of the synthesizer
Parameters: SynthStats [out]: A pointer to a SYNTHSTATS structure
Returns:  

S_OK

Succeeds

Throws:

E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: GetReferenceClock
Declaration: IReferenceClock* COutputPort::GetReferenceClock()
Purpose:
Returns a pointer to the internal IReferenceClock interface
Parameters: 
 none

Returns:

IReferenceClock Pointer to the IReferenceClock interface

Top    Index

Function: GetFormat
Declaration:
HRESULT COutputPort::GetFormat(LPWAVEFORMATEX pWaveFormatEx,LPDWORD pdwWaveFormatExSize,LPDWORD pdwBufferSize)
Purpose: Retrieves information about the WAV format specified in the COutputPort::SetPortParams structure, and the recommended size of the buffer to use for waveform output. The information can be used to create a compatible DirectSound buffer for the port
Parameters:  

Remarks: 

Remarks

The WAVEFORMATEX structure can have a variable length that depends on the details of the format. Before retrieving the format description, the application should query the synthesizer object for the size of the format by calling this method and specifying NULL for the pWaveFormatEx parameter. The size of the structure is returned in the variable pointed to by pdwWaveFormatExSize. The application can then allocate sufficient memory and call GetFormat again to retrieve the format description.

If pWaveFormatEx is not NULL, DirectMusic writes, at most, pdwWaveFormatExSize bytes to the structure.

Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: AllocateMemory
Declaration:
HRESULT COutputPort::AllocateMemory(CSampleInstrument &pSampleInstrument)
Purpose: Prepares the port for a wave-table memory access, obtains the download interfaces and allocates the wave and instrument data 
Parameters:  


Returns:
 

S_OK

Succeeds

Throws:

E_FAIL The method did not succeed
DMUS_E_NOT_DOWNLOADED_TO_PORT The object cannot be unloaded because it is not present on the port
DMUS_E_INVALID_DOWNLOADID An invalid download identifier was used in the process of creating a download buffer
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
E_OUTOFMEMORY Insufficient memory to complete the task
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: DownloadInstrument (CInstrument)
Declaration: HRESULT COutputPort::DownloadInstrument(CInstrument &pInstrument)
Purpose:
  Downloads a given instrument to the port wave-table memory
Parameters:      

Returns:  

S_OK

Succeeds

DM_FAILED Error, see DirectMidi causes

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
DMUS_E_NOT_DOWNLOADED_TO_PORT The object cannot be unloaded because it is not present on the port
E_OUTOFMEMORY Insufficient memory to complete the task

Top    Index

Function: DownloadInstrument (CSampleInstrument)
Declaration: HRESULT COutputPort::DownloadInstrument(CSampleInstrument &pSampleInstrument)
Purpose:
  Downloads a given sample instrument to the port wave-table memory
Parameters:    

Returns:  

S_OK

Succeeds

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
DM_FAILED Error, see DirectMidi causes
E_FAIL The method did not succeed
DMUS_E_ALREADY_DOWNLOADED The buffer has already been downloaded
DMUS_E_BADARTICULATION Invalid articulation chunk in DLS collection
DMUS_E_BADINSTRUMENT Invalid instrument chunk in DLS collection
DMUS_E_BADOFFSETTABLE The offset table has errors
DMUS_E_BADWAVE Corrupt wave header
DMUS_E_BADWAVELINK The wave-link chunk in DLS collection points to invalid wave
DMUS_E_BUFFERNOTSET No buffer was prepared for the data
DMUS_E_NOARTICULATION Articulation missing from an instrument in the DLS collection
DMUS_E_NOTMONO The wave chunk has more than one interleaved channel. DLS format requires mono
DMUS_E_NOTPCM Waveform data is not in PCM format
DMUS_E_UNKNOWNDOWNLOAD The synthesizer does not support this type of download

Top    Index

Function: UnloadInstrument (CInstrument)
Declaration: HRESULT COutputPort::UnloadInstrument(CInstrument &pInstrument)
Purpose:
  Unloads an instrument to the port wave-table memory and frees its space from the synthesizer 
Parameters:      

Returns:  

S_OK

Succeeds

DM_FAILED Error, see DirectMidi causes

Throws:

E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
DMUS_E_NOT_DOWNLOADED_TO_PORT The object cannot be unloaded because it is not present on the port

Top    Index

Function: UnloadInstrument (CSampleInstrument)
Declaration: HRESULT COutputPort::UnloadInstrument(CSampleInstrument &pSampleInstrument)
Purpose:
  Unloads a sample instrument to the port wave-table memory and frees its space from the synthesizer 
Parameters: 

Returns:  

S_OK

Succeeds

Throws:

E_NOINTERFACE No object interface is available
DMUS_E_SYNTHNOTCONFIGURED The synthesizer is not properly configured or opened
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: DeallocateMemory
Declaration: HRESULT COutputPort::DeallocateMemory(CSampleInstrument &pSampleInstrument)
Purpose:
  Deallocates the wave-table memory space and releases the download interfaces 
Parameters:  

Returns:  

S_OK

Succeeds

Throws:

DM_FAILED Error, see DirectMidi causes

Top    Index

Function: CompactMemory
Declaration: HRESULT COutputPort::CompactMemory()
Purpose:
  This method instructs the port to compact DLS or wave-table memory, thus making the largest possible contiguous chunk of memory available for new instruments to be downloaded
Parameters:  
void

Returns:  

S_OK

Succeeds

Throws:

E_OUTOFMEMORY Insufficient memory to complete the task
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL The method did not succeed
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: SendMidiMsg (Long version)
Declaration: HRESULT COutputPort::SendMidiMsg(LPBYTE lpMsg,DWORD dwLength,DWORD dwChannel,DWORD dwChannelGroup)
Purpose:  Sends any kind of data to the port (typically a MIDI system exclusive message)
Parameters:      

Returns:  

S_OK

Succeeds

Throws:

DM_FAILED Error, see DirectMidi causes
E_OUTOFMEMORY Insufficient memory to complete the task
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
S_FALSE Error
E_POINTER NULL pointer argument
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL The call to IReferenceClock::GetTime method did not succeed

Top    Index

Function: SendMidiMsg (Short version)
Declaration: HRESULT COutputPort::SendMidiMsg(DWORD dwMsg,DWORD dwChannelGroup)
Purpose:  Sends a typical MIDI 1.0 message to the port
Parameters:      

Returns:  

S_OK

Succeeds

Throws:

DM_FAILED Error, see DirectMidi causes
E_OUTOFMEMORY Insufficient memory to complete the task
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
S_FALSE Error
E_POINTER NULL pointer argument
DMUS_E_INVALID_EVENT The event either is not a valid MIDI message or makes use of running status and cannot be packed into the buffer
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_FAIL The call to IReferenceClock::GetTime method did not succeed

Top    Index

Function: SetEffect 
Declaration: HRESULT COutputPort::SetEffect(BYTE Effect)
Purpose:  Activates an audio effect in the port
Parameters:    

                                 
Returns:  

DMUS_E_UNKNOWN_PROPERTY The property set or item is not implemented by this port
S_OK

Succeeds

Throws:

E_FAIL The method did not succeed
E_INVALIDARG Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
E_NOTIMPL The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation
E_POINTER An invalid pointer, usually NULL, was passed as a parameter
E_OUTOFMEMORY Insufficient memory to complete the task
E_NOINTERFACE No object interface is available
DM_FAILED Error, see DirectMidi causes

Top    Index

Function: EncodeMidiMsg
Declaration: DWORD COutputPort::EncodeMidiMsg(BYTE Status,BYTE DataByte1,BYTE DataByte2)
Purpose:  Packs a separate midi message in a DWORD midi 1.0 message
Parameters:      

                      See DirectMidi Midi 1.0 messages

Returns:  The encoded midi 1.0 message

Top    Index

Function: EncodeMidiMsg
Declaration: DWORD COutputPort::EncodeMidiMsg(BYTE Command,BYTE Channel,BYTE DataByte1,BYTE DataByte2)
Purpose:  Packs a separate midi message in a DWORD midi 1.0 message
Parameters:      
                      

Returns:  The encoded midi 1.0 message

Top    Index