The name of the API is IFileIsInUse, an interface. It resides in Shobjidl.h, Shobjidl.idl and newly in JwaShlObj.pas. This is the translation:

{$IFDEF WINVISTA_UP}
const
  IID_IFileIsInUse: TGUID = (
    D1:$64a1cbf0; D2:$3a1a; D3:$4461; D4:($91,$58,$37,$69,$69,$69,$39,$50));

type
  {$ALIGN 4}
  tagFILE_USAGE_TYPE = (
    FUT_PLAYING = 0,
    FUT_EDITING = 1,
    FUT_GENERIC = 2
  );
  FILE_USAGE_TYPE = tagFILE_USAGE_TYPE;
  TFileUsageType = FILE_USAGE_TYPE;

const
  OF_CAP_CANSWITCHTO     = $0001;
  OF_CAP_CANCLOSE        = $0002;

type
  IFileIsInUse = interface(IUnknown)
    ['{64a1cbf0-3a1a-4461-9158-376969693950}']
    function GetAppName(out ppszName: LPWSTR) : HRESULT; stdcall;
    function GetUsage(out pfut : FILE_USAGE_TYPE) : HRESULT; stdcall;
    function GetCapabilities(out pdwCapFlags : DWORD) : HRESULT; stdcall;
    function GetSwitchToHWND(out phwnd : HWND) : HRESULT; stdcall;
    function CloseFile() : HRESULT; stdcall;
  end;

{$ENDIF WINVISTA_UP}

The interface can be used as a client and also can be implemented by a server. A client usually checks if a file has a lock and retrieves a pointer to this interface to access the methods. A server usually holds a lock on a given file and implements the interface to provide the methods to the client. This article will discuss only the client side.
You see that this API only works if both sides do their jobs. A process that locks a file must also implement this interface and register it, so a client can receive a status information. There is no direct link between a file lock and the process name. If a process holds a lock on a file but does not implement the interface you are on your own again. 
Eventually, this is only a shell helper for the nice Windows Explorer deletion dialog.

  IFileIsInUse = interface(IUnknown)
    function GetAppName(out ppszName: LPWSTR) : HRESULT; stdcall;
    function GetUsage(out pfut : FILE_USAGE_TYPE) : HRESULT; stdcall;
    function GetCapabilities(out pdwCapFlags : DWORD) : HRESULT; stdcall;
    function GetSwitchToHWND(out phwnd : HWND) : HRESULT; stdcall;
    function CloseFile() : HRESULT; stdcall;
  end;

The methods of the interface are really easy to understand.

• GetAppName retrieves the name of the process that holds the file. It can be any chosen name by the application designer. To get the name use always a PWideChar and don’t forget to free it with CoTaskMemFree (it uses the interface IMalloc). Don’t forget to check for the result. If you like exception you can also rewrite the code using safecall (convert the function to a procedure then).
• GetUsage returns the reason why the file is locked. It can be one of the enumeration constant of  TFileUsage. Either it can be playing a video or music or editing a file. If these are not sufficient the value FUT_GENERIC must be used. Maybe there will be more values in future.
• GetCapabilities returns a set of flags in a DWORD. They define whether the file can be closed (OF_CAP_CANCLOSE) by calling CloseFile or the we can put the application into foreground (OF_CAP_CANSWITCHTO). Be aware that you should inform the user that you are about to switch the window. Otherwise she could get nervous about her missing application window. Switching the window can be done by SetForegroundWindow. But your application must have a focus (and some other rules, see MSDN SetForegroundWindow) to switch the window; otherwise nothing happens.
• GetSwitchToHWND returns a window handle of the other process. Only use this handle to switch to the window. You don’t really know what window is returned here. Don’t try to close it or anything else because this is just bad behaviour. At all costs, check the return value. Otherwise you don’t know whether the returned window handle is valid or just an random number. In worst case it is an existing window from your process. Well, COM rules tell us to nullify the out parameters but usually it is better to check.
  Of course, the call is only valid if GetCapabilities returns the bit OF_CAP_CANSWITCHTO.
• CloseFile implements the server side of closing the file. The call is only valid if GetCapabilities returns the bit OF_CAP_CANCLOSE. Well, this is really nice. However, don’t trust it! Always recheck the lock on the file instead of continuing blindly.

To retrieve an interface on the file you have to lock it first. Either you download and compile the MSDN example IsFileInUse or you open up an application that implements the interface (e.g. a PDF Reader, MS Office).

The next step is to know where the locked files are placed. The location is the running object table, short ROT (ActiveX.GetRunningObjectTable() retrieves it). It is a global* (on machine) table that holds running COM objects. You can implement your own interfaces and put it in this table. Because interfaces can be arbitrary in its structure and reason to be,  they are attached to monikers (IMoniker) which describe them uniquely. There are several types of monikers like class, item and file moniker (more information provides IMoniker in MSDN). We are interested in the latter only.
So the whole work is an enumeration over all monikers in the ROT.  Usually there are not that much in there (I got 5 here). Each moniker is checked for its type (IsSystemMoniker) and if it is a file moniker (MKSYS_FILEMONIKER) the path is compared to the input parameter FileName. Honestly, I cannot tell why there is a comparison of the prefix at first followed by a comparison of the moniker itself, sorry. 
The object itself is retrieved from the moniker by GetObject. It may fail with E_ACCESS_DENIED so a check is done using Succeeded. In the end, we can try to retrieve the IFileIsInUse interface. There may be such a file registered but without the implementation of the interface, thus an additional check.

I didn’t create this whole source by myself. In fact, there is a FileIsInUse example in MSDN that is the base of this article. The original source is located in the docx file in the download. The example FileIsInUse will create a server.

function GetFileInUseInfo(const FileName : WideString) : IFileIsInUse;
var
  ROT : IRunningObjectTable;
  mFile, enumIndex, Prefix : IMoniker;
  enumMoniker : IEnumMoniker;
  MonikerType : LongInt;
  unkInt  : IInterface;
begin
  result := nil;

  OleCheck(GetRunningObjectTable(0, ROT));
  OleCheck(CreateFileMoniker(PWideChar(FileName), mFile));

  OleCheck(ROT.EnumRunning(enumMoniker));

  while (enumMoniker.Next(1, enumIndex, nil) = S_OK) do
  begin
    OleCheck(enumIndex.IsSystemMoniker(MonikerType));
    if MonikerType = MKSYS_FILEMONIKER then
    begin
      if Succeeded(mFile.CommonPrefixWith(enumIndex, Prefix)) and
         (mFile.IsEqual(Prefix) = S_OK) then
      begin
       if Succeeded(ROT.GetObject(enumIndex, unkInt)) then
        begin
          if Succeeded(unkInt.QueryInterface(IID_IFileIsInUse, result)) then
          begin
            result := unkInt as IFileIsInUse;
            exit;
          end;
        end;
      end;
    end;
  end;
end;

Conclusion

This whole API has some caveats

• This API relies on a server that registers an interface in the ROT honestly. If an application doesn’t do the effort, you will be unable to aquire the name of it.
• If you lock a file on a shared folder and you want to access the very same file on the local file system, you cannot determine the process if you access the shared folder from localhost. The reason is Windows itself. Windows is the provider of the file to the outer world (even if it is a loopback) so Windows Explorer shows “System” as origin. In the ROT you will see the the UNC path instead of the local file system path. Thus the comparison and our function will fail.
• *Security: A ROT is not really global. In fact, there are several ROTs in the system. ROTs are divided by a user and then the mandatory integrity control (MIC) or integrity levels (IL) high, medium and propably low (didn’t check). If you run as a user, your processes get an medium level and as an Administrator you’ll get an high integrity level. A server that runs with an medium integrity level will only be allowed to register itself into the medium ROT. So it must be started at least once as Administrator to be allowed to create some Registry keys for COM (LOCAL_MACHINE\Classes\AppID\guid). In this way it will be available in all ROTs if it wants. Unfortunately, this is not the end. On a multi user system, every object in a moniker has a security descriptor that tells COM who is allowed to access it. If Alice wants to access an object in the ROT that was created by Bob, Bob has to explicitily grant Alice access to it. By default the security, which allow access to SYSTEM, Administrators and the creator, is copied from the global COM security settings and can be changed either in the registry for an AppID, at process startup or for each registered object by the server. JWSCL provides all of them in JwsclComSecurity.pas (only Subversion trunk and >= 0.9.4). In this way a server can change the settings to, say, allow all authenticated users access to the object.

Downloads

You can download the example file from the Subversion directly.

https://jedi-apilib.svn.sourceforge.net/svnroot/jedi-apilib/jwapi/trunk/Examples/FileIsInUse/Client/FileIsInUseClientExample.dpr

Sequel

The next article discusses the the implementation if the interface IFileIsInUse.

The ACTRL_ACCESS structure is used by the interface method IAccessControl::GetAllAccessRights (and others) which is rather hard to implement yourself because the structure must be created in a single block of memory that can be freed by CoTaskMemFree.

So here is how it looks like

ACTRL_ACCESS design diagram

Luckily, JWSCL will provide an implementation of IAccessControl so don’t worry.

You can prevent this dialog box by setting the property UIInteractive of TComServer to true. The COM Server instance is defined in unit ComServ by the instance variable ComServer. It also sets ObjectCount which defines the remaining client COM connections. The dialog pops up if this value is greater than zero. In this way you can easily check yourself the whole circumstance and show a dialog yourself if you need it.

Consider what happens if a dialog box appears in your service app. I did some tests in Windows Vista and found out that the dialog box prevented the service process to be terminated although the service shuts down correctly. So I just set UIInteractive to false and it worked fine.

Remember: If a service must be shut down it should do it as fast as possible.

You can get your personal properties by using the Windows Address Book Editor. It can be opened using “wab” in command line.

At first you see your personal “Contacts” folder. This folder contains your personal contact file. Its extension is “.contact”. A double click on it opens the Address editor as seen below:

“Web.exe” can also receive any personal contact file to import it to your personal contacts.

The contact file contains a formatted text in xml syntax. Data is arranged in a tree that is used to retrieve values. When I am writing of a path, I iterate through the tree. Some of the elements contains a collection of the same element type. The reason comes from the fact, that several other contacts can be added to the personal contact. The WC API uses the array brackets to access different contact values.

The following sample path shows you how to obtain the first user’s name.(Notice that the array starts with one not zero.)

NameCollection/Name[1]/GivenName

XML (manually formatted):

This parts can be cut into three parts:

1. NameCollection defines a container for the array
2. /Name defines an array which contains all contacts
3. GivenName defines a name property of exact one contact.

There are also Value tags:

ContactIDCollection/ContactID[1]/Value

XML (manually formatted):

This path returns the GUID of contact number one.

Many parts of a path are already defined as constants. Have a look at them in MSDN.

So how can we read from the personal contact file? Since new API uses COM, we will use the following interfaces

• IContact
• IContactCollection
• IContactManager
• IContactProperties
• IContactPropertyCollection

Actually there is no implementation of these interfaces for Delphi. To create your own type library (TLB) do the following steps (in Vista of course):

1. Get Visual Studio 200x
2. Download and install the latest version Windows SDK for Vista for MIDL and IContact.IDL.
3. Open the Visual Studio Command Prompt (in VS open menu Tools). We need the predefined include path settings.
4. Add path of midl.exe from the Windows SDK to your path environment. Use this command:
   set path=%path%;<your path here>\Microsoft SDKs\Windows\v6.0\Bin
5. Change folder to ;<your path here>\Microsoft SDKs\Windows\v6.0\Include
6. Backup and open IContact.idl in your favorite text editor.
   Find these lines…
   interface IContactPropertyCollection;
   interface IContactCollection;

   …and add :

   interface IContactProperties;
   interface IContactPropertyCollection;

   Additionally find this method…

   HRESULT CommitChanges([in] DWORD dwCommitFlags);

   …and also add :

   HRESULT _DO_NOT_USE1([in] IContactProperties* pC);
   HRESULT _DO_NOT_USE2([in] IContactPropertyCollection* pC);

   In this way midl.exe will also create interfaces in the typelibrary for IContactProperties and IContactPropertyCollection.
   I could not figure out how to do it in another way. Comments are apreciated.

7. You should also find all appearances of…
   procedure Next; safecall;

   …and replace them by:

   function Next : HRESULT; stdcall;

   It is necessary because we need to check for a positive return value (S_FALSE). Delphi does not raise an EOleSysError exception for positive values.

8. Save your work and start the conversion:
   midl icontact.idl /tlb icontact.tlb
9. The new tlb file can now be imported using Delphi. To do so, start Delphi as Administrator, open menu “Components” and select “Install components” and hit the next button until all the components are listed. Click button “add” and choose the newly created IContact.tlb. Delphi imports the library and also generates the Delphi type library source code.

Did you know?

You can also (un)register a TLB file using regtlib.exe from C:\Windows\System32\URTTEMP
Type “regtlib Icontact.tlb” to register the library and “regtlib /u IContact.tlb” to unregister it.

You can find an already generated type library and and Delphi source code at the end of this article.

Using the Windows Contact API is really easy as soon as the Delphi type library unit exists. It implements class factories for IContact and IContactManager. Use the IContact class factory if you want to add your own contacts to the user’s personal database. If you just want to read data you have to use IContactManager.
Retrieving the current user’s profile is simple:

These lines creates an empty contact manager. Notice that the method Initialize is necessary for further calls.
Now we have to actually open the current user’s contact database.

The new interface Contact contains all the user’s personal data. We can obtain it through a path value as shown in the beginning of this article.
Let us obtain the user’s name. This task is done by retrieving the property interface IContactProperties using the Contact instance.

The new instance ContactProp allows us to access a property through a path.

The variable Name will contain the user’s name. In this way we make sure that the right amount of memory is allocated. Notice that the GetString actually returns the count of chars and not the count of bytes, so we have to double the size. We always get an exception in GetString because Delphi wraps (safecall convetion) the method and automatically raises an exception if the function returns a negative value (E_XXX code). We don’t distinguish between a memory error which we need to check for the correct size and a real error. So let us implement it in the right way:

In this way all “real” errors are catched and reraised.

All the other properties can be obtained in similar ways. However what properties are available at all? The interface IContactPropertyCollection allows us to obtain all available property names and types. IContactProperties implements a method GetPropertyCollection which returns a pointer to a IContactPropertyCollection that contains the requested properties. It is also possible to filter some of them.

The new property collection contains an enumeration method to iterating all available properties. Be aware that you must call Next before you start getting data.

In this way we can obtain name, type , version, modification time and ID of a property. Just use the available methods of IContactPropertyCollection.

• GetPropertyName
• GetPropertyType
• GetPropertyVersion
• GetPropertyModificationDate
• GetPropertyArrayElementID

We already coded how to get a string using COM methods. So this code isn’t new to you. It retrieves the name of the property.

To make life easier I created a unit that implements the shown code. You can download ContactMisc.pas in the download section of this article. The unit implements the following functions:

Some hints in the end

• The Windows Contacts API does not allow to open foreign contact profiles. Although IContactManager implements the method Load, it is useless. Every contact file may contain several contacts. However only one contact belongs to the user. The method Loads expects a contact file name and the user’s ID (GUID) . /GUID:”xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx” /PATH:”……..\xy.contact”
  You cannot retrieve the GUID of a foreign user with the WC API. To do so, you had to parse the contact file manually.
• So how does
  ContactManager.GetMeContact(Contact);

  retrieve the user’s ID?
  The ID is stored in the registry. Look at …
  HKEY_CURRENT_USER\Software\Microsoft\WAB\Me
  …and you’ll find the a string that is necessary for the Load method of IContactManager.

• The WC API is sensible to the current token. A service may use an impersonated thread to get a foreign user contact.

Download:

Download the package here. It contains:

• IContact.tlb – type library
• Contact_tlb.pas – delphi type library header
• ContactMisc.pas – IContact tools
• Contacts.dpr – small demonstration

… I get my dialog and all runs well – *except* I’ve lost theming
on this particular dialog. This means the application’s main windows shows
up correctly themed, the progress dialog does not. I’ve already added the
XP manifest to the progress dialog, too, but to no avail so far.

A theme is only applied if an EXE or DLL file has a manifest that explicitly enables theme support. If Windows cannot find this manifest, the process is only shown with the regular window design.

However the Vista elevation is done by creating a COM object and offers its methods through a seperate process. A seperate process is necessary because the same process cannot get assigned the ncessary administrator token. In our case a service in the service container svchost.exe has the task to host the COM object. The contained service is called dllhost.exe (service name: “COMSysApp”) and does not run until requested. It does not matter whether the service is deactivated or not because it is started directly by svchost.

The COM method and the dialog will run in the process space of the newly elevated dllhost.exe. And because there is no manifest information in this file you cannot get a themed dialog layout.

So how can you get a themed dialog anyhow?

The task is done by using the basic principles of COM. COM knowns Callback interfaces and other stuff. By using a Callback interface you can turn around the server – client principle.

1. Define a well known interface that is implemented by the client only. But also known to the server.
2. Add a parameter to your elevated COM method that receives a pointer to this interface.
3. Before calling an elevated method, create the interface and
4. apply a pointer to the method’s parameter you added.
5. Call the method and use the methods in the given callback interface. COM will automatically transfer the method calls to your non-elevated process. In this way you can create themed windows, do window management stuff (progress bar) and eventually close the window.

If you prefer to read code instead of text you should study this code excerpts.

Define a callback interface for your client and add it to the server’s TypeLib. Delphi will generate code for it automatically in a file called <Name>_TLB.pas (TLB Header). Do not create the interface by using the Delphi’s ActiveX expert. Just add it manually.

IMyCallback interface is known to both the server and the client, because we use the TLB Header in the client and the server. The client will implement and the server will receive a pointer to it and then call the included method ACallBackMethod everytime it wishes to do so.

The server implements a method to allow a callback interface to be passed to it.

Of course you have to implement both interfaces: IServerInt and IMyCallback. However IServerInt is implemented on server side and IMyCallback is only implemented on the client side.

On client side (namely your application) write..

Install the COM object anywhere before you’re going to use it.

After all implement the callback method…

…and anywhere you like, call the method to use our Callback interface.

I’m using TComObject and TComObjectFactory on the client side , because this way works for console applications, too. If you need the possibilities of TAutoIntfObject, you will have to write a standalone COM server with TApplication. However this is not necessary here. The method ACallBackMethod will be run in the client’s process space rather than the elevated helper process. You can check whether the callback method runs in the correct process (elevated or not?) with the following code.

Second way, still on the client side:
If you already have a form class, you can add the interface to it.

Instead of creating the COM object, you pass a self-pointer to the method parameter.

Be aware that in a multi thread environment, you have to make sure that resources in that specific form are accessed only by one thread at a time.

Eventually the server side calls the methods within the callback interface:

The callback method will be called in the context of the client. So it will not be elevated. This is because there is no ordinary method call here. COM will pack the function stack and all its parameter into a stream, send it to the client, unpack it and restore a proper function stack to be executed. This happens in the client process of course.
Get more information about COM callbacks here.

If you start the program without any parameter, you’ll get the help screen.

RunEl V1.0 – Run application elevated
by Christian Wimmer @ 2008
Visit us at http://blog.delphi-jedi.net

RunEl [/INSTALL][/UNINSTALL][/W[D][G]] [AppName] [Parameters]

Parameters:
/INSTALL – installs the RunElCOM.dll. Needed for parameter /D
RunElCOM.dll must be in the same folder as RunEl.
/UNINSTALL – uninstalls the RunElCOM.dll.
W – Wait for called process to be finished.
D – uses own elevation COM Class. Before using must be setup with /INSTALL .
G – uses foreground window to display UAC Prompt on.
Parameters W, D and G must be mixed up with only one “/”

Despite the INSTALL parameter, you do not have to install the program! I implemented two different ways to elevate an application. There is on the one side ShellExecute, which can elevate an application by passing “runas” as a parameter. On the other hand, I implemented the usual way by registering a COM DLL. In the last case, you have to register the DLL first. We get back there later.

Let’s see how we can use it. Open a command line window and type:

RunEl cmd

This command starts the Windows command line interpreter as an Administrator. You get the UAC prompt, allow the action and a new cmd window is opened. If you disallow the action, RunEl will return an error value through its process return value. This us useful if you want to check the errorlevel in a batch file.

Elevation failed. (2147943623) The operation was canceled by the user.

If you need to wait for the process to be closed, you can add the wait parameter. This is also mandatory if you want to check your application’s return value. Because it is clear that we have to wait until the process’ end to get the return value.

RunEl /w cmd

Sometimes the UAC prompt does not appear and just blinks in the task to get attention. This is because there is no available window. In this case you can specify parameter “g”, which uses the foreground window. The UAC prompt will appear again then.

RunEl /g cmd

Of course you can also combine both parameters. However there must only be one slash.
All these combinations are the same, so it ignores the case-sensitivity and the order of the three options letters.

RunEl /wg cmd
RunEl /gw cmd
RunEl /Gw cmd
RunEl /GW cmd

The last parameter “d” takes the usual way to get elevated privileges. It runs a COM method as the elevated user, creates the process, returns to non-elevated status and then eventually waits for the process or returns immediately.
However you have to install the provided DLL RunElCOM.dll at first. This is done by using RunEl.

RunEl /install
The COM DLL was successfully installed.

Now you are able to run applications with the “d” parameter in the nearly same way as shown above.

Run /d cmd
Run /dw cmd
Run /dwg cmd
…

I say nearly because of two issues:

1. You always have to use /d parameter. Otherwise ShellExecute is used
2. A major problem of ShellExecute is that it ignores the current directory if it is used for elevation. I circumnavigated this problem by using the following command line internally.
   

   cmd /C cd /d <current dir> & <your application> <parameters>

   The disadvantage of this solution is that you do not get the application’s return value. Cmd is the main process, so we get its return value instead of <your application>.
   If you need the correct return value directly, you have to use /d switch.

In the end you can uninstall the COM library.

runel /uninstall
The COM DLL was successfully uninstalled.

If you try to run an application using runel /d you’ll get the following error message.

RunEl /d cmd
Elevation failed. (2148007959) The class is not configured to support Elevated activation.

1. Do nothing and accept this dialog
2. Wait until I buy or get the very expensive sign certificate. I tell you that it will last a really long time.
3. Use your own certificate to sign the file

Download and Sourecode:

You get the newest version of RunEl in the JWSCL Download section of RunEl.

RunEl is also available through Subversion repository:

https://jedi-apilib.svn.sourceforge.net/svnroot/jedi-apilib/jwscl/trunk/examples/runel

You can browse the repository or download it with a Subversion client.

Please send bugs to mail@delphi-jedi.net , the mailinglist or the forum.