Microsoft DirectX 9.0

IDirectMusic8::CreatePort

The CreatePort method creates an object for a DirectMusic port.

Syntax

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 IDirectMusicPort8 interface is to be created. The GUID is retrieved through the IDirectMusic8::EnumPort method. If it is GUID_NULL, the returned port is the default port. For more information, see Default Port.

pPortParams

Address of a DMUS_PORTPARAMS8 structure that contains parameters for the port. The dwSize member of this structure must be initialized to sizeof(DMUS_PORTPARAMS8) before the method is called.

ppPort

Address of a variable that receives an IDirectMusicPort interface pointer.

pUnkOuter

Address of the controlling object's IUnknown interface for COM aggregation. Because aggregation is not currently supported, 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 can return one of error values in the following table.

Return code
CLASS_E_NOAGGREGATION
DMUS_E_DSOUND_NOT_SET
E_INVALIDARG
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

Remarks

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

If not all parameters could be obtained, the DMUS_PORTPARAMS8 structure is 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, 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, 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, the parameter value in *pPortParams is changed. In this case, the flag in dwValidParams remains set, but S_FALSE is returned to indicate that the value has been changed.

Requirements

  Header: Declared in dmusicc.h.

See Also