PcNewDmaChannel function (portcls.h)

Article
10/21/2021

The PcNewDmaChannel function creates a new DMA-channel object. This function is obsolete; for more information, see the following comments.

Syntax

PORTCLASSAPI NTSTATUS PcNewDmaChannel(
  [out]          PDMACHANNEL         *OutDmaChannel,
  [in, optional] PUNKNOWN            OuterUnknown,
  [in]           POOL_TYPE           PoolType,
  [in]           PDEVICE_DESCRIPTION DeviceDescription,
  [in]           PDEVICE_OBJECT      DeviceObject
);

Parameters

[out] OutDmaChannel

Output pointer for the DMA-channel object created by this function. This parameter points to a caller-allocated pointer variable into which the function outputs a reference to the newly created IDmaChannel object. Specify a valid, non-NULL pointer value for this parameter.

[in, optional] OuterUnknown

Pointer to the IUnknown interface of an object that needs to aggregate the object. Unless aggregation is required, set this parameter to NULL.

[in] PoolType

Specifies the type of storage pool from which the object is to be allocated. This is a POOL_TYPE enumeration value. Specify a nonpaged pool type for this parameter.

[in] DeviceDescription

Pointer to a description of the physical device for which the caller is requesting a DMA object. This parameter points to a structure of type DEVICE_DESCRIPTION.

[in] DeviceObject

Pointer to the device object for the physical adapter device. This parameter points to a system structure of type DEVICE_OBJECT.

Return value

PcNewDmaChannel returns STATUS_SUCCESS if the call was successful. Otherwise, it returns an appropriate error code.

Remarks

PcNewDmaChannel is obsolete. For all new audio drivers, use one of the following IPortWave Xxx::NewXxxDmaChannel methods in place of PcNewDmaChannel:

IPortWavePci::NewMasterDmaChannel

IPortWaveCyclic::NewMasterDmaChannel

IPortWaveCyclic::NewSlaveDmaChannel

For the sake of backward compatibility, the PortCls system driver will continue to support PcNewDmaChannel, and existing drivers can continue to use this function.

Specify the PoolType parameter to be one of the nonpaged pool types defined in the POOL_TYPE enumeration. The DMA-channel object must not reside in paged memory because several of the methods in the IDmaChannel interface can be called from IRQL DISPATCH_LEVEL.

The OutDmaChannel and OuterUnknown parameters follow the reference-counting conventions for COM objects.

Note

Microsoft supports a diverse and inclusive environment. This article contains references to terminology that the Microsoft style guide for bias-free communication recognizes as exclusionary. The word or phrase is used in this article for consistency because it currently appears in the software. When the software is updated to remove the language, this article will be updated to be in alignment.

Requirements

Requirement	Value
Minimum supported client	Obsolete. For all new audio drivers, use a IPortWaveXxx::NewXxxDmaChannel method instead. The PortCls system driver implements the PcNewDmaChannel function in Microsoft Windows 98/Me and in Windows 2000 and later operating systems.
Target Platform	Universal
Header	portcls.h (include Portcls.h)
Library	Portcls.lib
IRQL	PASSIVE_LEVEL