IVsQueryEditQuerySave2.QueryEditFiles Method

Article
04/29/2015

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

rgfQueryEdit
Type: UInt32

[in] Set of flag values taken from the tagVSQueryEditFlags enumeration. Default is 0.

cFiles
Type: Int32

[in] Count of files.

rgpszMkDocuments
Type: array<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<UInt32[]

[in] An array of flag values taken from the tagVSQEQSFlags enumeration. NULL implies that they are all 0.

rgFileInfo
Type: array<Microsoft.VisualStudio.Shell.Interop.VSQEQS_FILE_ATTRIBUTE_DATA[]

[in] Values taken from the VSQEQS_FILE_ATTRIBUTE_DATA structure containing information about the file attributes. This can be nulla null reference (Nothing in Visual Basic); it is ignored if rgrgf is nulla null reference (Nothing in Visual Basic).

pfEditVerdict
Type: UInt32%

[out] Values taken from the tagVSQueryEditResult enumeration indicating whether editing can continue.

prgfMoreInfo
Type: UInt32%

[out] Pointer to a set of flags whose values are taken from the tagVSQueryEditResultFlags enumeration.

Return Value

Type: 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

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.

Partager via