Share via


IVsCommandWindow.PrepareCommand Method

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.

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:

  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.

.NET Framework Security

See Also

Reference

IVsCommandWindow Interface

IVsCommandWindow Members

Microsoft.VisualStudio.Shell.Interop Namespace