NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-acxcircuit-acxfactorycircuitcreate)

Description

The AcxFactoryCircuitCreate function is used to create an ACXFACTORYCIRCUIT.

Parameters

`Device`

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

`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.

`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.

`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.

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

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.

An AcxFactoryCircuit can only be created on FDOs (not on RAW PDOs). The ACXFACTORYCIRCUIT object uses its FDO's static child list which is not available on a RAW PDO. For more information, see Static Enumeration and Dynamic Enumeration in the WDF documentation.

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.

AcxFactoryCircuitCreate - NtDoc