Udostępnij za pośrednictwem

IVsQueryEditQuerySave2.QueryEditFiles Method

  • Artykuł

Called when a file is about to be edited.

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

Syntax

'Declaration
Function QueryEditFiles ( _
    rgfQueryEdit As UInteger, _
    cFiles As Integer, _
    rgpszMkDocuments As String(), _
    rgrgf As UInteger(), _
    rgFileInfo As VSQEQS_FILE_ATTRIBUTE_DATA(), _
    <OutAttribute> ByRef pfEditVerdict As UInteger, _
    <OutAttribute> ByRef prgfMoreInfo As UInteger _
) As Integer

int QueryEditFiles(
    uint rgfQueryEdit,
    int cFiles,
    string[] rgpszMkDocuments,
    uint[] rgrgf,
    VSQEQS_FILE_ATTRIBUTE_DATA[] rgFileInfo,
    out uint pfEditVerdict,
    out uint prgfMoreInfo
)

int QueryEditFiles(
    [InAttribute] unsigned int rgfQueryEdit, 
    [InAttribute] int cFiles, 
    [InAttribute] array<String^>^ rgpszMkDocuments, 
    [InAttribute] array<unsigned int>^ rgrgf, 
    [InAttribute] array<VSQEQS_FILE_ATTRIBUTE_DATA>^ rgFileInfo, 
    [OutAttribute] unsigned int% pfEditVerdict, 
    [OutAttribute] unsigned int% prgfMoreInfo
)

abstract QueryEditFiles : 
        rgfQueryEdit:uint32 * 
        cFiles:int * 
        rgpszMkDocuments:string[] * 
        rgrgf:uint32[] * 
        rgFileInfo:VSQEQS_FILE_ATTRIBUTE_DATA[] * 
        pfEditVerdict:uint32 byref * 
        prgfMoreInfo:uint32 byref -> int 

function QueryEditFiles(
    rgfQueryEdit : uint, 
    cFiles : int, 
    rgpszMkDocuments : String[], 
    rgrgf : uint[], 
    rgFileInfo : VSQEQS_FILE_ATTRIBUTE_DATA[], 
    pfEditVerdict : uint, 
    prgfMoreInfo : uint
) : int

Parameters

  • rgpszMkDocuments
    Type: array<System.String[]
    [in] File to be processed. This is the same size as cFiles. It is not valid for cFiles to be 0.
  • rgrgf
    Type: array<System.UInt32[]
    [in] An array of flag values taken from the tagVSQEQSFlags enumeration. NULL implies that they are all 0.

Return Value

Type: System.Int32

If the method succeeds, it returns S_OK. If it fails, it returns an error code.
The return value in pfEditCanceled indicates whether it is OK for editing of the file to continue.
The parameter prgfMoreInfo returns the following results:

  • Whether any files are checked out

  • Whether any files changed on checkout

  • Whether any files are being edited in memory

  • Whether in-memory edit is not allowed

  • Whether noisy checkout is required (in silent mode only)

  • Whether checkout has been canceled or has failed

Remarks

COM Signature

From ivsqueryeditquerysave2.idl

HRESULT QueryEditFiles(
   [in] VSQueryEditFlags rgfQueryEdit,
   [in] int cFiles,
   [in, size_is(cFiles)] const LPCOLESTR rgpszMkDocuments[],
   [in, size_is(cFiles)] const VSQEQSFlags rgrgf[],
   [in, size_is(cFiles)] const VSQEQS_FILE_ATTRIBUTE_DATA rgFileInfo[],
   [out] VSQueryEditResult *pfEditVerdict,
   [out] VSQueryEditResultFlags *prgfMoreInfo
);

Editors, defined as anything that can change the contents of a project file, should call this method before the first edit in a document that has not yet been changed. Anything that edits the contents of the solution (.sln) file can call QueryEditSolutionFile, which will call this method.

  • If a file is not read-only and not under source control, QER_EditOK is returned.

  • If a file is read-only, if it is not under source control, and if rgfQueryEdit does not include QEF_AllowInMemoryEdits (or the Options dialog box is set to disallow the editing of read-only files), then QER_NoEdit_UserCanceled is quietly returned and the edit should not be committed to the in-memory document data. If the environment is in noisy mode, it will prompt the user that the edit is cancelled.

  • If a file is read-only, if it is not under source control, and if rgfQueryEdit includes QEF_AllowInMemoryEdits (or the Options dialog box is set to allow in-memory edits), then QER_EditOK is quietly returned.

  • If a file is read-only and under source control, the user is given the choice whether or not to check out the file. If the file is checked out, QER_EditOK is returned; otherwise, QER_NoEdit_UserCanceled is returned. This case is a little more complicated if the environment does not support the "checkout local version" option (and taking into account reloadability), if the user has the latest version of the file already, and if in-memory editing is allowed (that is, QEF_AllowInMemoryEdits). In most cases, however, in-memory edits of checked-in files are not possible.

Editors, Reloadability, and Checkout

When you call QueryEditFiles, there is always the potential of a file being checked out, which in turn can change the file contents in memory and on disk.

Because of the potential of changed contents, all VSPackages making file changes should call QueryEditFiles at the first attempt to change the file's contents, before changes are actually made to the file. If a VSPackage does not call QueryEditFiles first, and changes have already been made to the file in memory, those in-memory changes could be lost as a result of the file being checked out. This is considered a bug in the VSPackage.

The information about whether a file has been changed is returned in the *prgfMoreInfo return value via the QER_Reloaded or QER_Changed flags.

Important

QER_Changed is only returned if QEF_DetectAnyChangedFile flag is passed in the rgfQueryEdit argument to the QueryEditFiles call.

If a file is in the Running Documents Table, and QueryEditFiles determines that a reload will be required, it will attempt to reload the file contents. If it cannot reload its data, it displays a message box advising the user to manually close and reopen the document. If you are implementing a custom editor, see IVsPersistDocData for information on how to support reloads on your documents.

Project Files

It is up to each project to call QueryEditFiles when a change is about to be made to information that is persisted in a project file and to call QuerySaveFile or QuerySaveFiles before saving the project file.

.NET Framework Security

See Also

Reference

IVsQueryEditQuerySave2 Interface

Microsoft.VisualStudio.Shell.Interop Namespace