функция обратного вызова EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUITDEVICE (acxcircuit.h)

Статья
02/06/2025

Обратный вызов EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUITDEVICE вызывается ACX, когда драйвер должен создать WDFDEVICE для нового объекта ACXCIRCUIT.

Синтаксис

EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUITDEVICE EvtAcxFactoryCircuitCreateCircuitdevice;

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

Параметры

Parent

Объект WDFDEVICE (описанный в разделе Сводка объектов Платформы), который является родительским объектом WDFDEVICE, на который ссылается объект Device.

Factory

Существующий объект фабрики каналов ACXFACTORYCIRCUIT. Дополнительные сведения о объектах ACX см. в сводке по объектам ACX.

Config

Структура ACX_FACTORY_CIRCUIT_ADD_CIRCUIT, которая определяет конфигурацию для нового ACXCIRCUIT.

Device

Указатель на расположение, которое получает дескриптор к новому объекту платформы WDFDEVICE (описано в сводке объектов платформы).

Возвращаемое значение

Возвращает STATUS_SUCCESS, если вызов выполнен успешно. В противном случае возвращается соответствующий код ошибки. Дополнительные сведения см. в использовании значений NTSTATUS.

Замечания

AcxFactoryCircuit представляет объект фабрики, способный создавать ACXCIRCUIT по запросу.

Драйвер может зарегистрировать один или несколько ACXFACTORYCIRCUIT в ACX, это действие позволит ACX знать, что драйвер может создавать ACXCIRCUITs хорошо определенного типа.

ACX вызывает обратные вызовы ACXFACTORYCIRCUIT при обнаружении того, что звуковой путь требует одной из фабрики, предоставленных ACXCIRCUITs.

Объект ACXFACTORYCIRCUIT поддерживает динамические ACXCIRCUITs, это означает, что каждый ACXCIRCUIT, созданный фабрикой, связан с WDFDEVICE, и эти два объекта имеют одно время существования.

AcxFactoryCircuit имеет выделенную очередь WDF. Дополнительные сведения о очередях WDF см. в разделе Объекты очередей Платформы.

Пример

Ниже показан пример использования.

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

минимальная версия ACX: 1.0

Дополнительные сведения о версиях ACX см. в обзоре версий ACX.

Требования

Требование	Ценность
заголовка	acxcircuit.h
IRQL	PASSIVE_LEVEL

См. также

заголовка acxcircuit.h

Поделиться через