IVsExternalFilesManager.TransferDocument Method

Article
05/06/2010

Transfers a document to the Miscellaneous Files project.

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

Syntax

'Déclaration
Function TransferDocument ( _
    pszMkDocumentOld As String, _
    pszMkDocumentNew As String, _
    punkWindowFrame As IVsWindowFrame _
) As Integer
'Utilisation
Dim instance As IVsExternalFilesManager
Dim pszMkDocumentOld As String
Dim pszMkDocumentNew As String
Dim punkWindowFrame As IVsWindowFrame
Dim returnValue As Integer

returnValue = instance.TransferDocument(pszMkDocumentOld, _
    pszMkDocumentNew, punkWindowFrame)

int TransferDocument(
    string pszMkDocumentOld,
    string pszMkDocumentNew,
    IVsWindowFrame punkWindowFrame
)

int TransferDocument(
    [InAttribute] String^ pszMkDocumentOld, 
    [InAttribute] String^ pszMkDocumentNew, 
    [InAttribute] IVsWindowFrame^ punkWindowFrame
)

abstract TransferDocument : 
        pszMkDocumentOld:string * 
        pszMkDocumentNew:string * 
        punkWindowFrame:IVsWindowFrame -> int

function TransferDocument(
    pszMkDocumentOld : String, 
    pszMkDocumentNew : String, 
    punkWindowFrame : IVsWindowFrame
) : int

Parameters

pszMkDocumentOld
Type: System.String
[in] Specifies the original path to the file to be transferred.

pszMkDocumentNew
Type: System.String
[in] Specifies the new path to the file.

punkWindowFrame
Type: Microsoft.VisualStudio.Shell.Interop.IVsWindowFrame
[in] Specifies the pointer to the open window for the file.

Return Value

Type: System.Int32
If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsExternalFilesManager::TransferDocument(
   [in] LPCOLESTR pszMkDocumentOld,
   [in] LPCOLESTR pszMkDocumentNew,
   [in] IVsWindowFrame *punkWindowFrame
);

This is the implementation of the Open External File command on the system File menu. If no project can service this file and the Miscellaneous Files (External Files) project is not already present, the environment creates the Miscellaneous Files project and tries again.

In the environment, the Miscellaneous Files project is implemented using the external files manager (IVsExternalFilesManager). This interface allows you to manipulate the Miscellaneous Files project.

If you have a World Wide Web project, then the definition of your project system is tightly bound to the fact that your Web pages reside in a specific directory mimicking the hierarchy of the Web site. If your project has a file open from the Web and the user chooses to do a Save As on that file to save it to a floppy disk, then that file can no longer be considered a file that belongs to the Web site because it does not live in the directory of the Web site. The environment's model of Save As is that the open editor tracks the file in its new location. That is, the editor continues editing the new file in its new location and the old file remains unchanged in the original location and is no longer open. Because the new file is no longer a member of the Web site project, the project system hands the open editor to the Miscellaneous Files project.

To complete this transfer, the hierarchy/itemID owner of the project (in this example, the Web project) calls Query Service for SID_SVsExternalFilesManager to receive a pointer to IVsExternalFilesManager. The project then calls TransferDocument passing in the old document moniker (pszMkDocumentString) for the document when it was in the Web project. This moniker could be a URL, http:// or UNC path and is the key to the original file in the running document table (RDT). It also passes the new pszMkDocumentString and the new open window frame pointer. The Miscellaneous Files project then transfers the file to its project, allocates a new item ID for it, and then updates the RDT by calling RenameDocument. Window frames and different entities that listen for RDT events then know to update their references to the document.

.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