IFileIsInUse interface (shobjidl_core.h)

Article
07/22/2021

Exposes methods that can be called to get information on or close a file that is in use by another application. When an application attempts to access a file and finds that file already in use, it can use the methods of this interface to gather information to present to the user in a dialog box.

Inheritance

The IFileIsInUse interface inherits from the IUnknown interface. IFileIsInUse also has these types of members:

Methods

The IFileIsInUse interface has these methods.


IFileIsInUse::CloseFile Closes the file currently in use.
IFileIsInUse::GetAppName Retrieves the name of the application that is using the file.
IFileIsInUse::GetCapabilities Determines whether the file can be closed and whether the UI is capable of switching to the window of the application that is using the file.
IFileIsInUse::GetSwitchToHWND Retrieves the handle of the top-level window of the application that is using the file.
IFileIsInUse::GetUsage Gets a value that indicates how the file in use is being used.

Remarks

In versions of Windows before Windows Vista, when a user attempted to access a file that was open in another application, the user would simply receive a dialog box with a message stating that the file was already open. The message instructed that the user close the other application, but did not identify it. Other than that suggestion, the dialog box provided no user action to address the situation. This interface provides methods that can lead to a more informative dialog box from which the user can take direct action.

The Running Object Table

When an application opens a file, that application registers the file by inserting the instantiated IFileIsInUse object into the running object table (ROT). The ROT is a globally accessible lookup table that keeps track of currently running objects. These objects can be identified by a moniker. When a client attempts to bind a moniker to an object, the moniker checks the ROT to determine whether the object is already running. This allows the moniker to bind to the current instance rather than loading a new instance.

Perform these steps to add a file to the ROT:

Call the GetRunningObjectTable function to retrieve an instance of IRunningObjectTable.
Create an IFileIsInUse object for the file that is currently in use.
Create an IMoniker object for the file that is currently in use.
Insert the IFileIsInUse and IMoniker objects into the ROT by calling IRunningObjectTable::Register.

In the call to Register, specify the ROTFLAGS_ALLOWANYCLIENT flag. This allows the ROT entry to work across security boundaries. Use of this flag requires the calling application to have an explicit Application User Model ID (AppUserModelID) (System.AppUserModel.ID). An explicit AppUserModelID allows the Component Object Model (COM) to inspect the application's security settings. An attempt to call Register with ROTFLAGS_ALLOWANYCLIENT and no explicit AppUserModelID will fail. You can call Register without the ROTFLAGS_ALLOWANYCLIENT flag and the application will work correctly, but only within its own security level.

The value retrieved in the Register method's [out] parameter is used to identify the entry in later calls to retrieve or remove it from the ROT.

When to Implement

Applications that open file types that can be opened by other applications should implement IFileIsInUse. An application's implementation of this interface enables Windows Explorer to discover the source of sharing errors, which enables users to address and retry operations that fail due to those errors.

When to Use

An application calls IFileIsInUse to communicate with other applications to resolve sharing errors. These errors occur in response to user action in the file system. For example, when a user attempts to rename a folder while a file in that folder is open in an application, the renaming operation fails. Windows Explorer can call that application's implementation of IFileIsInUse to help the user identify the conflict and resolve this issue.

Sample

See the File Is in Use sample, which demonstrates how to implement IFileIsInUse and register a file with the ROT. It then shows how to customize the File In Use dialog to display additional information and options for files currently opened in an application.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	shobjidl_core.h (include Shobjidl.h)