WdfRegistryAssignMultiString method

[Applies to KMDF and UMDF]

The WdfRegistryAssignMultiString method assigns a set of strings to a specified value name in the registry. The strings are contained in a specified collection of framework string objects.

Syntax


NTSTATUS WdfRegistryAssignMultiString(
  _In_ WDFKEY           Key,
  _In_ PCUNICODE_STRING ValueName,
  _In_ WDFCOLLECTION    StringsCollection
);

Parameters

Key [in]

A handle to a registry-key object that represents an opened registry key.

ValueName [in]

A pointer to a UNICODE_STRING structure that contains a value name.

StringsCollection [in]

A handle to a framework collection object that represents a collection of framework string objects.

Return value

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

Return codeDescription
STATUS_INVALID_DEVICE_REQUEST

WdfRegistryAssignMultiString was not called at IRQL = PASSIVE_LEVEL.

STATUS_INVALID_PARAMETER

An invalid parameter was specified, or the collection that the StringsCollection parameter specified contained no string objects.

STATUS_ACCESS_DENIED

The driver did not open the registry key with KEY_SET_VALUE access.

 

This method also might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

If the value name that the ValueName parameter specifies already exists, WdfRegistryAssignMultiString updates the value's data.

The framework sets the value's data type to REG_MULTI_SZ.

The object collection that StringsCollection specifies must contain only framework string objects.

For more information about registry-key objects, see Using the Registry in Framework-Based Drivers.

Examples

The following code example creates a collection object and two string objects, adds the string objects to the collection, and then assigns the two strings to one registry value.


WDF_OBJECT_ATTRIBUTES attributes;
WDFCOLLECTION col = NULL;
WDFSTRING string1 = NULL, string2 = NULL;
UNICODE_STRING ustring1, ustring2, valueName;
NTSTATUS status;

status = WdfCollectionCreate(
                             WDF_NO_OBJECT_ATTRIBUTES,
                             &col
                             );
if (!NT_SUCCESS(status) {
    return status;
}

RtlInitUnicodeString(
                     &ustring1,
                     L"String1"
                     );
RtlInitUnicodeString(
                     &ustring2,
                     L"String2"
                     );
RtlInitUnicodeString(
                     &valueName,
                     L"ValueName"
                     );

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = col;

status = WdfStringCreate(
                         &ustring1,
                         &attributes,
                         &string1
                         );
if (!NT_SUCCESS(status)) {
    goto exit;
}
status = WdfStringCreate(
                         &ustring2,
                         &attributes,
                         &string2
                         );
if (!NT_SUCCESS(status)) {
    goto exit;
}
status = WdfCollectionAdd(
                          col,
                          string1
                          );
if (!NT_SUCCESS(status)) {
    goto exit;
}
string1 = NULL;

status = WdfCollectionAdd(
                          col,
                          string2
                          );
if (!NT_SUCCESS(status)) {
    goto exit;
}
string2 = NULL;

status = WdfRegistryAssignMultiString(
                                      Key,
                                      &valueName,
                                      col
                                      );
if (!NT_SUCCESS(status)) {
    goto exit;
...
exit:
if (col != NULL) {
    WdfObjectDelete(col);    // This will empty the collection
                             // because the string objects are
                             // child objects of the collection object.
}

Requirements

Target platform

Universal

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfregistry.h (include Wdf.h)

Library

Wdf01000.sys (KMDF);
WUDFx02000.dll (UMDF)

IRQL

PASSIVE_LEVEL

DDI compliance rules

DriverCreate, KmdfIrql, KmdfIrql2

See also

RtlInitUnicodeString
UNICODE_STRING
WdfCollectionAdd
WdfCollectionCreate
WdfObjectDelete
WdfRegistryAssignValue
WdfRegistryAssignMemory
WdfRegistryAssignString
WdfRegistryAssignUnicodeString
WdfRegistryAssignULong
WdfStringCreate

 

 

Send comments about this topic to Microsoft

Show: