IDirectMusic::CreatePort

The IDirectMusic::CreatePort method is used to create an object for a particular DirectMusic port.

HRESULT CreatePort(
  REFCLSID rclsidPort,
  LPDMUS_PORTPARAMS pPortParams,
  LPDIRECTMUSICPORT *ppPort,
  LPUNKNOWN pUnkOuter
);
 

Parameters

rclsidPort

Reference to (C++) or address of (C) the GUID that identifies the port for which the IDirectMusicPort interface is to be created. The GUID is retrieved through the IDirectMusic::EnumPort method. If it is GUID_NULL, then the returned port will be the default port. For more information, see Default Port.

pPortParams

Address of a DMUS_PORTPARAMS structure containing parameters for the port. The dwSize member of this structure must be initialized before the method is called.

ppPort

Address of a variable to receive an IDirectMusicPort interface pointer.

pUnkOuter

Address of the controlling object's IUnknown interface for COM aggregation. Aggregation is not currently supported, so this value must be NULL.

Return Values

If the method succeeds, the return value is S_OK, or S_FALSE if a requested parameter is not available.

If it fails, the method may return one of the following error values:

Remarks

By default, the port is inactive when it is created. It must be activated by a call to IDirectMusic::Activate or IDirectMusicPort::Activate.

If not all parameters could be obtained, then the DMUS_PORTPARAMS structure will be changed as follows to match the available parameters of the port.

On entry, the dwValidParams member of the structure indicates which members in the structure are valid. If the flag is not set for a member of the structure, then a default value is set for that parameter when the port is created.

On return, the flags in dwValidParams show which port parameters were set. If a particular parameter was not requested but was set to the default, then that flag is added to those passed in.

If the port supports a specified parameter, but the given value for the parameter is out of range, then the parameter value in *pPortParams will be changed. In this case, the flag in dwValidParams remains set, but S_FALSE will be returned to indicate that the value has been changed.

The following code shows how an application can request reverb capabilities and determine if they were obtained. (For an alternative way of checking and setting port properties, see Port Property Sets.)

DMUS_PORTPARAMS params; 
 
ZeroMemory(&params, sizeof(params)); 
params.dwSize = sizeof(params); 
params.dwValidParams = DMUS_PORTPARAMS_EFFECTS; 
params.dwEffectFlags = DMUS_EFFECT_REVERB;
HRESULT hr = pDirectMusic->CreatePort(guidPort, &params, 
        &port, NULL); 
if (SUCCEEDED(hr)) 
{ 
    fGotReverb = TRUE;
    if (hr == S_FALSE) 
    { 
        if (!(params.dwValidParams & DMUS_PORTPARAMS_EFFECTS)) 
        { 
            // Device does not support any effects
            fGotReverb = FALSE; 
        } 
        else if (!(params.dwEffectFlags & DMUS_EFFECT_REVERB)) 
        { 
            // Device understands effects, 
            // but could not allocate reverb
            fGotReverb = FALSE;
        } 
    } 
}
 

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dmusicc.h.