UrsDeviceInitialize function (ursdevice.h)

Initializes a framework device object to support operations related to a USB dual-role controller and registers the relevant event callback functions with the USB dual-role controller class extension.

Syntax

NTSTATUS UrsDeviceInitialize(
  [in] WDFDEVICE   Device,
  [in] PURS_CONFIG Config
);

Parameters

[in] Device

A handle to the framework device object that the client driver retrieved in the previous call to WdfDeviceCreate.

[in] Config

A pointer to a URS_CONFIG structure that the client driver initialized by calling URS_CONFIG_INIT.

Return value

The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return an appropriate NTSTATUS error code.

Remarks

The client driver for the USB dual-role controller must call this method after the WdfDeviceCreate call.

The client driver calls this method in its EvtDriverDeviceAdd implementation.

During this call, the client driver-supplied event callback implementations are also registered by setting appropriate members of URS_CONFIG.

The method creates resource lists for host and function roles and the queues required to handle IOCTL requests that are sent to the controller. With each role switch operation, the current role's child device stack is torn down and the device stack for the new role is loaded. The UrsDeviceInitialize method retrieves identifying information that is used to build those device stacks. The method also retrieves information about the device from the underlying bus, such as ACPI.

Examples

EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtUrsFilterResourceRequirements;
EVT_URS_SET_ROLE EvtUrsSetRole;

EvtDriverDeviceAdd (
    _In_ WDFDRIVER Driver,
    _Inout_ PWDFDEVICE_INIT DeviceInit
    )
{
...

    WDFDEVICE device;
    NTSTATUS status;
    WDF_OBJECT_ATTRIBUTES attributes;
    URS_CONFIG ursConfig;
...
 
    status = UrsDeviceInitInitialize(DeviceInit);
    if (!NT_SUCCESS(status)) {
        //UrsDeviceInitInitialize failed.
        return status;
    }
   
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, DRIVER_CONTEXT);
    status = WdfDeviceCreate(&DeviceInit, &attributes, &device);
    if (!NT_SUCCESS(status)) {
        // WdfDeviceCreate failed.
        return status;
    }
    URS_CONFIG_INIT(&ursConfig, UrsHostInterfaceTypeXhci, EvtUrsFilterResourceRequirements);
    
    ursConfig.EvtUrsSetRole = EvtUrsSetRole;
    status = UrsDeviceInitialize(device, &ursConfig);

    if (!NT_SUCCESS(status)) {
        // UrsDeviceInitialize failed.
        return status;

    }

...

}

Requirements

Requirement	Value
Minimum supported client	Windows 10
Minimum supported server	Windows Server 2016
Target Platform	Windows
Minimum KMDF version	1.15
Header	ursdevice.h (include Urscx.h)
Library	Urscxstub.lib
IRQL	PASSIVE_LEVEL

See also

URS_CONFIG

URS_CONFIG_INIT