IVsQueryEditQuerySave2.QueryEditFiles Method

Definition

Namespace:

Microsoft.VisualStudio.Shell.Interop

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

Called when a file is about to be edited.

public:
 int QueryEditFiles(System::UInt32 rgfQueryEdit, int cFiles, cli::array <System::String ^> ^ rgpszMkDocuments, cli::array <System::UInt32> ^ rgrgf, cli::array <Microsoft::VisualStudio::Shell::Interop::VSQEQS_FILE_ATTRIBUTE_DATA> ^ rgFileInfo, [Runtime::InteropServices::Out] System::UInt32 % pfEditVerdict, [Runtime::InteropServices::Out] System::UInt32 % prgfMoreInfo);

int QueryEditFiles(unsigned int rgfQueryEdit, int cFiles, std::Array <std::wstring const &> const & rgpszMkDocuments, std::Array <unsigned int> const & rgrgf, std::Array <Microsoft::VisualStudio::Shell::Interop::VSQEQS_FILE_ATTRIBUTE_DATA> const & rgFileInfo, [Runtime::InteropServices::Out] unsigned int & pfEditVerdict, [Runtime::InteropServices::Out] unsigned int & prgfMoreInfo);

public int QueryEditFiles (uint rgfQueryEdit, int cFiles, string[] rgpszMkDocuments, uint[] rgrgf, Microsoft.VisualStudio.Shell.Interop.VSQEQS_FILE_ATTRIBUTE_DATA[] rgFileInfo, out uint pfEditVerdict, out uint prgfMoreInfo);

abstract member QueryEditFiles : uint32 * int * string[] * uint32[] * Microsoft.VisualStudio.Shell.Interop.VSQEQS_FILE_ATTRIBUTE_DATA[] * uint32 * uint32 -> int

Public Function QueryEditFiles (rgfQueryEdit As UInteger, cFiles As Integer, rgpszMkDocuments As String(), rgrgf As UInteger(), rgFileInfo As VSQEQS_FILE_ATTRIBUTE_DATA(), ByRef pfEditVerdict As UInteger, ByRef prgfMoreInfo As UInteger) As Integer

Parameters

rgfQueryEdit

UInt32

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

cFiles

Int32

[in] Count of files.

rgpszMkDocuments

String[]

[in] File to be processed. This is the same size as cFiles. It is not valid for cFiles to be 0.

rgrgf

UInt32[]

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

rgFileInfo

VSQEQS_FILE_ATTRIBUTE_DATA[]

[in] Values taken from the VSQEQS_FILE_ATTRIBUTE_DATA structure containing information about the file attributes. This can be null; it is ignored if rgrgf is null.

pfEditVerdict

UInt32

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

prgfMoreInfo

UInt32

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

Returns

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 outWhether any files changed on checkoutWhether any files are being edited in memoryWhether in-memory edit is not allowedWhether 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.