IVsCommandWindow.PrepareCommand Method

  • Reference

Definition

Namespace:
Microsoft.VisualStudio.Shell.Interop
Assembly:
Microsoft.VisualStudio.Shell.Interop.dll
Assembly:
Microsoft.VisualStudio.Interop.dll
Package:
Microsoft.VisualStudio.Interop v17.11.40262

Performs all the steps to prepare to execute a command-line command.

public:
 int PrepareCommand(System::String ^ szCommand, [Runtime::InteropServices::Out] Guid % pguidCmdGroup, [Runtime::InteropServices::Out] System::UInt32 % pdwCmdID, [Runtime::InteropServices::Out] IntPtr % ppvaCmdArg, cli::array <Microsoft::VisualStudio::Shell::Interop::PREPARECOMMANDRESULT> ^ pResult);
public int PrepareCommand (string szCommand, out Guid pguidCmdGroup, out uint pdwCmdID, out IntPtr ppvaCmdArg, Microsoft.VisualStudio.Shell.Interop.PREPARECOMMANDRESULT[] pResult);
abstract member PrepareCommand : string * Guid * uint32 * nativeint * Microsoft.VisualStudio.Shell.Interop.PREPARECOMMANDRESULT[] -> int
Public Function PrepareCommand (szCommand As String, ByRef pguidCmdGroup As Guid, ByRef pdwCmdID As UInteger, ByRef ppvaCmdArg As IntPtr, pResult As PREPARECOMMANDRESULT()) As Integer

Parameters

szCommand
String

[in] String containing the command.

pguidCmdGroup
Guid

[out] Pointer to the GUID of the command's group.

pdwCmdID
UInt32

[out] Pointer to the identifier of the command.

ppvaCmdArg
IntPtr

nativeint

[out] A pointer to a VARIANT array containing the command arguments.

pResult
PREPARECOMMANDRESULT[]

[out] A pointer to a PREPARECOMMANDRESULT structure containing additional error information.

Returns

Int32

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

The method performs the following steps:

  1. Parses the command string.

  2. Looks up the command.

  3. Verifies the command is enabled.

  4. Determines whether it accepts parameters.

  5. Prepares a VARIANT containing the parameters and a structure to receive the command results.

Upon return, the caller has all the information needed to call the Exec method of the IOleCommandTarget interface.

COM Signature

From vsshell.idl:

HRESULT IVsCommandWindow::PrepareCommand(  
   [in, ref] LPCOLESTR szCommand,   
   [out] GUID* pguidCmdGroup,   
   [out] DWORD* pdwCmdId,   
   [out] VARIANT** ppvaCmdArg,   
   [out, retval] PREPARECOMMANDRESULT* pResult  
);

Notes for Implementers

On failure, PrepareCommand returns E_FAIL and sets pResult to a value of type PREPARECOMMANDRESULT indicating the nature of the failure. This enables the caller to customize the reporting of various errors. Also on failure the thread error information is set with a meaningful string.

The caller is responsible for the VARIANT argument ppvaCmdArg. To free it, the caller must first call VariantClear to clear the contents, and then call CoTaskMemFree to free the VARIANT itself.

Applies to