AcxFactoryCircuitCreate function (acxcircuit.h)

Article
10/03/2023

The AcxFactoryCircuitCreate function is used to create an ACXFACTORYCIRCUIT.

Syntax

NTSTATUS AcxFactoryCircuitCreate(
  WDFDEVICE               Device,
  PWDF_OBJECT_ATTRIBUTES  Attributes,
  PACXFACTORYCIRCUIT_INIT *Config,
  ACXFACTORYCIRCUIT       *Factory
);

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.

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.

Requirements

Requirement	Value
Header	acxcircuit.h
IRQL	PASSIVE_LEVEL

Share via