| Microsoft DirectX 9.0 SDK Update (Summer 2004) |
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
© 2004 Microsoft Corporation. All rights reserved.