To understand the concept of Window Sessions, Stations and Desktop it is not necessary to read all articles to the end. I think the beginning is just fine.

• Pushing the Limits of Windows: USER and GDI Objects
  Mark Russinovich writes about USER and GDI objects but he also gives a basic introduction how sessions, windowstations and desktops are related.
  • Part 1
  • Part 2  (still writing)
• Desktop Heap Overview
  The guys from Advanced Windows Debugging and Troubleshooting explain how it is possible that a desktop can run out of heap. It is a quite technical article but it gives a nice insight into some of the Windows internals.
  • Part1
  • Part2

I often prefer such blog articles to MSDN articles because blog articles are much more fun to read.

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?

I introduced a function similar to FreeAndNil

procedure JwFree(var Obj);

It just frees an object…in the release build of an application. However, in a debug build it additionally sets the value of obj to $C which isn’t a valid memory address. So “Assigned” won’t work here.
Any access to this “freed” member will generate an AccessViolation at address $0000000C. So you will know that a member of JWSCL was used beyond its life time.

procedure JwFree(var Obj);
var
 Temp: TObject;
begin
  Temp := TObject(Obj);
{$IFDEF DEBUG}
  Pointer(Obj) := Pointer($C);
{$ENDIF DEBUG}
  Temp.Free;
end;

I wonder if it should be extended to support different flavors like

1. $C in debug build and don’t touch the value in release (as currently shown)
2. Set the value $C also in release mode.
3. Nil the value in release mode. (quiet death mode)

They could be set by a compiler switch. Still have to think about this though…
What do you think?

Changes

I have commited these changes into the developer branch. They will be published in a next release so the current release won’t break a bad design.

So here are the feautures (You can look up the class names on the documentation page):

• Windows Token management (TJwSecurityToken)
  • Impersonation
  • Supports LogonUser, LsaLogonUser
  • Lots more
• Full support of Security ID (SID) (TJwSecurityID, TJwSecurityIDList)
  • Also well known security IDs like Everyone (JwsclKnownSid.pas) are stored as simple to use variables.
• Full support of Access Control Lists (also CALLBACK_ACE and OBJECT_ACE)
  • DACL, SACL
• Full support of Security Descriptor (SECURITY_DESCRIPTOR) (TJwSecurityDescriptor)
  • DACL, SACL, Owner, Group
  • Implements a simple to use Security Descriptor (TJwSimpleDescriptor)
• Security Rights Mapping; Maps Generic Rights to specific ones (JwsclMapping.pas)
  • Conversion of Security Rights (DWORD) to Human Readable names (JwFormatAccessRights)
• Privileges (TJwPrivilege, TJwPrivilegeSet, JwsclPrivileges.pas)
• Windowstation and Desktops (TJwSecurityWindowStation, TJwSecurityDesktop)
• Local Security Authority Logon Sessions (TJwLsaLogonSession)
• Security of Windows objects; files, registry, handles (TJwSecureFileObject, TJwSecureFileObject, TJwSecureGeneralObject)
  • Support of Access Checking (AccessCheck)
  • Supports Inheritance (by default only files and registry)
• Support of MS AuthZ API; Client Side Access Checks for custom Resources (JwsclAuthCtx.pas)
• Credentials GUI API (TJwCredentialsPrompt)
• MS Encryption and Protection API (TJwEncryptionApi,  TJwEncryptMemory, TJwRandomDataGenerator)
• Windows Version Detection on remote or local client (TJwFileVersion, TJwServerInfo, TJwWindowsVersion) Security Descriptor GUI (TJwSecurityDescriptorDialog)
• Terminal Sessions (TJwTerminalServer)
  • Server Management
  • Sessions Management
  • Processes Management
• Vista Elevation (JwShellExecute, JwElevateProcess, JwsclElevation.pas)
  • Supports SuRun (English version) (JwElevateProcess, JwCheckSuRunStatus)
• Vista Integrity Level (Built in)
• Firewall Administration (TJwsclFirewall)
• Builtin basic Sma rtpointer Support (TJwAutoLock)
• Job Object support (TJwJobObject) even with several sessions (TJwJobObjectSessionList)
• Process Handling that encapsulates support for different Windows Versions and bugs in API (functions JwCreateProcessAsAdminUser, JwCreateProcessInSession, JwGetProcessSessionID, JwGetTokenFromProcess, JwProcessIdToSessionId)
• Support Memory Mapped Objects (TJwFileStreamEx, TJwIPCStream, TJwVirtualStream)
• Extended Thread Support lile naming threads and WaitWithTimeOut (TJwThread)
• Hashing Support (TJwHash) 
  • For JWSCL classes (JwObjectHash)
  • For files (JwCreateFileHash, JwCompareFileHash, JwDataHash, JwIntegerHash) in combination with fast Memory Mapping.
• DCOM support for Client and Server (currently only developer branch); CoInitializeSecurity (TJwComProcessSecurity), Authentication, Impersonation, Proxy Security Blanket (TJwComClientSecurity, TJwComServerSecurity), Access Control (TJwServerAccessControl), DCOM Configuration (TJwComRegistrySecurity) of Global Configs and Class Security.
• Easy to use WinAPI (Msg)WaitForMultipleObjects functions (JwMsgWaitForMultipleObjects, JwMsgWaitForMultipleObjects)
• Multi Language Support of Resource Files (LoadLocalizedString)
• Ansi- & Unicode due to own Delphi compatible String type TJwString (JwsclAnsiUniCode.pas)
• Mapping of Windows Constants to Delphi enumeration (TJwEnumMap)
• All errors are reported by exceptions using a derived class from EJwsclSecurityException. (JwsclExceptions.pas)
• Supports Bugreports with Eurekalog (JwsclEurekaLogUtils.pas)
• JWSCL is based on OOP

To come

• Active Directory Support
• User Account Management

Current version is 0.9.3 Download.

Valid for all open source projects, also the JEDI API&WSCL projects heavily depend on their users. This is not a company where people work all day to make a  great project. I and other members of JEDI use our spare time after real work to bring forward projects such as JEDI.

Unfortunately, time has changed and less and less people want to provide their skills and manpower in projects like JEDI…and I am not talking about JEDI API exclusively. That is a pity because we will not provide you with source code forever. Instead the process will come to a halt and we will see more and more questions in newsgroup asking why the project doesn’t work anymore in Delphi 2020 (or similar).

I don’t get it. There are many new API functions in Vista and Windows 7. And I see a lot of people writing conversions from C to Delphi so they can use the new functionality. But instead of donating these sources to JEDI API they post it to their local forum or use it in their project as an internal unit. Usually, I come along and ask these people if they want to donate their source to JEDI API. And the chat goes like this:

Christian: “Hey, I am from JEDI API. Maybe you heard from us. It would be great if your conversion could be integrated into JEDI. Do you agree?”

X: “Yeah, I’m using your projects a lot. And of course, I would like to see my source integrated into JEDI.”

C: “Well, I need your source code to be converted to some standards we use. I will send you more information about this easy process. If you have further question just ask.”

X: “Eh? Sorry, but I don’t have time to put more effort into this. Can’t you just do it yourself?”

Let me answer: Well, If we could do it ourselves we would already have done it. But that means that we would need to give up our jobs and private life to convert over 20.000 functions, interfaces and types only for this project.

Did you know that there is a template that shows you how to create a JEDI API file?

Also it often happens that I don’t hear anything from them. Therefore these conversions never get integrated because I need an explicit agreement.

On the other hand there are many people who like just to use the source code in their own project because it makes it easier to write good programs.
May I ask what you did to keep alive the project that you gained from?  I have to say from experience that the donations in source and money (in relation to current software prices) are that rare that zero (0) would describe it best. Luckily, this is not entirely true but it is very close to the truth.

Fortunately, there are a lot of companies which are generous and allow us to use their products for free. You can find the list  in the sponsors section of this blog. With a monetary donation of nearly zero we could never use their products. I cannot stop saying: “Thank you!“

Also let me use this article to thank all the people who helped or are still helping in these projects. I want to thank them again and again and again! And let me thank the donators again (I wrote them a mail).

–

Christian

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.

I always add “RaiseLastOsError” to every Windows API call.

if not ImpersonateLoggedOnUser(token) then
  RaiseLastOsError;

In this way you don’t miss any failed call and wonder what is happening (I can recall a lot of forum threads that ask about this).
RaiseLastOsError generates an EOSError exception that contains the error number and text in its message. It also stores the GetLastError value in its property ErrorCode.

One more good thing is that a caller of the function, where this code is implemented, cannot ignore an error value. The API function ImpersonateLoggedOnUser is very problematic because if it fails all subsequent calls are made on the security token of the process instead of the thread. So a client could access more things than usual. So if we had a function that implements the example

function MyImpersonateUserToken(UserName : String; out UserData : PUserData) : Boolean;
begin
  //get user token here
  //get user information from token here and store it into UserData

  result := ImpersonateLoggedOnUser(token);

As you can see a caller can just do the following

MyImpersonateUserToken(UserName, UserData);
If UserData.Groups.IsMemberOf('Administrators') then

Be aware that the example is only fictional. However I have seen many production codes that call WinAPI without error checking. The WinAPI usually (and the code above definitely) does not touch any of the output parameters if they fail. So you probably get an Access Violation (best case) or it works randomly (worst case). See that UserData is not initialized here. But what about this one:

procedure MyImpersonateUserToken(UserName : String; out UserData : PUserData);
begin
  //get user token here
  if not GetUserToken then
    raiseLastOsError;
  //get user information from token here and store it into UserData
  if not GetTokenInformation then
    raiseLastOsError; 

  if not ImpersonateLoggedOnUser(token) then
    raiseLastOsError;

You see that the function is really a procedure now that throws exceptions in case of failure. In this way the code following the function call MyImpersonateUserToken isn’t executed at all. Instead, we need to wrap an exception trap around the function call to let the code continue.

try
  MyImpersonateUserToken(UserName, UserData);
except
end;

if UserData.Groups.IsMemberOf('Administrators') then

Okay, everbody should see that this is a really ******* code and should not be left in this way.

If you make an habit from this you won’t miss the old way. Instead it takes less time to implement and I don’t mention the time searching for memory leaks.

Furthermore, I think it looks much better and besides of that it is really easy to read and understand.
However, the most important reason (for me) is that any user who calls this function incorrectly (e.g. user not found) gets a nasty exception thrown into the face.

These are the reasons why JWSCL throws exceptions in 99,99% of its methods instead of returning error values.

I always use try/finally for memory allocations

Programmers have a hard to find memory leaks. There are libraries (like JWSCL) that support smart pointers but Delphi comes also with “smart pointers” (besides interfaces). Although it needs some more work. If you have translated code from C to Delphi you have seen it maybe. I’m talking about “goto” statements in C code.

{
  ...
  if (!GetTokenInformation(...))
    goto exit_1;

goto exit_0;
:exit_1
  CloseHandle(hToken);

:exit_0
return (result);
}

In Delphi we don’t use goto because we were told that it is  bad habit. So we directly put the exit after each failed function called.

begin
  ...
  if not GetToken(hToken) then
  begin
    result := true;
    exit;
  end;
  if (not GetTokenInformation(...)) then
  begin
    CloseHandle(hToken);
    result := FALSE;
    exit;
  end;

  CloseHandle(hToken);
  result := TRUE;
end;

In more complex code you can easily miss a failure code path or miss to close a handle or free an object. So why don’t do it this way?

  ...
  if not GetToken(hToken) then
    raiseLastError;

  try
    if (not GetTokenInformation(...)) then
      raiseLastError;

    if GetMeOutOfHere() then
      exit;
  finally
    CloseHandle(hToken);
  end;
end;

The try/finally statement ensures that the code within finally is executed. It does not matter that an exception is raised (we know that already). Even if we call “exit” the finally part is also executed.

However, you need to make sure that the variables within finally are valid.

1. CloseHandle throws an exception if the handle is not valid. This only happens if it detects an attached debugger.

2. Free, FreeAndNil, FreeMem, Dispose will throw an exception depending on the content of the given pointer. In worst case nothing happens and you get garbage results anywhere else in your application.

So the correct way is to trap every allocated variable (pointer, class) in a separate try/finally statement.

New(Ptr);
try
  MyClass := TMyClass.Create;
  try
    ...
  finally
    FreeAndNil(MyClass);
  end;
finally
  Dispose(Ptr);
  Ptr := nil;
end;

Make it an habit to implement the finally part immediately. Delphi helps you by adding the finally part automatically.

New(Ptr);
try
  (1)
finally
  Dispose(Ptr);
  Ptr := nil;
end;

Now continue at position (1).

One more tip: If you have a lot of source lines between try/finally you can also put a comment behind finally to show the initial call.

New(Ptr);
try
  ... many lines ...
finally //New(Ptr);
  Dispose(Ptr);
  Ptr := nil;
end;

In this way you don’t mix up the variable names allocated and freed. And we also don’t mix up the allocation types (e.g. GetMem <> Dispose)

Your programming habits

If you want to share your habits you can do this by leaving a comment. Or better you can write your own article and link it here so a conection is made.

Looking forward to hearing from you!

Christian

[Update]
The fix is currently only available in the developer version repository (aka trunk) of Subversion.

Internally the Connect method of TJwTerminalServer verifies the connection to Terminal Server by reading some property. This is done because of a change in the API’s by Microsoft: opening a handle with WTSOpenServer to a nonexisting server actually returns a valid handle. I reported this as a bug to Microsoft some time ago and the “fixed it” by changing the documentation.

For those interested in the code: it is a class function called IsValidServerHandle which can be used to verify a handle returned by WTSOpenServer:

class function TJwTerminalServer.IsValidServerHandle(const hServer: THandle): Boolean;
var
  dwSize: DWORD;
  WinStaInfo: WINSTATIONINFORMATIONW;
begin
  { All Windows < Vista return 0 on Invalid handle }
  Result := hServer <> 0;

  { No need to continue if it's already invalid... }
  if not Result then
    Exit;

  { For Windows >= Vista we need to make a query to be sure
    A non valid connection will fail on WTSQuerySessionInformation and will
    return LastError RPC_S_SERVER_UNAVAILABLE }
  if (TJwWindowsVersion.IsWindowsVista(True)) or
    (TJwWindowsVersion.IsWindows2008(True)) then
  begin
    Result := WinStationQueryInformationW(hServer, 65536, WinStationInformation,
      @WinStaInfo, sizeof(WinStaInfo), dwSize) or (GetLastError() <> RPC_S_SERVER_UNAVAILABLE);
  end;
end;

A more visible change is the introduction of the Session function of TJwTerminalServer, with this function you can get all details for a specific session. It is meant for those cases where you need only one specific session and is of course far more efficient than enumerating all sessions, retrieving all sessions details and then finding the particular session in the SessionList.

The signature of the function is:

function TJwTerminalServer.Session(const SessionId: TJwSessionId = WTS_CURRENT_SESSION): TJwWTSSession;

Note that the parameter is default so you can call both:

Session := TS.Session;  // Retrieve the current Session

and

Session := TS.Session(1); // Retrieve the session with SessionId 1

It is important to understand the difference between Session and Sessions: where Session returns an instance of TJwWTSSession, SessionS returns a SessionList. This is especially important because Session works with a SessionId parameters and Sessions (being a TObjectList descendant) is accessed with by Index which is just the position in the ObjectList.

If a Session is not found an EJwsclWinCallFailedException will be raised so you’d better wrap the call into a try..except handler!

The last remark is that you, the caller, are responsible for freeing the object so a more complete sample would be like this:

var
  TS: TJwTerminalServer;
  Session: TJwWTSSession;
begin
  TS := TJwTerminalServer.Create;
  try
    try
      Session := TS.Session;
      try
        // Work with the session object
        ShowMessageFmt('Username=%s', [Session.Username]);
        Session.PostMessage('Hello from the Jedi guys!', 'Message', MB_OK);
      finally
        FreeAndNil(Session);
      end;
    except
      // Handle Exception here!
    end;
  finally
    FreeAndNil(TS);
  end;
end;

You can see this comment at the beginning of a newly created service application. Unfortunately, today it is only half of the truth.

If you like to create a DCOM server in a service, and this is really easy if you know how to create in-process COM objects, then you need to know that Microsoft has changed the precondition for service initialization.

StartServiceCtrlDispatcher reads:

If a service runs in its own process, the main thread of the service process should immediately call StartServiceCtrlDispatcher. All initialization tasks are done in the service’s ServiceMain function when the service is started.

Usually, the COM factories in Delphi register their classes before any of the user code is initialized. It is done in unit ComServ in procedure Initialization. There an initialization procedure (InitProc) is set for further processing.This is bad for services because the COM registration has to be done in the ServiceMain function (or just after the call) as MSDN states. If you ignore or forget it the creation of a COM object (in the client) fails after some time (usually some minutes) with the error

CO_E_SERVER_EXEC_FAILURE ($80080005) : Server execution failed

For this reason the comment was added to the service code:

 // Windows 2003 Server requires StartServiceCtrlDispatcher to be
 // called before CoRegisterClassObject, which can be called indirectly
 // by Application.Initialize. TServiceApplication.DelayInitialize allows
 // Application.Initialize to be called from TService.Main (after
 // StartServiceCtrlDispatcher has been called).
 //
 // Delayed initialization of the Application object may affect
 // events which then occur prior to initialization, such as
 // TService.OnCreate. It is only recommended if the ServiceApplication
 // registers a class object with OLE and is intended for use with
 // Windows 2003 Server.
 

Well, what I didn’t realize, and that I really blame myself for, was the fact that this condition also exists in Windows Vista and Windows 7.  So we need to set

Application.DelayInitialize := true;

not only in Windows Server 2003 but also in all new Windows versions like Vista, 7, 8 and so on. So don’t believe in what comments tell but start thinking… Lesson learned the hard way.

PS. Is it worth to file it in QC?

References

QC Report 4722 : Service exposing COM interface does not work on windows 2003; http://qc.embarcadero.com/wc/qcmain.aspx?d=4722