The SRWLock was made for the case of a shared resource which will be changed from one ore more threads while there are other threads which want to read the resource.
Of course, this can be done with 1 or 2 critical sections. But 1 critical section will block the writing threads and 2 critical sections are 1 too much.

Optimized for speed and occupying very little memory the SRWLock provides us the basic features of the Delphi-known TMultiReadExclusiveWriteSynchronizer with an unbelievable performance (in my tests the SRWLock was at least 10 times faster then TMultiReadExclusiveWriteSynchronizer).
But, as my father likes to say “Fast and good is never together”, there are also caveats with the SRWLock: You can’t elevate a SharedLock to an ExclusiveLock and the lock can’t be acquired recursively.

Using the SRWLock is quite simple:

1. create a SRWLock

2. the reading thread

3. the writing thread

Don’t try to free the SRWLock … it’s done automatically.

The JediAPI-SVN-trunk contains the needed units (jwaWindows or jwaWinBase). Just try it.

What is a conditional variable?

Condition variables are nothing new. They are alread long known in the Unix world, and there are some thread frameworks already offering that feature. But since Windows Vista we have native support for them from the API.

Condition variables are a combination of an event and a corresponding lock. And that’s where their big advantage lies: With their help you can wait for an event and enter a critical section for example in one atomic operation. This avoids race conditions. At the same time condition variables save resources. In contrast to wait-for procedures they try to avoid trips to kernel mode when possible.

Usage

Usage of condition variables is relatively simple. There are just five functions you have to use. Additionally they follow the new course that they don’t have to be freed by the application. But foremost they have to be initialized. And that’s quite straight forward:

You need not be irritated by the content of the TConditionVariable record. In most cases the Ptr variable is nil after initialization. It works nonetheless.

A word of caution (born out of painful experience): TConditionVariable is a record. But it is not the content of the variable that is important but its address in memory. Therefore a simple assignment of CondVar2:=CondVar is no usable condition variable anymore.

Now imagine two threads which work in the same list. One is the producer filling the list. The other one is the consumer taking the items out again.

The TProducer’s code ist not really surprising. The only really interesting point is WakeConditionVariable(cvListFilled); which wakes the next thread which listens to cvListFilled.

TConsumer is much more interesting. After entering the critical section it checks whether there are items that have to be processed at all. If not SleepConditionVariableCS is called. This call leaves the CriticalSection and puts the thread in sleeping state until the timeout is reached or someone calls a wake procedure. After the sleep call the CriticalSection is entered automatically again. At this point the condition should be checked again since the wake-up call could have caused other threads to do work and change the condition. In our example this could happen if there are more than one consumer and WakeAllConditionVariable is used.

But what happens when there are more than one TConsumer but you only call WakeConditionVariable. Each call of WakeConditionVariable will wake the next thread in line until all TConsumer threads are called. Then a new round starts. As its name says WakeAllConditionVariable will wake up all threads in line at once.

And now?

All neccessary types and functions are available in the Jedi API svn-trunk. An usage example is TWaitList.

Thus it remains only to say: Do it!

From a 32Bit application, Windows makes sure that you cannot access the Windows\System32 folder because this is the place where Windows has all its 64bit DLLs and other files. Since a 32Bit app cannot load 64Bit DLLs, Windows redirects the access to Windows\SysWOW64 folder which is (nearly) a 32Bit copy of the System32 folder. Therefore if you call ShellExecute on the e.g. Windows\System32\osk.exe you actually run Windows\SysWOW64\osk.exe. However the 32Bit version of OnScreenKeyboard refuses to run on a 64Bit system.

Fortunately, we can disable the redirrection with Wow64DisableWow64FsRedirection.

That leads us to a problem with ShellExecute. It uses internal functions that are located in DLLs. And there is the problem. If a winapi function wasn’t called before, it will be setup by calling LoadLibrary and GetProcAddress. However, since redirection is offline, LoadLibrary will load a 64Bit DLL which, of course, fails. In such a case ShellExecuteEx returns GetLastError  $7E (127) which defines the error  “The module specified could not be found “. I wondered what module was not found and used ProcessExplorer to compare pre- and post situation of ShellExecute. There were many, but only one made ShellExecuteEx work with disabled redirection: MPR.dll (multi protocol router). Step by step disasm returned the that WNetGetConnectionW was loaded from the DLL. So the fix is to load this library before ShellExecuteEx (also ShellExecute) is called.

uses
  JwaWinType,
  JwaWinBase,
  JwaShellAPI,
  JwaSHFolder,
  JwaShlObj;

function Wow64DisableWow64FsRedirection(out OldValue: PVOID): BOOL; stdcall; external 'Kernel32.dll'; //only for JWA < 2.4
function Wow64RevertWow64FsRedirection(const OldValue: PVOID): BOOL; stdcall; external 'Kernel32.dll'; //only for JWA < 2.4

procedure RunOnScreenKeyBoard;
  function GetNativeWindowsDirectory : String;
  var
    P : array[0..MAX_PATH] of Char;
  begin
    SHGetFolderPath(0, CSIDL_SYSTEM, 0, SHGFP_TYPE_DEFAULT, @P);

    result := P;
  end;
var
  oldValue : Pointer;
  Path : String;
  hMpr_DLL : HMODULE;
  ShInfo : SHELLEXECUTEINFO;
begin
  //CoInitializeEx(nil, COINIT_MULTITHREADED or COINIT_DISABLE_OLE1DDE); //*1

  hMpr_DLL := LoadLibrary('mpr.dll'); //*2
  try
    if not Wow64DisableWow64FsRedirection(oldValue) then
      RaiseLastOSError;
    try
      Path := GetNativeWindowsDirectory + '\osk.exe';

      ZeroMemory(@ShInfo, sizeof(ShInfo));
      ShInfo.cbSize := sizeof(ShInfo);
      ShInfo.lpVerb := 'open';
      ShInfo.fMask := SEE_MASK_FLAG_NO_UI or SEE_MASK_NOASYNC;
      ShInfo.lpFile := PChar(Path);

      if not ShellExecuteEx(ShInfo) then
        RaiseLastOSError;
    finally
       Wow64RevertWow64FsRedirection(oldValue);
    end;
  finally
    FreeLibrary(hMpr_DLL);
  end;
end;

*1 Has no use here if it was already called. But it is a reminder that it should be called for ShellExecute due to MSDN docs.
*2 Make sure you don’t call LoadLibrary when redirection is offline.

Delphi (addition)

I forgot to mention that in my experiences, a simple call to ShellExecute works if you run your app in Delphi. You’ll see that the app already has mpr.dll loaded if you check with Process Explorer. However, running the same app in Windows Explorer it will fail.
You see that Delphi can have an effect on your application. Therefore, always test your app separately.

Download

You can download this file from here.

Remarks

I tested this code on my Win7 64bit System only.

The string “%windir%\sysnative\osk.exe” was a first guess. However, ShellExecute fails with Error 2 (File Not Found).

Because this is a 64Bit Problem only, I did not make extra effort to check for a 64Bit Windows. The function Wow64DisableWow64FsRedirection is not available on a 32Bit platform, so using static linking is a bad idea if you want to use your app on 32Bit.

If you find this code useful, you may consider a donation? As usual, a donation can be also a WinAPI conversion, examples, bug fixes etc.

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.

You may read on if you ever wanted to…

1. have this cool progress bar feature in the taskbar.
2. have an overlay icon onto your application’s icon in the taskbar.
3. multiple tabs for each window or control of your application in the taskbar.
4. have thumb buttons inside the preview of your form (like the Windows MediaPlayer).

You want your application to look like that?

Are you using Windows 7? What a lucky (wo)man you are.

The guys from TheUnknownOnes just released some components to use the new features introduced in Windows 7. 
Of course, these components are based on the JEDI Windows API. At the moment (until the next release of JWAPI), you’ll have to checkout the trunk of the JWAPI in order to get the code compiled.
To get these components, checkout the source out of their svn repository.

And if you want to discuss something about them in German: use this thread.

A first short demo was published here. Stay tuned for some more.

WinAPI

uses
  SysUtils,
  //JwaWindows, //Use either JwaWindows or these JEDI headers:
  JwaWinBase,
  JwaWinType,
  JwaWinNT,
  JwaAclApi,
  JwaAccCtrl,
  JwaWinError,
  JwaSddl;

type
  TOwnerResult = (orNone, orName, orSID);

function GetFileOwner(const FileName: string;
  out Domain, Username: String): TOwnerResult;
var
  pSD: PSecurityDescriptor;
  dwOwnerNameSize, dwDomainNameSize: DWORD;
  pOwnerSID: PSID;
  pszOwnerName, pszDomainName: PChar;
  OwnerType: SID_NAME_USE;
  dwError : DWORD;
begin
  result := orNone;

  pSD := nil;
  dwError := GetNamedSecurityInfo(
     PChar(FileName),//__in       LPTSTR pObjectName,
     SE_FILE_OBJECT,//__in       SE_OBJECT_TYPE ObjectType,
     OWNER_SECURITY_INFORMATION,//__in       SECURITY_INFORMATION SecurityInfo,
     @pOwnerSID,//__out_opt  PSID *ppsidOwner,
     nil,//__out_opt  PSID *ppsidGroup,
     nil,//__out_opt  PACL *ppDacl,
     nil,//__out_opt  PACL *ppSacl,
     pSD//__out_opt  PSECURITY_DESCRIPTOR *ppSecurityDescriptor
   );
  if (dwError <> NOERROR) then
  begin
    SetLastError(dwError);
    RaiseLastOSError;
  end;

  //First get necessary memory size for Owner and Domain
  dwOwnerNameSize  := 0;
  dwDomainNameSize := 0;
  if not LookupAccountSID(nil, pOwnerSID, nil,
    dwOwnerNameSize, nil, dwDomainNameSize, OwnerType) then
  begin
    //Check for SIDs that are unknown on this local system
    if (GetLastError() = ERROR_NONE_MAPPED) then
    begin
      Win32Check(ConvertSidToStringSid(pOwnerSID, pszOwnerName));
      Domain := '';
      Username := pszOwnerName;
      LocalFree(HLOCAL(pszOwnerName));
      result := orSID;
      exit;
    end
    else
    //Any other error exits the function
    if (GetLastError() <> ERROR_INSUFFICIENT_BUFFER) then
      RaiseLastOsError;
  end;

  //Allocate memory for owner and domain
  //Take into account the size of a char type (like WideCHAR)
  GetMem(pszOwnerName, dwOwnerNameSize*sizeof(CHAR));
  try
    GetMem(pszDomainName, dwDomainNameSize*sizeof(CHAR));
    try
      //Retrieve name and domain
      Win32Check(LookupAccountSID(nil, pOwnerSID, pszOwnerName,
        dwOwnerNameSize, pszDomainName, dwDomainNameSize, OwnerType));

      result := orName;

      Domain   := pszDomainName;
      Username := pszOwnerName;
    finally
      FreeMem(pszDomainName);
    end;
  finally
    FreeMem(pszOwnerName);
  end;
end;

The function behaves the following:

• If an WinAPI error occurs the exception EOSError is thrown. You can retrieve the error value from its property Errorcode.
• If the user name could be retrieved the result value is orName and both parameter Domain and UserName contain a value. Otherwise the result is orSID and only UserName contains the User Security Identifier (e.g. S-1-5-21-564352346-2735467565-567745764-1001).

JWSCL

Of course, JWSCL wraps these function calls already. Thus the source size decreases rapidly. See another example here.
In JWSCL it is quite different to implement the function. However the behaviour is equal:

function JwsclGetFileOwner(const FileName: string;
  out Domain, Username: String): TOwnerResult;
var
  F : TJwSecureFileObject;
  Owner : TJwSecurityId;
begin
  F := TJwSecureFileObject.Create(FileName);
  try
    Owner := F.Owner; //Owner is cached/freed by TJwSecureFileObject
    try
      Domain := Owner.GetAccountDomainName();
      Username := Owner.GetAccountName();
      Result := orName;
    except
      on E : EJwsclWinCallFailedException do
      begin
        if E.LastError = ERROR_NONE_MAPPED then
        begin
          Domain := '';
          Username := Owner.StringSID;
          Result := orSID;
        end
        else
          raise;
      end;
    end;
  finally
    F.Free;
  end;
end;

In a next version of JWSCL (currently trunk) the exception handling will be a little bit different:

function JwsclGetFileOwner2(const FileName: string;
  out Domain, Username: String): TOwnerResult;
var
  F : TJwSecureFileObject;
  Owner : TJwSecurityId;
begin
  F := TJwSecureFileObject.Create(FileName);
  try
    Owner := F.Owner; //Owner is cached/freed by TJwSecureFileObject
    try
      Domain := Owner.GetAccountDomainName();
      Username := Owner.GetAccountName();
      Result := orName;
    except
      on E : EJwsclSidNotMappedException do //not mapped error is handled differently
      begin
        Domain := '';
        Username := Owner.StringSID;
        Result := orSID;
      end;
    end;
  finally
    F.Free;
  end;
end;

If you use JWSCL (Version >= 0.9.2a) and enable the compiler switch JWSCL_SIDCACHE in file Include\Jwscl.inc, JWSCL will add a SID cache (for all TJwSecurityID instances globally). In this way LookupAccountSid will be called only once for every unknown SID and thus SIDs that were already translated are retrieved from cache instead.

Unfortunately, Access Violations are rather common and thus nobody can tell why it happens at a first glance. So I added an exception handler that maps this special access violation to a separate exception class (I called it EJwsclAccessedGuardPointerException).

uses
  ExceptionLog,
  //JwaWindows, //or
  JwaWinBase, JwaWinNT, JwaNtStatus,
  SysUtils;

type
  EJwsclAccessedGuardPointerException = class(Exception)
  public
    ExceptionRecord: PExceptionRecord;
  end;

resourcestring
  SGuardPageException = 'It was tried to access a guarded pointer. This '+
   'pointer was freed previously and is now accessed without initialization. '+
   'JWSCL may guard its class members in this way. You should check for '+
   ' accesses to e.g. class members which instance was freed.'#13#10+
   'Exception was raised at this address: $%p';

var
  GuardPtr : Pointer;
  OldExcpObj : function (P: PExceptionRecord): Exception;
  OldExitProc : procedure;

procedure MyExitProcessProc;
begin
  VirtualFree(GuardPtr, 0, MEM_RELEASE);

  if @OldExitProc <> nil then
    OldExitProc;
end;

function MyGetExceptionObject(P: PExceptionRecord): Exception;
var ErrorCode : Integer;
begin
  if (P.ExceptionCode = STATUS_ACCESS_VIOLATION) and
    (P.ExceptObject = GuardPtr) then
  begin
    result := EJwsclAccessedGuardPointerException.CreateFmt(SGuardPageException,
        [P.ExceptionAddress]);
    EJwsclAccessedGuardPointerException(Result).ExceptionRecord := P;
  end
  else
  begin
    result := OldExcpObj(P);
  end;
end;

var
  T : TObject;
  SysInfo : TSystemInfo;
begin
  OldExcpObj := ExceptObjProc;
  ExceptObjProc := @MyGetExceptionObject;

  OldExitProc := ExitProcessProc;
  ExitProcessProc := MyExitProcessProc;

  //On 32Bit OS call
  //GetSystemInfo(@SysInfo);
  //On WOW64Bit OS call (use IsWow64Process)
  GetNativeSystemInfo(@SysInfo);

  GuardPtr := VirtualAlloc(
    Pointer($BADC0DE),//  __in_opt  LPVOID lpAddress,
    SysInfo.dwPageSize,//  __in      SIZE_T dwSize,
    MEM_RESERVE,//  __in      DWORD flAllocationType,
    PAGE_NOACCESS//  __in      DWORD flProtect
  );
  if GuardPtr = nil then
    RaiseLastOSError;

  T := TObject(Pointer(GuardPtr));
  T.Free;
end.

Since the object has this guard pointer value (which may be dynamic) a call to Free (or Destroy) will fail with the exception EJwsclAccessedGuardPointerException. Be aware that there is no actual memory allocated. It is all about virtual memory.

The MyExitProcessProc is called right before the process exits. There is another exit handler called ExitProc that is called before the units are finalized. So I’m stuck with ExitProcessProc which is fine though.

I must say that I like this approach since it seems to be safer than just using a nearly arbitrary magic value. The value is still there so you can see it as an invalid memory address in a debugger. However, Assigned or similar workarounds will not work because the memory location can vary.
And of course the exception message clearly states what happened here.  There could added more information like stack trace but that I leave to you (or the JCL).

Be aware that there still might be errors. This code is hot. 

What is your opinion?

The Unicode version of this function, CreateProcessW, can modify the contents of this string. Therefore, this parameter cannot be a pointer to read-only memory (such as a const variable or a literal string). If this parameter is a constant string, the function may cause an access violation.

This means that when you move over to Unicode (Delphi 2009/2010) existing code might produce an Access Violation.

This code for example will produce an Access Violation:

To prevent these kinds of Access Violation we could change the declaration of the lpCommandLine parameter as var. This prevents passing nil though (which is allowed).

So if we want to allow passing nil but not a constant we should declare 2 overloaded functions:

and

I choose PByte in the second declaration because it allows for nil but disallows PChar(‘notepad.exe’) which will also AV.

So what do you think? Should we change this in Jwa?

What have we learned from the article?

1. Avoid version checks at all
2. Check for functionality
3. Use the right functions
4. Learn logic

1. It is always frustrating if an application doesn’t start because of version checking.

If you have a Win32API function that is not available on older OS, do not use a version check. If you don’t dive the internal structures of Window it is very likely that your application will work.

2. Instead: try to load the function with GetProcAddress. If it fails, well then use something else.

That is the reason why I tell people to set the DYNAMIC_LINK compiler switch when using any of the JEDI functions. In this case the JEDI API libraries loads a function using GetProcedureAddress (located in JwaWinTypes – don’t ask me why it is located there).
GetProcedureAddress can raise two types of Exception.

• EJwaLoadLibraryError : If a necessary library could not be found.
• EJwaGetProcAddressError : If the function could not be located in the library.

So now it is easy to write an exception handler:

try
  API_Call(...);
except
  on E1 : EJwaLoadLibraryError do
    //fail safe library not found
  on E2 : EJwaGetProcAddressError do
   //fail safe function not found
end;

Well, this code only works if you define DYNAMIC_LINK in your project options. Don’t forget it! If it is not defined, and you try to run your application on an older Windows, it just won’t start. Instead you get a nasty error message.

Delphi 2010 comes with a new feature that MS Visual C++ people know as Linker support for Delay-loaded DLLs.
Allen Bauer posted an article about this new feature for Delphi under the strange headline Procrastinators Unite… Eventually! You can also think of it as “Delay loaded functions for Delphi”.

function NewAPIFunction(Parameter : TParameter): BOOL; stdcall;
  external 'user32.dll' name 'NewAPIFunction' delayed;
...

begin
  NewAPIFunction(Parameter);
end;

Do you recognize the new word “delayed” ? If you try to access the function for the first time, it will be loaded automatically from the library “user32.dll”. So we don’t have to be afraid of running the application on an older Windows version. Unfortunately, we also have to add code that checks for the Windows version.

begin
  if OSVersion > 5.1 then
    NewAPIFunction(Parameter);
end;

(Don’t be confused about GreaterThan. There is a bug in the code plugin that prevents the greater sign to be shown correctly.)

Haven’t we learned that it is not good to check for the OS version? Shouldn’t we check for functionality? Apparently, delay loading in Delphi 2010 wasn’t created with this idea in mind.
If we change the library name or the function name to something incorrect, like:

function NewAPIFunction(Parameter : TParameter): BOOL; stdcall;
  external 'user32Bla.dll' name 'NewAPIFunction' delayed;
...

begin
  NewAPIFunction(Parameter);
end;

…and call this function, at least, I get a nasty EExternalException with the message “External Exception C0FB007E“.
Even using the correct library but an incorrect function name doesn’t change the exception type, but the message :
“External Exception C0FB007F“.

Well, It could have been so nice! And in Update 2 we’re going to see how…

function NewAPIFunction(Parameter : TParameter): BOOL; stdcall;
  external 'user32.dll' name 'NewAPIFunction' delayed;
...

begin
  try
    NewAPIFunction(Parameter);
  on E1 : ELoadLibraryError do
    //fail safe library not found
  on E2 : EGetProcAddressError do
   //fail safe function not found
end;

Instead we need to check:

function NewAPIFunction(Parameter : TParameter): BOOL; stdcall;
  external 'user32.dll' name 'NewAPIFunction' delayed;
...

begin
  try
    NewAPIFunction(Parameter);
  on E : EExternalException do
    //failsafe
end;

However, I wouldn’t even be sure that this exception type is always the same. EExternalException is always suspect to me, isn’t it? So in the end it is all about Exception.

UPDATE

I was so short sighted! To the COM people C0FB007E should look quite familiar. Yeah, it is a HRESULT code. It maps to

Severity (ERROR_SEVERITY_ERROR = $C) + Facility Code ($FB) + Code (7E and 7F)

Well $7E is 126 in decimal and can be found in JwaWinError.pas as ERROR_MOD_NOT_FOUND. Same goes for $7F =127 which is ERROR_PROC_NOT_FOUND.

Knowing this we can use:

begin
  try
    NewAPIFunction(Parameter);
  on E : EExternalException do
     RaiseLastOSError(Windows.HResultCode(E.ExceptionRecord.ExceptionCode));
  end;
end;

This exception should be known to Delphi programmers. And you can add another try except block around to catch the Win32 exception.

The exception EExternalException comes from an internal call to RaiseException.

UPDATE2:

If you read the system.pas file from Delphi 2010 you’ll find the function SetDliFailureHook. It allows us to get notified when an delayed loading error occured. So how does it look?

uses
  Windows,
  SysUtils;

type
  ELoadLibraryError = class(EWin32Error);
  EGetProcAddressError = class(EWin32Error);

function DelayedFailureHook(dliNotify: dliNotification; pdli: PDelayLoadInfo): Pointer; stdcall;
begin
  case dliNotify of
    dliNoteStartProcessing: ;
    dliNotePreLoadLibrary: ;
    dliNotePreGetProcAddress: ;
    dliFailLoadLibrary   :
      raise ELoadLibraryError.CreateFmt(
        'Failed to load library "%0:s".'#13#10' Error (%1:d) %2:s',[AnsiString(pdli.szDll),
          pdli.dwLastError, SysErrorMessage(pdli.dwLastError)]);
    dliFailGetProcAddress:
      if pdli.dlp.fImportByName then
        raise EGetProcAddressError.CreateFmt(
            'Failed to load function "%0:s" from "%1:s"'#13#10' Error (%2:d) %3:s',[
           AnsiString(pdli.dlp.szProcName), AnsiString(pdli.szDll),
          pdli.dwLastError, SysErrorMessage(pdli.dwLastError)])
      else
        raise EGetProcAddressError.CreateFmt(
            'Failed to load function #%0:d from "%1:s"'#13#10' Error (%2:d) %3:s',[
           pdli.dlp.dwOrdinal, AnsiString(pdli.szDll),
          pdli.dwLastError, SysErrorMessage(pdli.dwLastError)]);

    dliNoteEndProcessing: ;
  end;
end;

...
begin
  SetDliFailureHook(DelayedFailureHook);

  try
    NewAPIFunction(Parameter);
  on E1 : ELoadLibraryError do
    //fail safe library not found
  on E2 : EGetProcAddressError do
   //fail safe function not found
  end;
end.

All the other errors we don’t process are converted to an EExternalException error automatically. You can try it out by removing the case dliFailLoadLibrary or dliFailGetProcAddress.

By the way:

1. The function pointer of NewAPIFunction is not nil. It points to an address that does the magic behind the curtain.
2. If you wonder why the JEDI Windows API hasn’t implemented this feature: We are still in pre alpha stage.
   You could help by telling us your experience with this feature.

3. Using the right functions can be a bit problematic. There are a lot of possible functions you can use:

1. JwaWinBase/Windows contains GetVersion and GetVersionEx
2. There is also a more complex function called VerifyVersionInfo(Ex)
3. And Delphi comes with a function of its own in SysUtils : CheckWin32Version

CheckWin32Version is little known to Delphi programmers. Instead they create their own complicated classes and tool functions. But if you just want to check for the major and minor version of the OS, try this:

if CheckWin32Version(5, 1) then

It checks for Windows XP regardless of a service pack. It is the easiest and safest way to check the OS version. But sometimes you need also to know the service pack or even more.

GetVersion and GetVersionEx can be hard to be used. So Microsoft added support for a more flexible and safe way to check the OS version. VerifyVersionInfo was born.

I have translated Yochay Kiriaty’s example of VerifyVersionInfo for you.

uses
  JwaWinNT,
  JwaNative,
  JwaWinBase;

function IsWindowsXPorLater : Boolean;
const
  Condition = VER_GREATER_EQUAL;
var
  OSInfo : TOSVersionInfoEx;
  ConditionMask : Int64;
begin
  ZeroMemory(@OsInfo, sizeof(OSInfo));
  OSInfo.dwOSVersionInfoSize := SizeOf(OSInfo);
  OSInfo.dwMajorVersion := 5;
  OSInfo.dwMinorVersion := 1;
  OSInfo.wServicePackMajor := 1;
  OSInfo.wServicePackMinor := 0;

  ConditionMask := 0;
  ConditionMask := VerSetConditionMask(ConditionMask, VER_MAJORVERSION, Condition);
  ConditionMask := VerSetConditionMask(ConditionMask, VER_MINORVERSION, Condition);
  ConditionMask := VerSetConditionMask(ConditionMask, VER_SERVICEPACKMAJOR, Condition);
  ConditionMask := VerSetConditionMask(ConditionMask, VER_SERVICEPACKMINOR, Condition);

  result := VerifyVersionInfo(OSInfo, VER_MAJORVERSION or VER_MINORVERSION or
     VER_SERVICEPACKMAJOR or VER_SERVICEPACKMINOR,
     ConditionMask);
end;

I hope more people are going to use this function.

4. In the end I also want to write something about logic.

If you wonder why so many applications ceased to work when Windows Vista came out. Well, if you look at this code you should know why (Windows XP: 5.1 -> Vista: 6.0)

 if (MajorVersion >= 5) and (MinorVersion >= 1) then
 begin 'OK'
 end
 else
 begin
 'Sorry. Old Windows version detected'
 end;

Well, such a (similar) code is (still) used a lot of times. And it seems to work for Windows 2000 and XP. But in Vista MajorVersion was changed to 6 and, because it was the very first release of version 6, MinorVersion was set to zero. So the if condition stopped working on the second condition check. (BTW: This is a reason why Windows 7 is using version 6.1 instead of version 7.0 .)
Sometimes we need to apply the basic rules of logic (read a good book from Amazon) or check (nearly) all possible values in a table:

Not all Windows versions in this table really exists. But how could you know that at that time? So make the table as complete as possible. Then you can change the variables Win32MajorVersion and Win32MinorVersion to the test your if condition and run your application. Software engineers also use unit tests to check the correctness efficiency of their functions.

All in all, if the people of the bad applications had used a function like CheckWin32Version, we hadn’t this article now:

function CheckWin32Version(AMajor: Integer; AMinor: Integer = 0): Boolean;
 begin
 Result := (Win32MajorVersion >AMajor) or
 ((Win32MajorVersion = AMajor) and
 (Win32MinorVersion >= AMinor));
 end;

But then we couldn’t blame Microsoft for their bad compatibility. *g*

Based on an article of Bernd Ua and the JWA-translation of the IMAPI Headers, we developed an unit for using the Image Mastering API (IMAPI) in a kind way. You can get it from of the JEDI API Subversion repository or as a zip with binary (Download). (The in-develop-version can be found in the svn of TheUnknownOnes.net)
At the moment it supports only data/Joliet-Discs. But in the next spare time we will also add the audio/Redbook functions.

How to use it

After installing the component (TDiscmaster) and dropping it into your application, only a few things are needed to do.
Firstly get the list of available discrecorders.

The next step is, to say the discmaster, which recorder should be used. (Be aware: This starts an new image. Every data, added to the previous image, will be deleted).

The following steps are just fun:

Thats all. Normally you’ll get a burned disc now.

Your task for now, is to play around with the control (for example with the Discrecorder.Prop['WriteSpeed']). Take a look at the MSDN and get in touch with this way to burn discs. Feel free to ask if something isn’t clear to you. (I’ve mentioned only the important things. )