| CInputPort |
Purpose: Handles all input midi ports and
processes all their messages
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
CInputPort::Initialize(CDirectMusic &pDMusic)
Purpose:
Initializes the input port object
Parameters:
pDMusic [in]:
Reference to the main DirectMusic object
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
Function:
GetNumPorts
Declaration: DWORD CInputPort::GetNumPorts()
Purpose: Returns
the number of input midi ports in the system
Parameters:
Void
Returns:
| Number of ports |
Number of input midi ports, if 0 is returned, no input 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 |
Function: GetPortInfo
Declaration: HRESULT
CInputPort::GetPortInfo(DWORD dwNumPort,LPINFOPORT
lpInfoPort)
Purpose: Gets the port info structure of a given
number of midi port
Parameters:
dwNumPort [in]: Number of midi port, where dwNumPort must be greater than 0
lpInfoPort [out]: Address of an INFOPORT structure
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 |
Function:
GetActivatedPortInfo
Declaration: HRESULT CInputPort::GetActivatedPortInfo(LPINFOPORT
lpInfoPort)
Purpose: Gets the port info structure of the
current activated midi port
Parameters:
lpInfoPort [out]: Address of an INFOPORT structure
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 |
Function:
ActivatePort
Declaration: HRESULT CInputPort::ActivatePort(LPINFOPORT InfoPort,DWORD
dwSysExSize)
Purpose: Activate the input midi port providing a
pointer to an INFOPORT structure with the port identification.
Allocate the
buffer memory for incoming system exclusive events.
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 |
Function:
ActivatePortFromInterface
Declaration: HRESULT CInputPort::ActivatePortFromInterface(IDirectMusicPort8* pPort,DWORD dwSysExSize)
Purpose: Activate the input midi port providing a
pointer to an IDirectMusicPort8 interface pointer.
Allocate the
buffer memory for incoming 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 |
Function:
SetReceiver
Declaration: HRESULT CInputPort::SetReceiver(CReceiver
&Receiver)
Purpose: Sets the Receiver object for
receiving MIDI messages
Parameters:
CReceiver [in]: Reference to the Receiver object
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
Function: ReleasePort
Declaration: HRESULT
CInputPort::ReleasePort()
Purpose: Releases the DirectMidi COM
interfaces for a new port selection, this member function is also called by the
destructor.
Parameters: Void
Remarks:
Call this member function to deactivate the current 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 |
Function:
KsProperty
Declaration: HRESULT CInputPort::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 |
Function:
ActivateNotification
Declaration: HRESULT
CInputPort::ActivateNotification()
Purpose: Prepares DirectMidi
for handling input midi events
Parameters:
void
Returns:
| S_OK |
Succeeds |
Throws:
| DMUS_E_DMUSIC_RELEASED | The operation cannot be performed because the final instance of the DirectMusic object was released. Ports cannot be used after final release of the DirectMusic object |
| E_NOTIMPL | The method is not implemented. This value might be returned if a driver does not support a feature necessary for the operation |
| DM_FAILED | Error, see DirectMidi causes |
Function:
SetThru
Declaration: HRESULT CInputPort::SetThru(DWORD dwSourceChannel,DWORD
dwDestinationChannelGroup,DWORD dwDestinationChannel,COutputPort
&pdstMidiPort)
Purpose: Activates the MIDI thru from an
Input MIDI port to a given Output MIDI
port
Parameters:
Returns:
| S_OK |
Succeeds |
Throws:
| DM_FAILED | Error, see DirectMidi causes |
| 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. |
| DMUS_E_PORT_NOT_RENDER | The port is not an output port |
Function:
BreakThru
Declaration: HRESULT CInputPort::BreakThru(DWORD dwSourceChannel,DWORD
dwDestinationChannelGroup,DWORD dwDestinationChannel)
Purpose:
Breaks the established thru
connection
Parameters:
dwSourceChannel [in]: Source port channel (1-16)
dwDestinationChannelGroup [in]: Channel group. Each channel group is a set of 16 MIDI channels
dwDestinationChannel [in]: Destiny port channel (1-16)
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. |
| DMUS_E_PORT_NOT_RENDER | The port is not an output port |
| DM_FAILED | Error, see DirectMidi causes |
Function:
TerminateNotification
Declaration: HRESULT
CInputPort::TerminateNotification()
Purpose: Terminates the
midi notification handling, tells the worker thread to exit and unsignals events.
Parameters: Void
Returns:
| S_OK |
Succeeds |
| DM_FAILED | Error, see DirectMidi causes |
Throws:
| DMUS_E_DMUSIC_RELEASED |
The operation cannot be performed because the final instance of the DirectMusic object was released. Ports cannot be used after final release of the DirectMusic object.
|
| E_NOTIMPL | The method is not implemented. This value might be returned if a
driver does not support a feature necessary for the operation.
|
Function:
SetThreadPriority
Declaration: HRESULT CInputPort::SetThreadPriority(int nPriority)
Purpose:
Sets the priority value for the input port receiver thread
Parameters:
| THREAD_PRIORITY_ABOVE_NORMAL | Indicates 1 point above normal priority for the priority class |
| THREAD_PRIORITY_BELOW_NORMAL | Indicates 1 point below normal priority for the priority class |
| THREAD_PRIORITY_HIGHEST | Indicates 2 points above normal priority for the priority class |
| THREAD_PRIORITY_IDLE | Indicates a base priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 16 for REALTIME_PRIORITY_CLASS processes |
| THREAD_PRIORITY_LOWEST | Indicates 2 points below normal priority for the priority class |
| THREAD_PRIORITY_NORMAL | Indicates normal priority for the priority class |
| THREAD_PRIORITY_TIME_CRITICAL | Indicates a base priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 31 for REALTIME_PRIORITY_CLASS processes |
Returns:
| TRUE |
Succeeds |
Throws:
| DM_FAILED |
Error, see DirectMidi causes |
Function:
SetBuffer
Declaration: HRESULT CInputPort::SetBuffer(DWORD dwBufferSize)
Purpose:
Sets internal buffer for storing incoming 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 CInputPort::RemoveBuffer()
Purpose:
Removes the internal buffer
Returns:
| S_FALSE | Error |
| S_OK |
Succeeds |
Function: DecodeMidiMsg
Declaration: void
CInputPort::DecodeMidiMsg(DWORD dwMsg,BYTE *Status,BYTE *DataByte1,BYTE
*DataByte2)
Purpose: Short version of a structured midi message
decodification
Parameters:
dwMsg [in]: Structured Midi 1.0 message
Status [out]: Address of the status byte
DataByte1 [out]: Address of first byte
DataByte2 [out]: Address of second byte
See DirectMidi Midi 1.0 messages
Returns: nothing
Throws: nothing
Function:
DecodeMidiMsg
Declaration: void CInputPort::DecodeMidiMsg(DWORD dwMsg,BYTE *Command,BYTE
*Channel,BYTE *DataByte1,BYTE *DataByte2)
Purpose: Long version
of a strucutred midi message
decodification
Parameters:
dwMsg [in]: Structured Midi 1.0 message
Command [out]: Address of Command byte
Channel [out]: Address of channel byte
DataByte1 [out]: Address of first byte
DataByte2 [out]: Address of second byte
See DirectMidi Midi 1.0 messages
Returns: nothing
Throws: nothing