Edit

EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUITDEVICE callback function (acxcircuit.h)

  • Article

The EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUITDEVICE callback is invoked by ACX when the driver must create a WDFDEVICE for a new ACXCIRCUIT object.

Syntax

EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUITDEVICE EvtAcxFactoryCircuitCreateCircuitdevice;

NTSTATUS EvtAcxFactoryCircuitCreateCircuitdevice(
  WDFDEVICE Parent,
  ACXFACTORYCIRCUIT Factory,
  PACX_FACTORY_CIRCUIT_ADD_CIRCUIT Config,
  WDFDEVICE *Device
)
{...}

Parameters

Parent

A WDFDEVICE object (described in Summary of Framework Objects) that is the parent of the WDFDEVICE referenced in Device object.

Factory

The existing circuit factory ACXFACTORYCIRCUIT Object. For more information about ACX objects, see Summary of ACX Objects.

Config

An ACX_FACTORY_CIRCUIT_ADD_CIRCUIT structure that defines the configuration for the new ACXCIRCUIT.

Device

A pointer to a location that receives a handle to the new WDFDEVICE framework object (described in Summary of Framework Objects).

Return value

Returns STATUS_SUCCESS if the call was successful. Otherwise, it returns an appropriate error code. For more information, see Using NTSTATUS Values.

Remarks

An AcxFactoryCircuit represents a factory object capable of creating an ACXCIRCUIT on demand.

A driver can register one or more ACXFACTORYCIRCUIT with ACX, this action will let ACX know that the driver is capable of creating ACXCIRCUITs of a well defined type.

ACX invokes the ACXFACTORYCIRCUIT's callbacks when it detects that an audio path requires one of the factory provided ACXCIRCUITs.

The ACXFACTORYCIRCUIT object supports dynamic ACXCIRCUITs, this means that each ACXCIRCUIT created by the factory is associated with a WDFDEVICE and these two objects have the same lifetime.

An AcxFactoryCircuit has a dedicated WDF queue. For more information about WDF queues, see Framework Queue Objects.

Example

Example usage is shown below.

NTSTATUS
Dsp_EvtAcxFactoryCircuitCreateCircuitDevice(
    _In_  WDFDEVICE                         Parent,
    _In_  ACXFACTORYCIRCUIT                 Factory,
    _In_  PACX_FACTORY_CIRCUIT_ADD_CIRCUIT  CircuitConfig,
    _Out_ WDFDEVICE* Device
)
{
    ACXOBJECTBAG circuitProperties;

    PAGED_CODE();

    NTSTATUS status = STATUS_SUCCESS;
    WDF_OBJECT_ATTRIBUTES attributes;

    *Device = NULL;

    // Create object bag from the CircuitProperties
    ACX_OBJECTBAG_CONFIG propConfig;
    ACX_OBJECTBAG_CONFIG_INIT(&propConfig);
    propConfig.Handle = CircuitConfig->CircuitProperties;
    propConfig.Flags |= AcxObjectBagConfigOpenWithHandle;

    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

    RETURN_NTSTATUS_IF_FAILED(AcxObjectBagOpen(&attributes, &propConfig, &circuitProperties));

    auto cleanupPropConfig = scope_exit([=]() {
        WdfObjectDelete(circuitProperties);
        }
    );

    // Retrieve the intended Circuit ID from the object bag
    GUID circuitId;
    RETURN_NTSTATUS_IF_FAILED(Dsp_DetermineCircuitGuidFromVendorProperties(circuitProperties, &circuitId));

    // Call the appropriate CreateCircuitDevice based on the Circuit ID
    if (IsEqualGUID(circuitId, DSP_CIRCUIT_MICROPHONE_GUID) || IsEqualGUID(circuitId, DSP_CIRCUIT_UNIVERSALJACK_CAPTURE_GUID))
    {
        return DspC_EvtAcxFactoryCircuitCreateCircuitDevice(Parent, Factory, CircuitConfig, Device);
    }
    else if (IsEqualGUID(circuitId, DSP_CIRCUIT_SPEAKER_GUID) || IsEqualGUID(circuitId, DSP_CIRCUIT_UNIVERSALJACK_RENDER_GUID))
    {
        return DspR_EvtAcxFactoryCircuitCreateCircuitDevice(Parent, Factory, CircuitConfig, Device);
    }

    status = STATUS_NOT_SUPPORTED;
    DrvLogError(g_SDCAVDspLog, FLAG_INIT, L"Unexpected CircuitId %!GUID!, %!STATUS!", &circuitId, status);
    return status;
}

ACX requirements

Minimum ACX version: 1.0

For more information about ACX versions, see ACX version overview.

Requirements

Requirement Value
Header acxcircuit.h
IRQL PASSIVE_LEVEL

See also