WdfStringCreate function (wdfstring.h)

Artikel
02/22/2024

[Applies to KMDF and UMDF]

The WdfStringCreate method creates a framework string object and optionally assigns a specified Unicode string to the object.

Syntax

NTSTATUS WdfStringCreate(
  [in, optional] PCUNICODE_STRING       UnicodeString,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringAttributes,
  [out]          WDFSTRING              *String
);

Parameters

[in, optional] UnicodeString

A pointer to a UNICODE_STRING structure that contains a Unicode string constant. The framework copies the string to the new framework string object. This pointer is optional and can be NULL.

[in, optional] StringAttributes

A pointer to a WDF_OBJECT_ATTRIBUTES structure that contains driver-supplied attributes for the new string object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out] String

A pointer to a location that receives a handle to the new string object.

Return value

WdfStringCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the following values:

Return code	Description
STATUS_INVALID_DEVICE_REQUEST	WdfStringCreate was not called at IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	An invalid parameter was specified.
STATUS_INSUFFICIENT_RESOURCES	A string object could not be allocated.

For a list of other return values that the WdfStringCreate method might return, see Framework Object Creation Errors.

This method also might return other NTSTATUS values.

Remarks

The default parent for framework string objects is the driver's framework driver object. However, unless the string is associated with the driver, your driver should set the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure to an object that represents the string's scope. Typically, strings are device-specific and their parent object should be a framework device object.

If your driver provides EvtCleanupCallback or EvtDestroyCallback callback functions for the framework string object, note that the framework calls these callback functions at IRQL = PASSIVE_LEVEL.

For more information about framework string objects, see Using String Objects.

Examples

The following code example initializes a WDF_OBJECT_ATTRIBUTES structure and then creates a framework string object.

NTSTATUS  status;
WDFSTRING  stringHandle = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = pDeviceContext->Device;
status = WdfStringCreate(
                         NULL,
                         &attributes,
                         &stringHandle
                         );
if (!NT_SUCCESS(status)){
    return status;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfstring.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Delen via