Export (0) Print
Expand All

IVsQueryEditQuerySave2.QueryEditFiles Method

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)

int QueryEditFiles (
	[InAttribute] uint rgfQueryEdit,
	[InAttribute] int cFiles,
	[InAttribute] string[] rgpszMkDocuments,
	[InAttribute] uint[] rgrgf,
	[InAttribute] VSQEQS_FILE_ATTRIBUTE_DATA[] rgFileInfo,
	out uint pfEditVerdict,
	out uint prgfMoreInfo
)
int QueryEditFiles (
	/** @attribute InAttribute() */ UInt32 rgfQueryEdit, 
	/** @attribute InAttribute() */ int cFiles, 
	/** @attribute InAttribute() */ String[] rgpszMkDocuments, 
	/** @attribute InAttribute() */ UInt32[] rgrgf, 
	/** @attribute InAttribute() */ VSQEQS_FILE_ATTRIBUTE_DATA[] rgFileInfo, 
	/** @attribute OutAttribute() */ /** @ref */ UInt32 pfEditVerdict, 
	/** @attribute OutAttribute() */ /** @ref */ UInt32 prgfMoreInfo
)
JScript does not support passing value-type arguments by reference.

Parameters

rgfQueryEdit

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

cFiles

[in] Count of files.

rgpszMkDocuments

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

rgrgf

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

rgFileInfo

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

pfEditVerdict

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

prgfMoreInfo

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

Return Value

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

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.

NoteImportant

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.

Community Additions

ADD
Show:
© 2014 Microsoft