EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUIT callback function (acxcircuit.h)
The EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUIT callback is invoked by ACX when the driver must create an ACXCIRCUIT object with the specified configuration.
Syntax
EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUIT EvtAcxFactoryCircuitCreateCircuit;
NTSTATUS EvtAcxFactoryCircuitCreateCircuit(
WDFDEVICE Parent,
WDFDEVICE Device,
ACXFACTORYCIRCUIT Factory,
PACX_FACTORY_CIRCUIT_ADD_CIRCUIT Config,
PACXCIRCUIT_INIT CircuitInit
)
{...}
Parameters
Parent
A WDFDEVICE object (described in Summary of Framework Objects) that is the parent of the WDFDEVICE referenced in Device object.
Device
A WDFDEVICE object (described in Summary of Framework Objects) created in the EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUITDEVICE callback. This device will be associated with the new ACXCIRCUIT.
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.
CircuitInit
ACXCIRCUIT_INIT is an opaque object used for circuit initialization. Use AcxCircuitInitAllocate to initialize the ACXCIRCUIT_INIT structure.
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.
An AcxFactoryCircuit has a dedicated WDF queue. For more information about WDF queues, see Framework Queue Objects.
Example
Example usage is shown below.
EVT_ACX_FACTORY_CIRCUIT_CREATE_CIRCUIT Dsp_EvtAcxFactoryCircuitCreateCircuit;
NTSTATUS
Dsp_EvtAcxFactoryCircuitCreateCircuit(
_In_ WDFDEVICE Parent,
_In_ WDFDEVICE Device,
_In_ ACXFACTORYCIRCUIT Factory,
_In_ PACX_FACTORY_CIRCUIT_ADD_CIRCUIT CircuitConfig,
_In_ PACXCIRCUIT_INIT CircuitInit
)
{
ACXOBJECTBAG circuitProperties;
PAGED_CODE();
NTSTATUS status = STATUS_SUCCESS;
// Create object bag from the CompositeProperties
ACX_OBJECTBAG_CONFIG propConfig;
ACX_OBJECTBAG_CONFIG_INIT(&propConfig);
propConfig.Handle = CircuitConfig->CircuitProperties;
propConfig.Flags |= AcxObjectBagConfigOpenWithHandle;
WDF_OBJECT_ATTRIBUTES attributes;
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));
AcxCircuitInitSetComponentId(CircuitInit, &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_EvtAcxFactoryCircuitCreateCircuit(Parent, Device, Factory, CircuitConfig, CircuitInit);
}
else if (IsEqualGUID(circuitId, DSP_CIRCUIT_SPEAKER_GUID) || IsEqualGUID(circuitId, DSP_CIRCUIT_UNIVERSALJACK_RENDER_GUID))
{
return DspR_EvtAcxFactoryCircuitCreateCircuit(Parent, Device, Factory, CircuitConfig, CircuitInit);
}
status = STATUS_NOT_SUPPORTED;
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 |