WdfRegistryAssignMultiString function (wdfregistry.h)

[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

[in] Key

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

[in] ValueName

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

[in] StringsCollection

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:

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

See also

RtlInitUnicodeString

UNICODE_STRING

WdfCollectionAdd

WdfCollectionCreate

WdfObjectDelete

WdfRegistryAssignMemory

WdfRegistryAssignString

WdfRegistryAssignULong

WdfRegistryAssignUnicodeString

WdfRegistryAssignValue

WdfStringCreate