Share via


SetExpandedStringValue method of the StdRegProv class

The SetExpandedStringValue method sets the data value for a named value whose data type is REG_EXPAND_SZ.

This topic uses Managed Object Format (MOF) syntax. For more information about using this method, see Calling a Method.

Syntax

uint32 SetExpandedStringValue(
  [in] uint32 hDefKey = HKEY_LOCAL_MACHINE,
  [in] string sSubKeyName,
  [in] string sValueName,
  [in] string sValue = 
);

Parameters

hDefKey [in]

A registry tree, also known as a hive, that contains the sSubKeyName path. The default value is HKEY_LOCAL_MACHINE.

The following trees are defined in WinReg.h.

HKEY_CLASSES_ROOT (2147483648)

HKEY_CURRENT_USER (2147483649)

HKEY_LOCAL_MACHINE (2147483650)

HKEY_USERS (2147483651)

HKEY_CURRENT_CONFIG (2147483653)

sSubKeyName [in]

A key that contains the named value to be set.

sValueName [in]

A named value whose data value you are setting. You can specify an existing named value (update) or a new named value (create). Specify an empty string to set the data value for the default named value.

sValue [in]

An expanded string data value. The environment variable specified in the string must exist for the string to be expanded when you call GetExpandedStringValue.

Return value

In C++, the method returns a uint32 value that is 0 (zero) if successful. If the function fails, the return value is a nonzero error code that is defined in WinError.h. In C++, use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error. You can also look up return values under the WMI Error Constants.

In scripting or Visual Basic, the method returns an integer value that is 0 (zero) if successful. If the function fails, the return value is a nonzero error code that you can look up in WbemErrorEnum.

Remarks

Expanded strings are strings that can include variables; these variables are resolved when an application or a service uses the value. For example, the value of an entry that references a file might include the variable %systemroot%. When a service, such as the Event Log, references the entry, the %systemroot% variable is replaced by the name of the directory containing the Windows system files (for example, C:\Windows). On a different computer, one with Windows installed on drive D, this same registry value might be replaced by D:\Windows.

If you need to create an entry that includes a value that might change, such as the path environment variable or the location of the current user's profile, you can use the SetExpandedStringValue method.

Examples

The Create Expanded String Values VBScript sample uses WMI to create an expanded string value under the HKLM\SOFTWARE\System Admin Scripting Guide portion of the registry.

The following VBScript code example shows how to use the SetExpandedStringValue method. The script first creates a new key then creates a new expanded string value under the key.

const HKEY_LOCAL_MACHINE = &H80000002
strComputer = "."
Set objReg=GetObject("winmgmts:{impersonationLevel=impersonate}!\\"&_
    strComputer & "\root\default:StdRegProv")
' Create a new key
strKeyPath = "Software\MyKey\MySubKey"
Return = objReg.CreateKey(HKEY_LOCAL_MACHINE, strKeyPath)
If (Return = 0) And (Err.Number = 0) Then   
    Wscript.Echo _
        "HKEY_LOCAL_MACHINE\Software\MyKey\MySubKey created"
Else
    Wscript.Echo "CreateKey failed. Error = " & Err.Number
End If
' Create an expanded string and give it a value
strValueName = "Expanded String Value Name"
strValue = "%ExpandedStringValue%"
' Write expanded string value
Return = objReg.SetExpandedStringValue( _
    HKEY_LOCAL_MACHINE,strKeyPath,strValueName,strValue)
If (Return = 0) And (Err.Number = 0) Then   
    Wscript.Echo "SetExpandedStringValue succeeded"
Else
    Wscript.Echo _
        "SetExpandedStringValue failed. Error = " & Err.Number
End If

Requirements

Minimum supported client
Windows Vista
Minimum supported server
Windows Server 2008
Namespace
Root\default
MOF
RegEvent.mof
DLL
Stdprov.dll