Video Screencast Help
Symantec to Separate Into Two Focused, Industry-Leading Technology Companies. Learn more.

SWV 6.1 SDK Guide Part 1: Intro & Function Changes from SVS

Created: 28 Jul 2009 • Updated: 29 Jul 2010 | 6 comments
Language Translations
Jordan's picture
+3 3 Votes
Login to vote

In SWV 6.1 (formerly SVS) several new useful features have been added. Like the SVS SDK documentation I wrote, this will mostly cover the usage of SWV 6.1 in .Net - C# to be specific - but this information will still be useful to unmanaged code developers. I plan on adding to it as new versions of SWV come out, if there are any new API For 6.1, but I can't promise the timing will be as soon as the new update to SWV is out. In SWV there have been a few changes to existing functions -such as export - as well as the following new features: Patching, Rest Point (layer Merging),Isolation, Dependent Layers, Deactivate on Last Process Exit, Auto Run Process and Keep in layer. With the exception of Keep in layer, whose API won't be fully functional until a later version of SWV, all of these new features will be covered over the next few articles.

Since SWV is a newer version of SVS all the functions I covered in Managed SVS SDK Documentation will work with SWV with no change, so all your existing code will work with SWV 6.1. In this first collection of articles I plan on covering all the changes to existing SVS functions that are SWV specific as well as how to write a program that will work with both SVS 2.1 and SWV 6.1 using the same FSL2 Class. And because it's possible to use the same class for both versions I'm going to be updating the existing class that I made available for SVS a year ago with all the new SWV 6.1 methods.

With SVS all the API were stored in the library fsllib32.dll but with SWV most of the new API are stored in vzlib.dll, so SWV uses both libraries and you'll need to remember to reference both of them. If you're using the Managed C# class you won't have to worry about this. FSLlib32.dll is similar, but not the same in SWV as we've modified a few API for SWV, you can still make references to the 2.1 API in your application but there are a few things you'll need to consider which we'll cover in this article.

Changes to the FSL2 Class

A lot of constants have been added SVSconst.cs, I'm trying to get all of them in there that people might need to use, and more of these will be added as time goes on. The most important are the new constants for ExportEX.

FSL2Info has been updated in SVSStruct.cs with new items for SWV 6.1

In Managed SVS ExportEX has been added.

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

Exporting without User SIDs

One of the most asked for features has been added to SWV, which is the ability to export a layer with no user information in it. With ExportEx you can now pass in a flag that will strip out all User SIDs from a layer and the layer will stay clean after an import until someone activates it.

FSL2ExportEx

public static extern UInt32 ExportEx
(
  string fslGUID,
  string archivePath,
  IMPEXP_INFO_FUNC RTInfoFunc,
  ref IMP_EXP_V1 pUserData,
  UInt32 structureVersion,
  UInt32 flags
);

ExportEx is not new to SWV, it's been in SVS for years but I didn't include it in the original SVS SDK documentation because it didn't add anything to what you could do over regular Export. Now with SWV there is a difference, and any new features we add to export will most likely go into this function and not Export, which is the afore mentioned export with no user information.

ExportEx behaves much like Export, so for a full explanation of how to use Export please see part 3 of the SVS SDK documentation, with the exception of the bool for replaceIfExsits has been replaces with the flags parameter. Currently there are two flags, both constants defined in SVSconst.cs, named LAYER_REPLACE_IF_EXISTS and STRIP_SID_INFO_FROM_LAYER that you can pass in. If you want to have both options you combine them with the + symbol. Since ExportEx is a SVS 2.X function you can use it with earlier versions as long as you don't use the STRIP_SID_INFO_FROM_LAYER flag since that's a SWV 6.1 feature.

Changes to vzGetLayerInfo

As I mentioned in the changes to the FSL2 Class the Info structure has 2 new items in it: Flags and Visibility Flags.

FSL2Info

public class Info {
  public UInt32 dwStructSize;
  bool bIsGroup;
  public UInt32 dwLayerType;
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)] public string name;// FSL2_MAXNAMELEN
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)] public string peerName;// FSL2_MAXNAMELEN
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)] public string regPath;// FSL2_MaxReg
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)] public string fileRedirPath;// FSL2_MaxPath
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)] public string regRedirPath;// FSL2_MaxReg
  public UInt32 active;
  public UInt32 activeOnStart;
  public UInt32 enabled;
  public UInt32 majorVersion;
  public UInt32 minorVersion;
  public UInt32 lastActivatedTime;
  public UInt32 createTime;
  public UInt32 lastRefreshTime;
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 200)] public string fslGUID;// FSL2_MAXIDLEN_BYTES
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 200)] public string peerGUID;// FSL2_MAXIDLEN_BYTES
  public UInt32 compressionLevel;
  public UInt32 flags;
  public UInt32 visibilityFlags;
}

VisibilityFlags are for Isolation and have been added to SVSconst.cs and you can get the same information from FSL2GetLayerVisibility (discussed in a later article) and while you could use FSL2SetLayerInfo to change this value that's not recommended. Remember that there are 3 visibility flags that can be added up for a numerical representation of a layer's status and you'll have to parse this information - which I'll cover more when I cover the Isolation API. Lastly flags are for other flags that a layer may have, as of this writing that's only FSL2_Layer_DEACTIVATE_UPON_LAST_PID which is for Deactivate on Last Process Exit (discussed in a later article).

The FSL2Info structure represents an interesting conflict between SVS 2.1 and SWV 6.1 as the structures are a different size and you can't overload a class/structure in .Net or C so you would think you have to define the structure for SWV or SVS if you plan on using this. Not so. If you go back and read Part 4 of the SVS SDK Documentation you remember that you need to define the size of the structure with this code:

mySVS.pInfo.dwStructSize = (UInt32) Marshal.SizeOf(mySVS.pInfo);

Well if you're using a product that you want to work with both 2.1 and 6.1 you can check for which version (discussed later in this article) and then run this code instead:

mySVS.pInfo.dwStructSize = (UInt32) Marshal.SizeOf(mySVS.pInfo)-8;

Each item we add to the structure is only 4-bytes in size so we're just subtracting the two new items and it will get defined to the correct size.

Detecting Virtualization Version

Detecting what version a user has installed is rather simple and I covered the function you'll need to use back in Part 1 of the SVS SDK Documentation, specifically FSL2GetDriverVersion.

FLS2GetDriverVersion

public static extern UInt32 getDriverVersion
(
  ref UInt32 version1,
  ref UInt32 version2,
  ref UInt32 version3,
  ref UInt32 version4
);

This function returns four different version numbers of which we are only interested in two, version1 and version2. Version1 is the 2 in SVS 2.1 or the 6 in SWV 6.1 this is the best way to tell what code path you should use. Version2 is the second number after the first dot and isn't that important right now but if there are changes between 6.1 and 6.2 that require this method this is how you'd do it. Version3 covers the information after the second dot so 2.1.3071 or 6.1.4063 which is what's incremented for service packs and hotfixes. Version4 is currently not used with SVS or SWV builds but may be in the future.

Deprecated API

FSL2SetShellRefreshFlag and FSL2GetShellRefreshFlag, as well as the enumeration eFSL2_SHELL_REFRESH_FLAG, have been deprecated in 6.1. I didn't cover these API in the SVS 2.1 SDK Documentation but they basically allow you to set when SVS would do Desktop refreshes after certain actions (activate, deactivate and so on) and now all this behavior is handled by the driver which determines the most resource friendly way to do desktop refreshes. So, for example, if you try to activate four layers at once instead of doing 4 desktop refreshes the driver will do only one after the last activate is finished.

A Note on the FSL2 Class

If you look at ManagedSVS.cs or SVSStrcut.cs you'll notice that I don't do any version checking and yet the same code will work with SVS 2.1 or SWV 6.1. The reason is that the program assumes that all the information exists in the libraries and it actually doesn't check until it attempts to invoke those methods or structures. So as long as you don't call any SWV 6.1 code on a machine with SVS 2.1 installed no exceptions will be thrown. This allows us to write one application that can work with both products.

Seeing it in Action

Below is some simple sample code that shows how to use FSL2GetDriverVersion.

static string getDriverVersion()
{
  FSL2 mySVS = new FSL2();
  UInt32 version1 = 0;
  UInt32 version2 = 0;
  UInt32 version3 = 0;
  UInt32 version4 = 0;
  FSL2.getDriverVersion(ref version1, ref version2, ref version3, ref version4);
  return version1.ToString() + "." + version2.ToString() + "." + version3.ToString();
}

This is a pretty simple function, it returns a string of a full SWV or SVS build. The only thing to really note is that you need to define all of your version variables before you call the function.

Conclusion

This article barely scratches the surface of SWV 6.1 and all the new features added, it does, hopefully, the basic differences between SWV and SVS and how you can use the SDK to write for both products. Part 2 will cover Patching.

Remember that future versions will be listed in the FSL2 Class portal where the FSL2 class is available for download so be sure to subscribe to that thread which will inform you of any new articles and updates to the class.

Return to the Virtualization SDK Book

Comments 6 CommentsJump to latest comment

Scot Curry's picture

I don't know how you get the time to put out so many great articles, but I really do appreciate it.
Scot 

+2
Login to vote
Jordan's picture

I tend to write them over several months and then release them all at once when they're time sensitive like 6.1 articles.

If a forum post solves your problem please flag is as the solution

+1
Login to vote
spazzzen's picture

So is SWV 6.1 finally and officially released?  Not a RC right?

0
Login to vote
Scot Curry's picture

You can get the latest from the Symantec Downloads page.  We have even released a service pack and a hot fix.

0
Login to vote
Jordan's picture

There's been no service pack released yet.

If a forum post solves your problem please flag is as the solution

+1
Login to vote
Scot Curry's picture

Jordan is correct (as always).  We have released a Maintenance Pack.  Thanks for the catch.

0
Login to vote