Edit

Share via

SHEvaluateSystemCommandTemplate function (shellapi.h)

  • Article

Enforces strict validation of parameters used in a call to CreateProcess or ShellExecute.

Syntax

SHSTDAPI SHEvaluateSystemCommandTemplate(
  [in]            PCWSTR pszCmdTemplate,
  [out]           PWSTR  *ppszApplication,
  [out, optional] PWSTR  *ppszCommandLine,
  [out, optional] PWSTR  *ppszParameters
);

Parameters

[in] pszCmdTemplate

Type: PCWSTR

A command line, which may or may not include parameters. If the parameters are substitution parameters, then SHEvaluateSystemCommandTemplate should be called before parameters have been replaced.

[out] ppszApplication

Type: PWSTR*

A pointer to the verified path to the application. This value should be passed as the lpApplication parameter in a call to CreateProcess or as the lpFile parameter in a call to ShellExecute. This resource is allocated using CoTaskMemAlloc, and it is the responsibility of the caller to free the resource when it is no longer needed by calling CoTaskMemFree.

[out, optional] ppszCommandLine

Type: PWSTR*

A pointer to a command-line string template to be used in a call to CreateProcess. Command-line parameters should be specified based on this template, and then passed as the lpCommandLine parameter to CreateProcess. It is guaranteed to be of a form that PathGetArgs can always read correctly. This resource is allocated using CoTaskMemAlloc, and it is the responsibility of the caller to free the resource when it is no longer needed by calling CoTaskMemFree.

This parameter can be NULL if this function is not being used in association with a call to CreateProcess.

[out, optional] ppszParameters

Type: PWSTR*

A pointer to a command-line string template to be used in a call to ShellExecute. Command-line parameters should be specified based on this template, and then passed as the lpParameters parameter to ShellExecute. This parameter is identical to calling PathGetArgs. This resource is allocated using CoTaskMemAlloc, and it is the responsibility of the caller to free the resource when it is no longer needed by calling CoTaskMemFree.

This parameter can be NULL if this function is not being used in association with a call to CreateProcess.

Return value

Type: HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This function is used when a calling process needs the deterministic behavior from a command template, regardless of execution context. It ignores the current process state, such as the %PATH%, GetCurrentDirectory, and parent process directory.

This function is used when the command is hard-coded.

This function is used by ShellExecute when handling file associations from HKEY_CLASSES_ROOT. The purpose of this function is to reduce CreateProcess command-line exploits. It is not designed for processing user input and if used for that purpose can generate unexpected failures.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header shellapi.h
DLL Shell32.dll
API set ext-ms-win-shell-shell32-l1-2-2 (introduced in Windows 10, version 10.0.14393)