Video Screencast Help
Protect Your POS Environment Against Retail Data Breaches. Learn More.

SWV 6.1 SDK Guide Part 3: Duplicating Layers & Sub-layer Merging

Created: 30 Jul 2009 • Updated: 29 Jul 2010
Language Translations
Jordan's picture
+2 2 Votes
Login to vote

In the previous article I talked about Patching, which is the first half of the new Layer Management features of SWV, for Part 3 I'm finishing off Layer Management functions with Duplicating Layers and Sub-Layer Merging. At first glance you may not recognize these features because the API are named differently from what the feature name is. In SVSadmin or SVScmd Duplicate layer is named Clone Layer and Sub-layer Merging is named "New Reset Point".

As with the Patch article I'll briefly cover what the new feature can be used for so you have an idea of how to use the API.

FunctionNameA vs. FunctionNameW

If you have the SDK help file, which can be installed via the SWV installer (run a repair and add features if you haven't done this), you'll notices that several of the new API are listed twice with either an 'A' or a 'W' after them. This is to designate if the function is in Ansi (A) or Unicode (W) which is something that shouldn't be new to you if you're a C++ developer on Windows. For the FSL2 Class I'll only be using the Ansi version for several reasons: first and foremost all the other API are Ansi only so I don't want to confuse people with what type they're calling. Secondly .Net by default marshals in unmanaged code as Ansi.

It's also worth noting that all the functions that have an 'A' and 'W' version are found in VzLib.dll instead of FSLLib32.dll.

Changes to the FSL2 Class

ManagedSVS.cs has several new methods added.

SVSConst has a new type added.

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

Duplicate Layer

VzDuplicateLayer does pretty much what you'd expect, it creates an exact copy of the layer in question that has a new GUID and name. This can be useful if you want to run and update or patch on a layer and want to keep the older version on a machine until you can verify that the updates work as intended. In SWV we call this feature Clone because we wanted to keep to a similar word length as the other commands that Duplicate Layer is grouped with (Delete, Export, Rename).

VzDuplicateLayer

 public static extern UInt32 duplicateLayer
 (
   string souceLayerGuid,
   string newLayerName,
   [MarshalAs(UnmanagedType.LPStr)] StringBuilder newLayerGuid,
   bool keepRWLayer,
   VZ_PTCH_CB_FUNC CBInfoFunc,
   ref VZ_DIFF_PTCH diffUserData
  );

VzDupluicateLayer takes several parameters in and returns a GUID for the clone. Most of these are pretty self explanatory, you pass in a source GUID, a new name for the cloned layer and a boolean for if you want to keep the Read Write Sub-layer from the source layer. Like Patch API you need to pass in the new structure VZ_DIFF_PTCH and the user data object for status reporting - see Part 2 of the SWV 6.1 SDK Guide for more information and examples. VZ_DUPE_STAGES is the enumeration used for getting the clone progress status.

Merging Sub-Layers

VzMergeLayer is an interesting feature that, due to poor naming, can be confusing on what it actually does. VzMergeLayer simply merges a Layer's Read-Write Sub-layer into the Read Only Sub-layer. It does not merge two layers into one which the API name implies - which is why I'm making sure to always refer to the feature as Sub-Layer Merging so there's no confusion.

Merge Sub-layers is called "Create Reset Point" in SVSadmin and SVScmd because to a user that's all they really need to know, if they select this option they're just updating what a layer gets reset to - most people don't need to know the nitty-gritty about what a reset point actually is (the Read Only Sub-Layers) or the difference between Layers and Sub-layers.

VzMergeLayer

 public static extern UInt32 mergeLayer
 (
   string layerGuid,
   string userSID,
   VZ_PTCH_CB_FUNC CBInfoFunc,
   ref VZ_DIFF_PTCH diffUserData
 );

VzMergeLayer takes a GUID and a userSID. You can use any SID you want, or pass in NULL, and to make it easy there's a constant you can pass in - VZ_USE_CURRENT_USER_SID - that will tell SWV to just use the current user's SID for the merge. If you pass in NULL for a SID VzMergeLayer will not copy down any of the user information in the Read Only Sub-layer. If it does, it moves the information to the Default User's area so any user on that machine will have access to that content if the layer is active.

Like Patch API you need to pass in the new structure VZ_DIFF_PTCH and the user data object for status reporting -see Part 2 of the SWV 6.1 SDK Guide for more information and examples. VZ_COPY_RW_STAGES is the enumeration used for getting the clone progress status.

Seeing it in Action

In this example I'm going to write a tool that will take a GUID and then clone the layer (to make a copy) and then merge the sub-layers of the original. As with all my code samples I'm not bothering with writing out the argument logic and I am just assuming you've already done that.

Main Function

  FSL2 mySVS = new FSL2();
  String myGuid = args[0];
  StringBuilder myGuid2 = new StringBuilder(FSL2.MAXIDLEN);
  StringBuilder myCloneName = new StringBuilder(FSL2.MAXNAMELEN);
  UInt32 result=1;

  FSL2.getLayerNameFromGUID(myGuid.ToString(),myCloneName);
  result = FSL2.duplicateLayer(myGuid.ToString(), "Copy of " + myCloneName.ToString(), myGuid2, true, new FSL2.VZ_PTCH_CB_FUNC(mergeCloneStatus), ref mySVS.diffUserData);
  if (result == 0)
   {
    Console.WriteLine("Clone of layer " + myCloneName + " done. Creating new Reset Point.");
    result = FSL2.mergeLayer(myGuid.ToString(), FSL2.VZ_USE_CURRENT_USER_SID, new FSL2.VZ_PTCH_CB_FUNC(mergeCloneStatus), ref mySVS.diffUserData);
    if (result == 0)
     {
       Console.WriteLine("New Reset Point created for " + myCloneName + ".");
     }
    else
     {
       Console.WriteLine("Error Creating Reset Point. Error Code " + result);
      }
    }
  else
    {
     Console.WriteLine("Error Cloning Layer. Error Code " + result);
    }

As always the first thing we do is create an instance of the FSL2 object which initializes the SWV driver. Then I assign the GUID for the layer we're going to be manipulating and create two new StringBuilders, one for the cloned layer's GUID and one for the cloned layer's name. Lastly I create a result variable with the default value of 1 - which no API returns as a result code.

Next I get the layer's name from a GUID, which gets placed in the StringBuilder we created, then I call FLS2.duplicateLayer where I add "Copy of" in front of the new layer name so we can tell which one is the copy. Notice that for FSL2.VZ_PTCH_CB_FUNC I'm passing in mergeCloneStatus-which I'll cover below - to both duplicateLayer and cloneLayer because both of the API can use the same status reporting method.

If the layer was cloned correctly I notify the user and then call the mergeLayer function to change the Reset Point of the original layer and if that worked I let the user know. On a failure for either API I let the user know that the process failed and gave them the SVS error code number so they can find out information about the problem.

 public static void mergeCloneStatus(FSL2.VZ_DIFF_PTCH CBInfoFunc)
  {
   if (CBInfoFunc.currentFunction == FSL2.VZ_COPY_RW_TO_UT)
    {
      Console.WriteLine("Creating Reset Point, keeping user SID for current user");
    }
   else if (CBInfoFunc.currentFunction == FSL2.VZ_DUPLICATE_LAYER)
    {
      Console.WriteLine("Cloning Layer");
    }
  }

To get the status of DuplicateLayer or MergeLayer you need to use a delegate function like mergeCloneStatus above. In Part 2 of this guide I showed how you can get percentage complete for an operation. This time around I'm showing how you can use the currentFunction parameter of FSL2.VZ_DIFF_PTCH to determine what API called the delegate by comparing the value of currentFunction to some constants in the FSL2 Class. In this particular case VZ_COPY_RW_TO_UT and VZ_DUPLICATE_LAYER which are two of five possible API that use FSL2.VZ_DIFF_PTCH. In SVSconst.cs I've got comments after each constant for which function, or situation, uses.

Conclusion

Parts 2 and 3 of this guide covered the new features for managing layers in SWV, with Patch, Clone and Sub-layer Merging you have a wide array of tools for updating and testing layers in any environment. With Part 4 I'll go into layer actions such as Deactivate When Last Process Exits, and Auto Run from Layer.

Return to the Virtualization SDK Book