wiki.mbirth.de

All you never wanted to know

View on GitHub
:new: 2009-09-12 :wavy_dash: :up: 2009-09-12

U3Helper Tutorial

Diese Seite auf Deutsch.

You might want to read the U3 Basics first.

How to convert an application to U3

Example Application: IVOS
Tools used: Sandboxie, regedit, Total Commander (for file management and compression), notepad

Let’s start with installing IVOS into the sandbox. Since it’s using Microsoft’s Installer, you have to first start it inside the Sandbox.

Open Sandboxie Control (the yellow icon in your systray) and select menu FunctionRun SandboxedWindows Installer Service. Now search the setup_ivos.exe, right-click and select Run sandboxed. This should install IVOS into the sandbox.

After installation, find your Sandboxes contents. In Sandboxie Control select menu FunctionContents of sandboxExplore contents. An Explorer-window should pop up and you should see two directories drive and user as well as two files RegHive (maybe only one of them is shown). Below drive is the changed(!) content of your local drives. Every file a sandboxed program changes or writes goes there. All other files stay in their regular locations. So you can easily see, what files the installation of IVOS added or changed.

Most interesting there is everything below drive\C\Program Files\CommunX - these are the main files of IVOS. There’s one .xml file, which might be modified by IVOS (.xml-files are often used for configuration data), but the other files seem static (.dll and .exe).

Now create an empty directory somewhere and in there, create 3 other folders: data, host and manifest. The .xml-file goes to the newly created data directory. Those 4 other files go to host.

So far for the file-part. Let’s get to the tricky part: Finding out, which registry entries the program uses. 99,9% of all programs use a branch like HKEY_LOCAL_MACHINE\Software\<company> or HKEY_CURRENT_USER\Software\<company>. Since we installed it to the Sandbox, in Sandboxie Control, select menu FunctionRun SandboxedAny Program… and enter regedit into the field before clicking OK. Now regedit pops up and you can start browsing the registry. Looking under HKEY_LOCAL_MACHINE\Software, there’s nothing like ComunX or even IVOS. So let’s take a look at HKEY_CURRENT_USER\Software … and there it is: a key (registry-term for “folder”) named ComunX.

Let’s export this initial data for our U3-package: click once on the ComunX-key and select menu FileExport. Now name the file regdata1 and save it to the root folder of drive C:. Since we’re inside the Sandbox, you’ll find that file by the Explore contents option in Sandboxie Control. It’s in \drive\C\regdata1.reg . Copy that file to our data-folder.

Now right-click the file (in the data-folder) and select Edit. Notepad will open with the registry file loaded.

Find the line:

"apppath"="C:\\Program Files\\ComunX\\IVOS\\"

Now some U3-basics: The U3 LaunchPad stores some paths inside environment variables. This is, so that applications can find their data although it is stored in different locations on different PCs. The most important are %U3_HOST_EXEC_PATH% which contains the path to the directory, where application files go to and %U3_APP_DATA_PATH% which is the directory on the U3 stick which contains data for that application.

So since U3 doesn’t install the application to C:\Program Files\ComunX\IVOS, we have to insert the correct path there, which is %U3_HOST_EXEC_PATH%. So change the line to:

"apppath"="%U3_HOST_EXEC_PATH%\\"

Leave everything else as it is. Save the file.

Now copy U3Helper.exe to the host-directory. Also put the U3Helper.ini in there. I usually copy one from another application and modify it. I already made all necessary modifications for IVOS. Take a look at the ini-file. First comes the line [U3Helper] followed by a friendly name of the application and the executable file which should be started. This is Launcher.exe for IVOS. The next interesting entry is that below [RegBackup]. As you can see this is the registry path, we just found out. U3Helper imports these from the regdata1.reg file upon launch of the application and exports them back to that file, when you “eject” the U3-stick. All U3-environment-variables found in these registry entries get resolved to their actual data. So the %U3_HOST_EXEC_PATH%\\ we added gets resolved to C:\Documents and Settings\<username>\Application Data\U3\Apps\{12345678-1234-1234-143123123}\Exec - so that IVOS will see the real path to itself. The first line below [RegBackup] gets saved to a file regdata1.reg, the second entry (if there) to regdata2.reg, and so on.

Some lines further down you’ll find [DataToExecDir] and the entry ivos.xml. This is the .xml-file we put into the data (%U3_APP_DATA_PATH%) directory. And this line tells U3Helper to copy it over to the executables directory (%U3_HOST_EXEC_PATH%) upon IVOS-launch and back to the data-directory on the stick, when ejecting.

These are all configuration lines in U3Helper.ini. The remaining lines are mostly default data and some explanations.

Now extract IVOS’ application icon so that it can be shown in LaunchPad. You may use Icon Sucker. I for myself use a plugin for Total Commander. Put the Icon-file (.ico) into the manifest-directory.

Save the attached (see below) manifest.u3i to that same directory. I already prepared it. Usually I’d copy a manifest from another program and modify it accordingly. Most important is to generate a unique GUID (the long number in the seconds line). There’s a nice web tool to do so: UUIDgen. Also, Microsoft provides some tool somewhere and the U3 Manifest creator (from http://www.u3.com) also generates such GUIDs.

After changing the GUID (or UUID as it is sometimes called), fill in the rest of the data. The version number can be found by right-clicking the ivos.exe and selecting Properties. There you have a Version-tab, which shows version 2.0.2.0 - so set the string in the manifest to it.

Set the webpage, developer name and description. And now, most important, set the file to launch the application. This is the line with the appStart-command. You start IVOS with the Launcher.exe and this file will be in %U3_HOST_EXEC_PATH% as we learned. So to start IVOS, the computer has to start %U3_HOST_EXEC_PATH%\Launcher.exe. This is, what the line says.

The other lines can remain untouched. These are U3Helper-commands. Since we told U3Helper what to do through the U3Helper.ini file, there’s nothing left to change here. Oh, one single thing: the minFreeSpace-value should be the storage space required on the U3-drive to install IVOS. Since the whole package gets smaller after compression, just guess a value based upon the size of the host-directory.

I think we’re ready now. Use a ZIP-utility (like WinZip) to compress the 3 folders host, data and manifest into a ZIP file. Make sure, the ZIP file only has those 3 folders (and it’s subfolders, if any). The directory structure should look like this:

  • 📂 data (Directory)
    • 📄 ivos.xml (File)
    • 📄 regdata1.reg (File)
  • 📂 host (Directory)
    • 📄 ivos.chm (File)
    • 📄 Ivos.exe (File)
    • 📄 ivossapi.dll (File)
    • 📄 Launcher.exe (File)
    • 📄 U3Helper.exe (File)
    • 📄 U3Helper.ini (File)
  • 📂 manifest (Directory)
    • 📄 IVOS.ico (File)
    • 📄 manifest.u3i (File)

The only thing left to do is to rename the .zip-file to .u3p, so that you have a file IVOS.u3p or maybe IVOS_U3.u3p. You should be able to install this to the U3 stick. I attached everything so that you may play around. I hope that IVOS stores the registration info in the registry in that key we found out otherwise we have to look into it to find out, how to retain the registration info between different PCs. And remember that IVOS only works, if the Speech API 5.1 is installed on the host PC.

Loading Google+ comments…