Installing FalconView Client Editors

As discussed in the FalconView SDK, in order to install FalconView client editors, it is necessary to add an entry to the client editors registry key (under "HKLM\Software\PFPS\FalconView\Client Editors").  The trick with installing a client editor key is that the installer must determine which client editor number to use for the key.  I recently wrote a new FalconView overlay in C# .NET and thought I'd share some steps that other developers may find useful for installing FalconView overlays.  (I'm working in Visual Studio 2005, so the steps below are for that version.  These steps are somewhat broad as I assume that the developer is experienced enough to fill in some of the details.  I also assume that the overlay is being written in .NET as this example uses all .NET classes and assemblies.)

1.  Create a new Setup Project Using Visual Studio and Add Your Binaries to the Setup

I'll leave most of this work to the reader as this post is not meant to address this part of the setup.  Suffice it to say that you add your project outputs to a new setup project in a conventional fashion so that they get installed to the desired location on the user's PC.

2.  Add an Installer Class to Your Output Assembly

An installer class derives from System.Configuration.Install.Installer.  Installer classes have a number of methods that you can override in order to execute steps at certain points during an install.

3.  Add Code to Your Installer Class to Register Your Assembly for COM

FalconView uses COM to communicate with all its client editors.  This function is a short sample that shows how you can add a method to your installer class that will register your assembly for COM so that FalconView can find your overlay class.

private void RegisterAssembly(string assemblyFile)

{

  Assembly assembly = Assembly.LoadFrom(assemblyFile);

  new RegistrationServices().RegisterAssembly(assembly,

     AssemblyRegistrationFlags.SetCodeBase);

}

4. Add Code to Your Installer Class to Set the Client Editor Key

Here's the meat of this post.  The following method sets the client editor key so that your overlay becomes visible to FalconView.

private void InstallClientEditorKey(

   string classIdString, int interfaceVersion, bool isStaticOverlay)

{

   // get the FalconView client editors key

   RegistryKey clientEditorsKey = 

      Registry.LocalMachine.OpenSubKey(

      @"SOFTWARE\PFPS\FalconView\Client Editors", true);

   // create a list of taken client editor numbers

   List listTakenNumbers = new List();

   string[] subKeys = clientEditorsKey.GetSubKeyNames();

   foreach (string subKeyName in subKeys)

   {

      try

      {

         listTakenNumbers.Add(Int32.Parse(subKeyName));

      }

      catch (Exception) { } // probably just a key that isn't an integer

   }

   // find the first available client editor number

   int iFirstAvailable = 0;

   while (listTakenNumbers.Contains(iFirstAvailable))

      iFirstAvailable++;

   // create the client editor key

   RegistryKey overlayKey = 

      clientEditorsKey.CreateSubKey(iFirstAvailable.ToString());

   // create the values

   overlayKey.SetValue("classIdString", classIdString,

      RegistryValueKind.String);

   overlayKey.SetValue("interfaceVersion", interfaceVersion,

      RegistryValueKind.DWord);

   overlayKey.SetValue("isStaticOverlay",

      isStaticOverlay ? 1 : 0, RegistryValueKind.DWord);

   // clean up

   overlayKey.Close();

   clientEditorsKey.Close();

}

5. Call Your Methods From an Overridden Method in Your Installer Class

I choose to override the Install method on the installer class.  (For more documentiontation on Installer classes, consult MSDN.)

public override void Install(IDictionary stateSaver)

{

   try

   {

      base.Install(stateSaver);

      // register the assembly for COM

      RegisterAssembly(Context.Parameters["assemblypath"]);

      // install the FalconView client editor key

      InstallClientEditorKey("Server.Overlay", 3, true);

   }

   catch (Exception ex)

   {

      MessageBox.Show(ex.Message,

         "Install Failed", MessageBoxButtons.OK,

         MessageBoxIcon.Error);

   }

}

Note the use of Context.Parameters above.  This dictionary is how all of the install parameters are passed into an Installer class by the installer.

6. Add the Custom Action to Your Setup Project

When you add the custom action, you will need to specify the entry point for the action.

This screen capture shows where to set the EntryPoint property on the custom action.  When your install reaches the custom action, it will call into your Installer class and execute the actions there.

You could add additional logic to your install, such as checking to make sure the overlay isn't already installed and adding uninstall steps, but I'll leave that as an exercise for the reader.