Skip to content

Latest commit

 

History

History
127 lines (96 loc) · 4.39 KB

nf-acxcircuit-acxfactorycircuitcreate.md

File metadata and controls

127 lines (96 loc) · 4.39 KB
Raw
UID tech.root title ms.date targetos description prerelease req.assembly req.construct-type req.ddi-compliance req.dll req.header req.idl req.include-header req.irql req.kmdf-ver req.lib req.max-support req.namespace req.redist req.target-min-winverclnt req.target-min-winversvr req.target-type req.type-library req.umdf-ver req.unicode-ansi topic_type api_type api_location api_name f1_keywords dev_langs
NF:acxcircuit.AcxFactoryCircuitCreate
audio
AcxFactoryCircuitCreate
12/14/2022
Windows
The AcxFactoryCircuitCreate function is used to create an ACXFACTORYCIRCUIT.
false
function
acxcircuit.h
PASSIVE_LEVEL
apiref
HeaderDef
acxcircuit.h
AcxFactoryCircuitCreate
AcxFactoryCircuitCreate
acxcircuit/AcxFactoryCircuitCreate
c++

-description

The AcxFactoryCircuitCreate function is used to create an ACXFACTORYCIRCUIT.

-parameters

-param Device

A WDFDEVICE object (described in Summary of Framework Objects) that will be associated with the circuit.

-param Attributes

Additional Attributes defined using a WDF_OBJECT_ATTRIBUTES that are used to set the various object's values: cleanup and destroy callbacks, context type, and to specify its WDF parent object.

-param Config

The ACXFACTORYCIRCUIT_INIT structure that defines the circuit factory initialization. ACXFACTORYCIRCUIT_INIT is an opaque object used for circuit factory initialization. Use AcxFactoryCircuitInitAllocate to initialize the ACXFACTORYCIRCUIT_INIT structure.

-param Factory

A pointer to a location that receives a handle to the new ACXFACTORYCIRCUIT Object. For more information about ACX objects, see Summary of ACX Objects.

-returns

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

-remarks

The ACXFACTORYCIRCUIT is used by the ACX framework for 'on-demand' ACXCIRCUITs. ACX will ask the ACXFACTORYCIRCUIT to create a new circuit when an endpoint requires one.

The ACXFACTORYCIRCUIT is used in a multi-circuit endpoint. A circuit created by an ACXFACTORYCIRCUIT cannot be the 'core' circuit for the endpoint, i.e., the circuit that gives the endpoint identity.

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

Example

Example usage is shown below.

    NTSTATUS                                        status;
    WDF_OBJECT_ATTRIBUTES                           attributes;
    ACXFACTORYCIRCUIT                               factory;
    PACXFACTORYCIRCUIT_INIT                         factoryInit = NULL;
    SDCAXU_FACTORYCIRCUIT_CONTEXT *                 factoryCtx;
    ACX_FACTORY_CIRCUIT_OPERATION_CALLBACKS         operationCallbacks;

    //
    // Get a FactoryCircuitInit structure.
    //
    factoryInit = AcxFactoryCircuitInitAllocate(Device);

    //
    // Add factory identifiers.
    //
    AcxFactoryCircuitInitSetComponentId(factoryInit, &SDCAXU_FACTORY_GUID);
    AcxFactoryCircuitInitAssignCategories(factoryInit, &SDCAXU_FACTORY_CATEGORY, 1);
    AcxFactoryCircuitInitAssignName(factoryInit, &s_FactoryName);

    //
    // Assign the circuit's operation-callbacks.
    //
    ACX_FACTORY_CIRCUIT_OPERATION_CALLBACKS_INIT(&operationCallbacks);
    operationCallbacks.EvtAcxFactoryCircuitCreateCircuitDevice = SdcaXu_EvtAcxFactoryCircuitCreateCircuitDevice;
    operationCallbacks.EvtAcxFactoryCircuitCreateCircuit = SdcaXu_EvtAcxFactoryCircuitCreateCircuit;
    AcxFactoryCircuitInitSetOperationCallbacks(factoryInit, &operationCallbacks);

    //
    // Create the factory circuit.
    //
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, SDCAXU_FACTORYCIRCUIT_CONTEXT);
    attributes.ParentObject = Device;
    status = AcxFactoryCircuitCreate(Device, &attributes, &factoryInit, &factory);

ACX requirements

Minimum ACX version: 1.0

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

-see-also