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

SVS 2.X SDK Guide Part 1: Intro and Initializing SVS

Created: 15 Apr 2008 • Updated: 29 Jul 2010
Language Translations
Jordan's picture
0 0 Votes
Login to vote

This article will be discussing how to use the SVS APIs in .Net C#. It references the FSL2 class I'm writing which can be downloaded here and is meant to show how the API work and what you can do with them. You should also have the latest version of FSLLIB.HLP that's available with the SDK -- for reference -- as I may not cover everything for each method.

The code in this article is done in C# and the class used is a .Net one. However, for those using just the SDK and C++ this article will still be useful because I'll cover what the methods do and why or when you might want to use them -- you'll just have to change some code around to get examples to work.

To get any of the API to work you need to import the DLL they are in and then marshal everything in. This can be quite a complicated process even though it doesn't take up many lines of code. I won't be covering how you marshal in unmanaged code to C# because I don't think I could do the complicated subject much justice. However, it is sufficient to say that when importing a DLL you need to be very careful of what variable type you're converting to and if you need to use the ref keyword for pointers or not.

It's recommended that you don't change anything in the FSL2 class, unless you're familiar with using unmanaged code in .Net. Not all of it is dealing with the imported DLL such as the constructor I added that will be discussed in this article.

FSL2 Class

The FSL2 class is divided up into 2 separate CS files:

  1. ManagedSVS.cs
  2. SVSConst.cs

ManagedSVS is where most of the magic happens. This is where the fsllib32.dll is imported and all the marshaling is done. You'll notice that System.Runtime.InteropServices is being used, this is the Namespace where all the marshaling and DLL import methods are contained. There's not a reference that needs to be added to use this Namespace.

All the SVS API are named the same thing except those that start with FSL2 (which is almost all.) These are named the same as you'd find in the help file except the prefix FSL2 is missing. Why? Well I thought it was pointless, and a little annoying, to have to type FSL2 (the name of the class) then FSL2functionname. The only reason for the FLS2, was to designate the function, was for SVS, which our class name takes care of quite well. So I've removed the FSL2 from all the contestants, methods, structures and the like because it was redundant to have it.

SVSConst.cs is a file that contains all the constants that are used in SVS, these are named the same as if you were coding in C++ but again, as above, missing the prefix "FSL2" for the same reason. Any variable that's typed in all caps is a constant.

Return Code

Unless otherwise noted all FSL2 functions return 0 for success and any other possible SVS error code for a failure, these are type UInt32.

Starting SVS up

SVS needs to be initialized before most of the APIs can be used, this required getting the product key and verifying it with the driver. It's a rather simple process that most people forget to do when they first start developing with the SDK. To initialize SVS we need to call two functions: getProductKey and initSystem. GetProductKey requires you to pass in SVS's Product ID number, this is contained in the constant PRODUCT_ID_SVS and then returns the Product Key.

FSL2GetProductKey Method

Fsl2.getProductKey
(
  int ProductId, 
  StringBuilder buffer, 
  int cbProductKeyBuffer
)

To get the product key we'll need a StringBuilder type set to the length constant MAX_KEY_LENGTH. This is where the returned product key will be saved. To retrieve the key we need to pass into getProductKey a product ID (constant), the recently created stringbuilder and then the size of the stringbuilder.

FSL2InitSystem

Fsl2.initSystem
(
  string origProductKey, 
  int productId, 
  ref UInt32 numDaysRemaining
)

Once we have our product key we need to use it to initialize the system, this is done with initSystem. This method will check with the driver to see if your product key is still valid and if so return the number of days remaining (if a demo version) on your license as well as "turning on" the driver for use with your app. If it there's anything wrong with your key it will return many possible error codes (see SDK documentation for more) that will tell you why the initialization didn't work.

FSL2.initialize

With the FSL2 I'm trying to keep it as close to the actually C++ library as possible by not adding any of my code, however there will be some of my own stuff there. One such method is the FSL2.Initialize method which takes the two methods discussed below and places them into a prebuilt method for easy use. I did this because this is something that everyone will want and can be a little on the complicated side to get everything working correctly. With this method I'm not checking against numDaysRemaining that's references with the initSystem method because I don't really care to return how many days are left on a key so that's something to change if you want.

FSL2.initialize Method

StringBuilder productKey = new StringBuilder(MAX_KEY_LENGTH);
           UInt32 numDays = 0;
           if (ERROR_SUCCESS == getProductKey(PRODUCT_ID_SVS, productKey, productKey.Capacity))
           {
               UInt32 status = initSystem(productKey.ToString(), PRODUCT_ID_SVS, ref numDays);
               if (status == ERROR_SUCCESS || status == PRODUCT_KEY_VALID)
               {
                   return true;
               }
               else
               {
                   return false;
               }
           }
           else
           {
               return false;
           }
       }

You've probably noticed that inside the initialize function I'm not use FLS2 in front of anything, that's because it's used inside the class instead of somewhere else, if you want to remove it from the class remember to add FSL2 in front of every method and constant (all cap words).

The reason it's inside the class is I've added the initialize method to the FSL2 constructor so as soon as you create a new object of type FSL2 (which you'll have to do for many things) everything gets set for you. I'm not checking to see if initialize returns true or false because I wanted to leave that up to you to decide how you'll handle that error since everyone has their own way of doing things like that. As long as you remember to create a new FSL2 object you'll never have to worry about initializing the driver to work with your app.

Other methods

There are a few other methods that go along with initializing the system or checking things that you may want to know before your app is run.

FSL2GetDriverVersion

FSL2.getDriverVersion
(
  ref UInt32 Version1, 
  ref UInt32 Version2, 
  ref UInt32 Version3, 
  ref UInt32 Version4
)

The get driverVersion method returns 4 different versions, each one is a part of the total version number, for example 2.1.2084, Version1 would be the 2, Version2 would be the 1 and Version3 would be 2084. Version4 is a success checker and returns 0 if the method was successful even though the method itself does the same thing (like all FSL2 methods).

FSL2GetLibraryVersion

FSL2.getLibraryVersion
(
  ref UInt32 Version1, 
  ref UInt32 Version2, 
  ref UInt32 Version3, 
  ref UInt32 Version4
)

FSL2.getLibraryVersion is the same as FSL2.getDriverVersion except it returns the version of fsllib32.dll which should be the same as the driver though if you just updated SVS you won't see the change in the driver's version until after you restart.

FSL2GetProductVersion

FSL2.getProductVersion()

This method returns the Product Version, which is 71, instead of 0 for success. If you remember we're passing in a product version constant PRODUCT_ID_SVS into both getProductKey and intSystem which is 71. You can use either that constant or this method to retrieve the needed version.

FSL2ProcessProductKey

FSL2.processProductKey
(
  string origProductKey, 
  int productId, 
  ref int numDayRemaning
)

FSL2.processProductKey takes a product key and checks to see if it's valid and how many days are remaining. This is what FSL2.initSystem does as well but FSL2.processProductKey doesn't initialize the driver. If you want the app to be able to check license information after starting this may be the favorable way to do it, especially if you either don't want to initialize the driver or have already done so.

FSL2SetProductKey

FSL2.setProductKey 
(
  int productId, 
  string productKey
)

Lastly is FSL2.setProductKey which takes a product ID and productKey and will set the productKey as the new one used by SVS, useful if you just changed licenses with SVS and need to change this across the board or want to add a register window to your app.

Conclusion

I realize that some people will be a little disappointed with this article not going into common SVS features, but there are more articles on their way that will, hopefully, cover what you want to know. The information here is meant to be the spring board into all the others and provide you with the knowledge you need to start using either the SDK or the FSL2 class. Part Two will cover Common Methods such as Activate, Delete, Reset and so on.

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