More than 6000 people signed already, including me. Please sign and spread the word :

Read more about the issue and how to sign here:

http://www.fsf.org/campaigns/secure-boot-vs-restricted-boot/statement

I had a wow effect, do you?

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.

If you want to write a documentation, consider first to create an account. This will help immensely if there is a need to contact you on the subject. Of course, it is not mandatory and you don’t contact any JEDI member.

I have written a page about JWSCL. It can be improved though.

Also JCL news can be found here (although they look outdated)

The code was not posted in this exact way. I just extracted the necessary parts for your comprehension (The original source was even more a duplicate of real plain C code.):

function IsUserMemberOf(const Group : PSID) : BOOL;
 var
   hToken : HANDLE;
 begin
   result := false;
   //retrieve Token here and store in hToken ... (short version)
   if not OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY or TOKEN_DUPLICATE, hToken) then
     goto Exit;

   //additional stuff for Vista and house keeping for Windows in general and a lot of gotos   

   if not CheckTokenMembership(hToken, Group, @result) then
   begin
     goto Exit_1;
   end;

:Exit_1
  CloseHandle(hToken);
  goto Exit;
:Exit
end; 

What is the problem here with the return value of the function? First of all, every WinAPI function is checked against its return value and the function exits if the function call fails. This is good, because I still see a lot of codes where no checks are made. But we have another problem here. There are two possible results (sets of possible return values) we actually want to tell the caller of this function:

• The set of possible results whether the user is member of a given group. This is clearly a binary (say: two elements: TRUE/FALSE) set here.
• The set of whether an error occured. This is also a binary set (TRUE/FALSE).

The codomain of your function is a binary set which means the range of the return value is FALSE (0) to TRUE (1). However, the function above maps two sets with different meanings into one set: the codomain or function result. If one of the WinAPI calls fails, the function immediately exits and returns FALSE. So the element FALSE is obviously used for two computation results. On that tells the caller that the user is NOT a member of the given group and the other one tells her that the function failed for whatever reason. So we have a mapping of two values to one value. We lost information! Without an additional (meta) information we are unable to distinguish them again. Always think of it when you want to specifiy/write a function. But of course we have this information somewhere else. The WinAPI itself has it. GetLastError provides the error value which (hopefully) helps us to solve the problem. So everything is fine now? I wish! Check this out:

function GetMyUserName : String;
var
 nSize : Cardinal;
 p : PChar;
begin
 nSize := 0;
 if not GetUserName(nil, nSize) and (GetLastError() = ERROR_INSUFFICIENT_BUFFER) then
 begin  
   GetMem(p, nSize * sizeof(WCHAR));
   try
     if not GetUserName(p, nSize) then
       RaiseLastOSError;
     result := p;
   finally
     FreeMem(p);
   end;
 end
 else
   RaiseLastOSError;
end; 

begin
  ...
  xy := GetMyUserName();
  bIsMember := IsUserMemberOf(aGroup);

  if not bIsMember and (GetLastError() _unequal_ 0) then
    ERROR //...handling;
end;

The function IsUserMemberOf is called in succession of GetMyUserName which asks the WinAPI function GetUserName to return the size of the username string. The GetLastError code is set to ERROR_INSUFFICIENT_BUFFER (122_dec) which tells us to use create a memory block of valid size.
Now GetMyUserName returns correctly our username and let’s say that IsUserMemberOf does not fail either. But it wants to tell us that the user (or better process) is not the member of our given group. So the return value is FALSE and it is a fact that most of the WinAPI functions won’t change the LastError value if they succeed. So GetLastError will still be ERROR_INSUFFICIENT_BUFFER (122_dec) when the variable bIsMember is tested for validity and the result is an ERROR handling which, in fact, should not be done here.
As you see, although we got additional information from GetLastError, the implementation of our function does not allow a caller to find out whether the return value is the value of a computation or an error status.

If you intend to write such a function. I urge you not to use plain C techniques. Why? Let us check how WinAPI functions could look like in Delphi with plain C techniques:

function GetUserNameW(lpBuffer: LPWSTR; nSize: PDWORD): BOOL;
var
   pUserName : PWideChar;
   res: NTSTATUS;
   bRes : Boolean;
begin
   bRes := FALSE;

   if (nSize = nil) then
   begin
     SetLastError(ERROR_INVALID_PARAMETER);
     goto Exit;
   end;

   if (lpBuffer = NIL) or (nSize^ _smallerthan_ InternalGetMinUserNameLength()) then
   begin
      nSize^ := InternalGetMinUserNameLength();

      SetLastError(ERROR_INSUFFICIENT_BUFFER);
      goto Exit;
   end;

   //This is not quite necessary but adds more complexion to the example
   pUserName := HLOCAL(LocalAlloc(LPTR, InternalGetMinUserNameLength() * sizeof(WIDECHAR));
   //TODO: also check pUserName for nil, if nil goto Exit

   res := NtGetUserName(pUserName, InternalGetMinUserNameLength() * sizeof(WIDECHAR));
   if NT_FAILED(res) then
   begin
      SetLastError(NtStatusToDosError(res));
      goto Exit_1;
   end;   

   if not StrCopyMemory(lpBuffer, pUserName) then //fake call but already uses SetLastError
      goto Exit_1;

   bRes := TRUE;
:Exit_1
   FreeMem(pUserName);
   goto Exit;
:Exit
   result := bRes; //in C actually: return bRes;
end;

Looks complicated, doesn’t it? I didn’t intend to write the real implemention of GetUserName (I don’t know it by heart) but instead just show a fictive implementation. So WinAPI uses solely the function result as an error indication. FALSE means an error occured and the out parameter values and GetLastError must be checked according to documentation. TRUE means, everything is fine.

Do we need this in Delphi? Not really. If you intend to write a library, a DLL file, that needs to be called by other languages, well, than you could use SetLastError as an error reporting facility. But then you still have to return all your computations in an out/var parameter (by reference). Of course, you can also use the type HRESULT as error indicator in the return value.

function GetUserNameW(lpBuffer: LPWSTR; nSize: PDWORD): HRESULT; 

If you want a plain Delphi function, you can make life easier by using exceptions.

procedure GetUserNameW(Name: PWideChar; var nSize: DWORD); 

In addition, this makes it possible to return a computation in the function return value.

function GetUserNameW(Name: PWideChar; var nSize: DWORD) : PWideChar;
begin
  if (nSize = nil) then
  begin
    SetLastError(ERROR_INVALID_PARAMETER);
    RaiseLastOsError;
  end;
  ... //to make it short one example here is sufficient
end;

As you can see, RaiseLastOsError is called which raises an EOsError. It contains the GetLastError return code in its property ErrorCode automatically. We can even create our own exception class (JWSCL does with EJwsclWinCallFailedException) and get rid of SetLastError at all! And, of course you can use the native string type feature of Delphi which makes the function really easy to use.

function GetUserName() : String;

The function returns a string. It does not return an empty string in a case of failure as other implementations we can find on the internet. Otherwise, we would have the same problem as in the beginning of this article: One return value that can be a valid computation result or an error status. What’s your guess in this situation?

function IsUserMemberOf(const Group : PSID) : Boolean;
 var
   hToken : HANDLE;
 begin
   result := false;
   //retrieve Token here and store in hToken ... (short version)
   if not OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY or TOKEN_DUPLICATE, hToken) then
     RaiseLastOsError;

   //additional stuff for Vista and house keeping for Windows in general and a lot of RaiseLastOsError;

   if not CheckTokenMembership(hToken, Group, @result) then
   begin
      RaiseLastOsError;
   end;
end; 

A good implementation comes from JEDI Component Library (JCL) in file JclSecurity.pas Forget about all the other implementations!! Use this one:

function IsGroupMember(RelativeGroupID: DWORD): Boolean;
var
  psidAdmin: Pointer;
  Token: THandle;
  Count: DWORD;
  TokenInfo: PTokenGroups;
  HaveToken: Boolean;
  I: Integer;
const
  SE_GROUP_USE_FOR_DENY_ONLY = $00000010;
begin
  Result := not IsWinNT;
  if Result then // Win9x and ME don't have user groups
    Exit;
  psidAdmin := nil;
  TokenInfo := nil;
  HaveToken := False;
  try
    Token := 0;
    HaveToken := OpenThreadToken(GetCurrentThread, TOKEN_QUERY, True, Token);
    if (not HaveToken) and (GetLastError = ERROR_NO_TOKEN) then
      HaveToken := OpenProcessToken(GetCurrentProcess, TOKEN_QUERY, Token);
    if HaveToken then
    begin
      {$IFDEF FPC}
      Win32Check(AllocateAndInitializeSid(SECURITY_NT_AUTHORITY, 2,
        SECURITY_BUILTIN_DOMAIN_RID, RelativeGroupID, 0, 0, 0, 0, 0, 0,
        psidAdmin));
      if GetTokenInformation(Token, TokenGroups, nil, 0, @Count) or
       (GetLastError <> ERROR_INSUFFICIENT_BUFFER) then
         RaiseLastOSError;
      TokenInfo := PTokenGroups(AllocMem(Count));
      Win32Check(GetTokenInformation(Token, TokenGroups, TokenInfo, Count, @Count));
      {$ELSE FPC}
      Win32Check(AllocateAndInitializeSid(SECURITY_NT_AUTHORITY, 2,
        SECURITY_BUILTIN_DOMAIN_RID, RelativeGroupID, 0, 0, 0, 0, 0, 0,
        psidAdmin));
      if GetTokenInformation(Token, TokenGroups, nil, 0, Count) or
       (GetLastError <> ERROR_INSUFFICIENT_BUFFER) then
         RaiseLastOSError;
      TokenInfo := PTokenGroups(AllocMem(Count));
      Win32Check(GetTokenInformation(Token, TokenGroups, TokenInfo, Count, Count));
      {$ENDIF FPC}
      for I := 0 to TokenInfo^.GroupCount - 1 do
      begin
        {$RANGECHECKS OFF} // Groups is an array [0..0] of TSIDAndAttributes, ignore ERangeError
        Result := EqualSid(psidAdmin, TokenInfo^.Groups[I].Sid);
        if Result then
        begin
          //consider denied ACE with Administrator SID
          Result := TokenInfo^.Groups[I].Attributes and SE_GROUP_USE_FOR_DENY_ONLY
              <> SE_GROUP_USE_FOR_DENY_ONLY;
          Break;
        end;
        {$IFDEF RANGECHECKS_ON}
        {$RANGECHECKS ON}
        {$ENDIF RANGECHECKS_ON}
      end;
    end;
  finally
    if TokenInfo <> nil then
      FreeMem(TokenInfo);
    if HaveToken then
      CloseHandle(Token);
    if psidAdmin <> nil then
      FreeSid(psidAdmin);
  end;
end;

function IsAdministrator: Boolean;
begin
  Result := IsGroupMember(DOMAIN_ALIAS_RID_ADMINS);
end;

The same can be done using JWSCL.

uses
  JwaWindows,
  JwsclToken,
  JwsclKnownSid,
  JwsclUtils;

var
  Token : TJwSecurityToken;
begin
  JwInitWellKnownSIDs;

  Token := TJwSecurityToken.CreateTokenEffective(TOKEN_READ or TOKEN_QUERY or TOKEN_DUPLICATE);
  try
    Token.ConvertToImpersonatedToken(DEFAULT_IMPERSONATION_LEVEL, MAXIMUM_ALLOWED);
    if Token.CheckTokenMembership(JwAdministratorsSID) then
      //active member of Administrators
  finally
    Token.Free;
  end;
end;

At first I thought that it was a problem with the OpenKey function of TRegistry. However, this was already confirmed and fixed as a bug in QC# 23429.

Then I wanted to check the real error value of DeleteKey. Of course, it just returns true or false, so I added a call to GetLastError. And it returned 87 (Invalid Parameter). It must be said that using GetLastError in a framework like VCL is always a problem because you don’t really know how many winapi functions are called subsequent to the actual winapi function. So you may get an error value from another random function. This is one reason I’m using exceptions in JWSCL, btw.
A quick step through debugging session (you have to enable debug dcu in project options and rebuild the project) confirmed that the invalid parameter error (87) came from RegDeleteKey. But why 87? The next step was obvious because I had a windows function and thus I would have to read its MSDN documentation.

It reads:

Impact of workaround.Disabling icons from being displayed for shortcuts prevents the issue from being exploited on affected systems. When this workaround is implemented, shortcut files and Internet Explorer shortcuts will no longer have an icon displayed.

Let me show you, why I can’t work anymore efficiently.

Windows 7 Taskbar with plain Icons

As you can see, some of the applications are already started and they don’t have their icon but some of them have. I don’t see the reason though. Do you?

BTW: This goes on in the start menu, on the desktop, and the favorite list in Windows Explorer.

Happy working….

EDIT:

A possible fix was supplied by external programmers. Maybe this will be the only option for the last few people who are using Windows 2000 still.

Feel free to use it since it is public domain.

Download C++ Environment Scripts

By default the scripts setup the environment to the newest compiler found on your system. In this way you can just call msbuild and build your projects.

Please adapt your news reader accordingly. However, it is a pity that the old messages cannot be restored and maybe never will without an backup.

Furthermore, the server itself may still be changed but the address will stay the same.

UPDATE:

It looks to me as if only the unsecured access is not accepted. Instead only SSL is available regardless of the address (so both works).
I got some mails from people who couldn’t answer the threads I participate. So they sent me mails directly.

A shame that Kaster’s thread wasn’t replicated by e.g. Nick. His blog is far more often read by people than this Announce forum (which was afterwards effectively unavailable to me and others).
Furthermore some forums look to me a little bit more abandoned than usual. So the activity seems to be lower.