Export (0) Print
Expand All
Expand Minimize

SHEvaluateSystemCommandTemplate function

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

Syntax


HRESULT SHEvaluateSystemCommandTemplate(
  _In_       PCWSTR pszCmdTemplate,
  _Out_      PWSTR *ppszApplication,
  _Out_opt_  PWSTR *ppszCommandLine,
  _Out_opt_  PWSTR *ppszParameters
);

Parameters

pszCmdTemplate [in]

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.

ppszApplication [out]

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.

ppszCommandLine [out, optional]

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.

ppszParameters [out, optional]

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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Shellapi.h

DLL

Shell32.dll

 

 

Community Additions

ADD
Show:
© 2014 Microsoft