Kiosk Applications (part two)

Last time, we familiarized ourselves with the concept of what a kiosk application is, as well as the idea of desktop objects on Windows. This time we're going to take a look at the process behind making our own desktop and running our application on it.

Before we dive into code, I want to discuss the basic ideas behind what we're going to do and what to expect. When you create a new desktop and switch to it, what you're given isn't very much. You have the desktop background, and no processes active on that desktop. Not even Windows Explorer. So what you see visually is the user's desktop wallpaper, and that's it. No start bar. No icons. Nothing. What's more, the system doesn't trap Ctrl+Alt+Del for non-default desktops, so hitting Ctrl+Alt+Del does nothing. So you've got the most bare-bones user interface possible.

The little red flag that should be going up in your head right about now is that this means you have no way to shut anything down. You can't end-task the application. You can't go to Start->Shut Down. You can't do anything aside from power the machine down. So that brings up the chicken and egg question: how do you first launch an application inside of a desktop which doesn't currently exist, and when the application terminates, what do you do?

The most common answers to those questions are: you bootstrap your application so that it first creates a new desktop, then it launches within that desktop. When the application terminates, you can do anything you'd like, but eventually you need to go back to the original desktop to be able to do anything (like shut the computer down).

Let's talk about bootstrapping, since it seems to be the start of our journey. The concept sounds scary, but it's really quite easy. Before you can launch your application in kiosk mode, you must first have a desktop object which you can launch on. Processes belong to a desktop, not windows. So that means once your application has launched, it's already on the desktop. You can't move a process from one desktop to another (for many technical reasons which I won't speculate on), so that means you need to bootstrap. The thought behind bootstrapping is that you launch one application which is responsible for launching another application. In our case, the first application is responsible for creating the new desktop, and then launching our application on it. But because of bookkeeping purposes, and security, the first app (the bootstrapper) is also responsible for some bookkeeping -- it needs to keep track of what the current desktop is before making the new one, and once the kiosk app is done running, it usually is responsible for switching back to the default desktop and closing the new one.

So what actions does the bootstrapper need to take? Well, first, it needs to get some information about what desktop is currently active. It does this by calling the GetThreadDesktop API for the current thread and stores that value. Then it needs to "open" the input desktop with the ability to switch desktops using the OpenInputDesktop API. Note that if the user doesn't have the proper access rights to do this, then they will not be able to switch from one desktop to another, and this API will return nil instead of the old input desktop. So now that you're storing the current thread's desktop and the current input desktop, it's time to make a new one using a call to CreateDesktop. If the user has the proper access rights, this call will return a non-nil value for the newly made desktop. At this point, there's a new desktop object on the system, but it's not currently active -- calling SetThreadDesktop and SwitchDesktop takes care of that. The first call assigns the new desktop to the current thread so that it can interact with the new desktop. The call to SwitchDesktop is what physically changes your view from the default desktop to the new one. When this happens, you're presented with the spartan view described earlier.

The next step the bootstrapper needs to take is to launch the kiosk application and wait for it to terminate. Once the kiosk application terminates, the bootstrapper is then able to restore the default desktop switching back to the old input desktop (the value returned to us from OpenInputDesktop), and calling SetThreadDesktop again with the value returned to us from our earlier call to GetThreadDesktop. Then it can destroy the kiosk's desktop with a call to CloseDesktop.

Now that we know the general process we need to follow, let's take a look at some of the declares needed to make it happen.[rbcode] Soft Declare Function CreateDesktopW Lib "User32" ( name as WString, device as Integer, devMode as Integer, _
flags as Integer, access as Integer, sec as Integer ) as Integer
Declare Function GetCurrentThreadId Lib "Kernel32" () as Integer
Soft Declare Function GetThreadDesktop Lib "User32" ( id as Integer ) as Integer
Soft Declare Function OpenInputDesktop Lib "User32" ( flags as Integer, inherit as Boolean, access as Integer ) as Integer
Soft Declare Sub SetThreadDesktop Lib "User32" ( desk as Integer )
Soft Declare Sub SwitchDesktop Lib "User32" ( desk as Integer )
Soft Declare Sub CloseDesktop Lib "User32" ( desk as Integer )[/rbcode]
As you can see, we're using soft declares for the desktop functions. We need to do this because older versions of Windows (such as 98 and ME) do not support multiple desktops.

Following our pseduocode from above, to store our desktop information, we'd do:[rbcode] Const DESKTOP_SWITCHDESKTOP = &h100

// The first thing we need to do is keep track of the current
// desktop so that we can switch back to it when we're done
mOldDesk = GetThreadDesktop( GetCurrentThreadId )

// We also need to get the input desktop
mOldInputDesk = OpenInputDesktop( 0, false, DESKTOP_SWITCHDESKTOP )[/rbcode]
That's takes care of the initial bookkeeping. The call to GetThreadDesktop should be self-explanatory (we're simply getting a handle to the current thread's desktop object). The call to OpenInputDesktop will return to us our current input desktop object. We're specifying no flags, that we don't want to inherit any handles, and that we want the ability to switch desktops.

Now we're ready to create the new desktop.[rbcode]Const GENERIC_ALL = &h10000000
// Now we're ready to make our new desktop. We're just going to use
// the application name as the desktop name.
mDesk = CreateDesktopW( "Spiffy Desktop", 0, 0, 0, GENERIC_ALL, 0 )[/rbcode]
This call creates a desktop named "Spiffy Desktop" (note that desktop names are case insensitive and cannot contain a backslash [\] character). The second and third parameters are reserved and must be zero. The fourth parameter specifies the flags, and we don't have any to set. The fifth parameter determines our desktop's access rights, and we want to allow them all. The final parameter is a security attribute, which we can safely ignore (it'll inherit the security from the current application). As you can see, making a new desktop object really isn't that hard!

The next step we have to accomplish is switching to our new desktop, which we do like this:[rbcode] // Now that we've made a new desktop, let's set it up and
// switch over to it
SetThreadDesktop( mDesk )
SwitchDesktop( mDesk )[/rbcode]
If you run this code right now, as-is, you'll see what I mean by security. However, you should save any open work you have, because you will be shutting down your computer. When your application runs, you'll see the screen go to a blank-looking desktop with no icons. No amount of monkeying around will get you back to your original desktop. Go ahead, give it a spin -- I'll just wait here for you to reboot. :-)

Ok, now that you're back, let's continue on. At this point, your bootstrapper will be launching the kiosk application onto the new desktop, and it should wait for the application to terminate. I am going to gloss-over the details of how this is accomplished a bit. You'll use more declares, which are found in the Windows Functionality Suite. Specifically, you'll use CreateProcess to launch the application and WaitForSingleObject to wait for the application to terminate. Just assume you have access to a function called FolderItem.LaunchAndWait (I'll provide the code below).[rbcode]// Launch the kiosk application into the new desktop
theKioskAppItem.LaunchAndWait( "", "Spiffy Desktop" )[/rbcode]
This causes the kiosk application to launch, and the bootstrapper to pause execution. After the kiosk application has finished executing, the bootstrapper will resume executing and should clean things up.[rbcode] // Now clean everything up
SwitchDesktop( mOldInputDesk )
SetThreadDesktop( mOldDesk )
CloseDesktop( mDesk )[/rbcode]
That's all there is to it! When you put it all together, you suddenly have a bootstrapping application which can launch a kiosk app into a new desktop. However, we're not done with this topic yet. Tune in next time for a discussion of how to improve upon our knowledge of how kiosk applications work.

Oh, and as promised, here's the LaunchAndWait function.[rbcode]Sub LaunchAndWait(extends f as FolderItem, params as String = "", deskName as String = "")
// We want to launch the application and wait for
// it to finish executing before we return.
#if TargetWin32
Soft Declare Function CreateProcessW Lib "Kernel32" ( appName as WString, params as WString, _
procAttribs as Integer, threadAttribs as Integer, inheritHandles as Boolean, flags as Integer, _
env as Integer, curDir as Integer, startupInfo as Ptr, procInfo as Ptr ) as Boolean

Soft Declare Function CreateProcessA Lib "Kernel32" ( appName as CString, params as CString, _
procAttribs as Integer, threadAttribs as Integer, inheritHandles as Boolean, flags as Integer, _
env as Integer, curDir as Integer, startupInfo as Ptr, procInfo as Ptr ) as Boolean

dim startupInfo, procInfo as MemoryBlock

startupInfo = new MemoryBlock( 17 * 4 )
procInfo = new MemoryBlock( 16 )

dim unicodeSavvy as Boolean = System.IsFunctionAvailable( "CreateProcessW", "Kernel32" )

startupInfo.Long( 0 ) = startupInfo.Size

dim deskStr, deskPtr as MemoryBlock
if deskName <> "" then
if unicodeSavvy then
deskStr = ConvertEncoding( deskName + Chr( 0 ), Encodings.UTF16 )
else
deskStr = deskName + Chr( 0 )
end if

startupInfo.Ptr( 8 ) = deskStr
end if

dim ret as Boolean
if unicodeSavvy then
ret = CreateProcessW( f.AbsolutePath, params, 0, 0, false, 0, 0, 0, startupInfo, procInfo )
else
ret = CreateProcessA( f.AbsolutePath, params, 0, 0, false, 0, 0, 0, startupInfo, procInfo )
end if

if not ret then return

Declare Function WaitForSingleObject Lib "Kernel32" ( handle as Integer, howLong as Integer ) as Integer
Const INFINITE = -1
Const WAIT_TIMEOUT = &h00000102
Const WAIT_OBJECT_0 = &h0

// We want to loop here so that we can yield time back
// to other threads. This means threaded applications
// will "just work", but non-threaded ones will still appear hung.
while WaitForSingleObject( procInfo.Long( 0 ), 1 ) = WAIT_TIMEOUT
App.SleepCurrentThread( 10 )
wend

Declare Sub CloseHandle Lib "Kernel32" ( handle as Integer )
CloseHandle( procInfo.Long( 0 ) )
CloseHandle( procInfo.Long( 4 ) )
#endif
End Sub[/rbcode]