Video Screencast Help

SWV 6.1 SP1 SDK Guide Part 1: Changes in SP1 & Mounting Registry Hives

Created: 24 Sep 2009 • Updated: 29 Jul 2010
Language Translations
Jordan's picture
+1 1 Vote
Login to vote

Software Workspace Virtualization 6.1 Service Pack 1 brings one new feature, Partial Activate, a change to an existing feature, Patch, and an overhaul to where information regarding where information is stored in the registry for a layer.

This article will cover everything, including detecting the SWV version, except Partial Activate which will need it's own article due to the complexity of the feature.

Changes to the FSL2 Class

ManagedSVS.cs has several new methods added.

You can download the newest version of the FSL2 Class from the download portal.

Detecting Version

I covered extensively how to detect what version of SWV or SVS that was installed in Part One of the SWV 6.1 SDK Guide, you can use the function GetDriverVersion to determine what the behavior of a specific API is, in the case of patch, or if an API is available or not. For SP1 this is very simple, anything post build 6.1.5000 is SP1, so you just need to check that version1 is 6, version2 is 1 and version3 is greater then 5000. If version3 is less then 5000 then you're using MP1.

Changes to Patch

The Patch API haven't changed, nor has the VPA format, however now when you apply a patch file any link files (.LNK) are deleted out of the Read-Write Sub-Layer. This was done because of a few applications that changed shortcuts between versions. Unfortunately there is no way to disable this behavior.

Changes to the Registry

There were two changes to how SWV interacts with the Registry in SWV SP1, the first one shouldn't affect any of your code unless you've hard coded the path to the layer metadata section while the second change, hive mounted registry redirect areas, will possibly require you to make some changes to existing applications.

The Layer Metadata is the location in the registry where information such as the layer's name, GUID, flags and other information that's displayed when you bring up the layer info screen. Prior to SWV 6.1 SP1 this information was located at HKEY_LOCAL_MACHINE\SYSTEM\Altiris\FSL\# where # is the layers Magic Number and now all that information is located at HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\FSLX\Parameters\FSL\#.

If you had hardcoded the layer metadata location you should instead use FSL2GetLayerInfo or VzGetLayerAttribute to retrieve the regPath of a layer. To learn how to do this you can read Part 4 of the SVS SDK Guide.

Next is hive mounting, or what we're calling the Instant on Registry, which introduces two big changes with how you interact with a layer. The first is now that the registry redirect of a layer is now located at the root or HKeyLocalMachine with each Sub-layer getting it's own hive named _SWV_LAYER_# where # is the Magic Number of the Sub-layer.

The other change, which is the big one, is that the registry redirect of a layer doesn't exist if the layer isn't active, so you cannot change, add or reference any of this content by default. An example of this would be adding a new registry key to a layer via a layer editor such as SWVadmin. To get around this issue two new functions were added that allow you mount and unmount a registry hive when the layer isn't active - which places the layer into edit mode.

For more information on these changes please read SWV's New Instant On Registry Hive and Other Registry Changes in 6.1 SP1 here on Connect.

FSL2_Error_Layer_Being_Edited

Another change that was added is now when a layer is being edited, by mounting the hives when the layer is inactive, only the process that placed a layer into edit mode can make changes to it which includes activating, deleting or resetting the layer. If you try to edit a layer being edited by a separate process you'll get an error code 1068 back which is FSL2_Error_Layer_Being_Edited.

To try this open up SWVadmin and double click on that layer to open up the advanced layer editor, next open up a command prompt and try to activate the same layer via SVScmd - you should get back an Error: 1068.

Mounting Registry Hives

Before I cover the API to mount and unmount a registry hive I need to mention something that you need to be extra careful of - leaking a registry handle. When you mount a hive you're getting a handle to said hive and while that handle is open nothing else can read or edit the hive file - nor can it be unmounted. So you need to be careful that you always call FSL2SublayerEditStop when you're done with a layer, actually you'll have to call it twice because you have to mount each sub-layer separately.

If you don't do this you'll leak a handle and until your program exits that hive will be inaccessible.

If you're writing an application that you want to work with Pre-SP1 versions of SWV or SVS there are two options you can use. The first is detecting the driver version as mentioned earlier and the second is to wrap the hive mounting API in a try\catch so when the call to them is made your application won't error out.

FSL2SublayerEditStart

public static extern UInt32 sublayerEditStart
  (
      string fslGUID,
      out IntPtr pLayerEditEvent
  );

To mount a hive you need the GUID and an empty handle, an IntPtr in .Net, to get filled. You need to do this for each sub-layer so you'll need to get the peerGUID if you want to mount both the Read-Only and Read-Write Sub-layers.

This function will place a layer into Edit Mode.

Remember to keep track of the handles and to close them off properly using sublayerEditStop.

FSL2SublayerEditStop

public static extern UInt32 sublayerEditStop
  (
     string fslGUID,
     out IntPtr pLayerEditEvent
  );

To unmount a hive, and to release the handle properly, you need to pass in the GUID and the handle you got from sublayerEditStart. Note that even if you do this the hive may not unmount, it's not uncommon for a Windows process to have an open handle to something inside the layer so that it cannot be unmounted. However you still need to call this API so that you can exit Edit Mode as well as release the open handle you have so that you can activate the layer.

Seeing it in Action

In this sample code we'll be placing both sub-layers into Edit Mode and then exit Edit Mode.

FSL2 mySVS = new FSL2();
IntPtr myHandle= new IntPtr();
IntPtr myPeerHandle= new IntPtr();
StringBuilder myGuid = new StringBuilder(FSL2.MAXIDLEN);
string peerGuid = "";
FSL2.createLayer("testLayer", FSL2.LAYER_TYPE_NORMAL, true, myGuid);
mySVS.pInfo.dwStructSize = (UInt32)Marshal.SizeOf(mySVS.pInfo);
FSL2.getLayerInfo(myCmd.guid, mySVS.pInfo);
peerGuid = mySVS.pInfo.peerGUID;
if (is61SP1 ())
    {
     //load reg hive
       FSL2.sublayerEditStart(myCmd.guid, out myHandle);
       FSL2.sublayerEditStart(myPeer, out myPeerHandle);
    }
//code that affect registry
  if (is61SP1 ())
    {
        //unload reg hive
        FSL2.sublayerEditStop(myCmd.guid,out myHandle);
        FSL2.sublayerEditStop(myPeer, out myPeerHandle);
    }

There are several things going on in this code. First we're initializing all of our variables, including the handles, and then we're getting the peerGUID of our layer. Next we call is61SP1 to see if we're SP1 one or not, if we are we mount the hive. The same thing is being done at the end of our code so we make sure to close our open handles and exit Edit Mode.

static bool is61SP1 (){
    bool is61SP1 = false;
    UInt32 version1 = 0;
    UInt32 version2 = 0;
    UInt32 version3 = 0;
    UInt32 version4 = 0;
    FSL2.getDriverVersion(ref version1, ref version2, ref version3, ref version4);
    if (version1 >= 6)
       {
          //it's at least 6.1
          if (version2 >= 1)
             {
               //it's at least 6.1
                if (version3 > 5000)
                    {
                      //it's SP1
                      is61SP1 = true;
                    }
             }
        }
    return is61SP1;
}

The function above will check the version number of SWV and return true if we're SWV 6.1 SP1.

Conclusion

There are a lot of changes between SWV 6.1 MP1 and SWV 6.1 SP1 that you need to check for, they were all changes that weren't made lightly and we realize that it can affect those of you that write your own tools so I hope this guide will help you navigate around them.

Part two of this guide will cover the new features Partial Activate and Profile Excludes.

Return to the Virtualization SDK Book