IVsCommandWindow.PrepareCommand Method

Article
10/26/2012

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

Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop (in Microsoft.VisualStudio.Shell.Interop.dll)

Syntax

'Declaration
Function PrepareCommand ( _
    szCommand As String, _
    <OutAttribute> ByRef pguidCmdGroup As Guid, _
    <OutAttribute> ByRef pdwCmdID As UInteger, _
    <OutAttribute> ByRef ppvaCmdArg As IntPtr, _
    <OutAttribute> pResult As PREPARECOMMANDRESULT() _
) As Integer

'Usage
Dim instance As IVsCommandWindow 
Dim szCommand As String 
Dim pguidCmdGroup As Guid 
Dim pdwCmdID As UInteger 
Dim ppvaCmdArg As IntPtr 
Dim pResult As PREPARECOMMANDRESULT()
Dim returnValue As Integer 

returnValue = instance.PrepareCommand(szCommand, _
    pguidCmdGroup, pdwCmdID, ppvaCmdArg, _
    pResult)

int PrepareCommand(
    string szCommand,
    out Guid pguidCmdGroup,
    out uint pdwCmdID,
    out IntPtr ppvaCmdArg,
    PREPARECOMMANDRESULT[] pResult
)

int PrepareCommand(
    [InAttribute] String^ szCommand, 
    [OutAttribute] Guid% pguidCmdGroup, 
    [OutAttribute] unsigned int% pdwCmdID, 
    [OutAttribute] IntPtr% ppvaCmdArg, 
    [OutAttribute] array<PREPARECOMMANDRESULT>^ pResult
)

function PrepareCommand(
    szCommand : String, 
    pguidCmdGroup : Guid, 
    pdwCmdID : uint, 
    ppvaCmdArg : IntPtr, 
    pResult : PREPARECOMMANDRESULT[]
) : int

Parameters

szCommand
Type: System.String

[in] String containing the command.

pguidCmdGroup
Type: System.Guid%

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

pdwCmdID
Type: System.UInt32%

[out] Pointer to the identifier of the command.

ppvaCmdArg
Type: System.IntPtr%

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

pResult
Type: array<Microsoft.VisualStudio.Shell.Interop.PREPARECOMMANDRESULT[]

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

Return Value

Type: System.Int32
If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

The method performs the following steps:

Parses the command string.
Looks up the command.
Verifies the command is enabled.
Determines whether it accepts parameters.
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.

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Share via