Filename Macros

Filename Macros

Thinstall filename expansion macros are used to express paths where parts of the path string are not known until the program has installed and is running. .

Expansion macros include the following substrings that can be embedded in a longer string. The macro portions of the string will be expanded by Thinstall to their true value, while the rest of the string is left unchanged.

Thinstall specific macros

%InstallPath%

The directory where the current running exe is located.

( How to obtain this value in your program)

example: c:\program files\myprog \test.exe (does not include trailing backslash)

%ProgramName%

The name of the current EXE with extension, but without path.

example: c:\program files\myprog\ test.exe

%BaseName%

The name of the current EXE without extension or path.

example: c:\program files\myprog\ test .exe

%VersionId%

This macro is only available if Thinstall's installer is used. %VersionId% will expand to the "Program Indentification String" value you entered in the Version Tab in the Install dialog.

This macro is typically used in conjunction with %Programs% to specify a StartMenu shortcut link path locations. For example:

If Program Indentification String is set to "Thinstall Studio", then the filename macro:

%Programs% \ %VersionId% \ %ProgramName%

will expand to the something similar to the following:

C:\Documents and Settings\All Users\Start Menu\Programs \ Thinstall Studio \ Thinstall.exe

%Cwd%

The current working directory when the program first began execution. If the current working directory is later changed by the program, the files retain the original expansion.

%Temp%

The Windows TEMP directory for the current user. Windows determines the Temp directory by consulting the Environment Variable TEMP.

$EnvVar$

The value of the Environment Variable "EnvVar"

example: $PATH$ = c:\windows;c:\windows\system32;....

Windows Macros - Macros that are derived from the system registry keys

Macro values are derived by consulting three locations:

By calling ShGetFolderPath() from shfolder.dll (see notes below: this may note exists on some versions of windows)

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders

For various versions of Windows, some of these registry macros might not exist, fall-back substitution: indicates which macro is used when the registry key is missing.

%ProgramFilesDir%

The non-hardcoded version of c:\program files

%Common StartMenu%

Where application can place StartMenu shortcuts at the top level

Windows NT example=C:\Documents and Settings\All Users\Start Menu)

Applications should use %Common Programs% to place shortcuts under Start Menu\Programs.

%StartMenu%

Path where Start Menu is located for the current user

%Common AppData%

Where the application should place data meant to be shared with All Users.

Windows NT example=C:\Documents and Settings\All Users\Application Data

fall-back substitution = %InstallPath%

%Local AppData%

Where application should store machine local application data

Windows NT example=C:\Documents and Settings\Username\Local Settings\Application Data)

fall-back substitution = %InstallPath%

%AppData%

Where the application should place data to be accessed by the current user.

Windows NT example=C:\Documents and Settings\UserName\Application Data

fall-back substitution = %InstallPath%

%Common Desktop%

Where the application should place desktop shortcuts for All User.

Windows NT example = C:\Documents and Settings\All Users\Desktop

fall-back substitution = %Desktop%

%Desktop%

Specifies the path to the current user's desktop

%Common StartUp%

Where the application should place startup shortcuts for All User.

Windows NT example = C:\Documents and Settings\All Users\Start Menu\Programs\Startup

fall-back substitution = %StartUp%

%Startup%

Specifies the directory where objects are run after login for the current user.

%Common Programs%

Where the application should place startup shortcuts for All User.

Windows NT example = C:\Documents and Settings\All Users\Start Menu\Programs

fall-back substitution = %Programs%

%Prog rams%

The non-hardcoded version of %StartMenu%\Programs

example = C:\Documents and Settings\UserName\Start Menu\Programs

Designed for Windows XP Logo requirements ask you to use %Common Programs% instead of %Programs% so shortcuts are visisble to all local users.

%Common Favorites%

All User's favorites directory.

fall-back substitution = %Favorites%

%Favorites%

Current User's Favorites directory

Requires shfolder.dll 5.0

%SystemSystem%

The OS independent version of c:\windows\system32

Windows 95 example: c:\windows\system

Windows 98 example: c:\windows\system32

Windows NT example: c:\winnt\system32

%SystemRoot%

The OS independent version of c:\windows

Windows 95/98/ME/XP example: c:\windows

Windows NT example: c:\winnt

%Personal%

Specifies the "My Documents" folder for the current user

Requires shfolder.dll 5.0

%Fonts%

System Fonts directory

Requires shfolder.dll 5.0

%NetHood%

Current User's NetHood directory

Requires shfolder.dll 5.0

%Recent%

Current User's Recent directory

Requires shfolder.dll 5.0

%Templates%

ShellNew directory

Requires shfolder.dll 5.0

%SendTo%

Current User's Sendto

Requires shfolder.dll 5.0

%Profile%

The user's profile folder. A typical path is C:\Documents and Settings\ username.
Requires shfolder.dll 5.0

%Profiles%

The file system directory containing user profile folders. A typical path is C:\Documents and Settings.
Requires shfolder.dll 6.0

When are Macros expanded?

Macros are expanded when your program first loads and remain fixed for the rest of the program execution. Thinstall does not expand any macros after your program loads, all API functions that are handled by Thinstall expect fully qualifed paths. For example OpenFile("%installpath%\test.dat"); will fail. Inside your program you can only use real filenames.

Examples

Starting Working Directory	Program EXE location	Virtual filename	Runtime Expanded result
c:\otherdir	c:\program files\myprog\test.exe	%cwd%\data.txt	c:\otherdir\data.txt
c:\otherdir	c:\program files\myprog\test.exe	%InstallPath%\data.txt	c:\program files\myprog\data.txt
c:\otherdir	c:\program files\myprog\test.exe	%InstallPath%\%basename%.dat	c:\program files\myprog\test.dat
c:\otherdir	c:\program files\myprog\test.exe	%InstallPath%\%programname%.dat	c:\program files\myprog\test.exe.dat
c:\otherdir	c:\program files\myprog\test.exe	x:\mydir\test.dat	x:\mydir\test.dat

How do obtain %InstallPath% inside your program.

%InstallPath% always equals the value of the path where the Thinstall created EXE is located while it is running. In the case where your main Thinstall EXE executes a second bundled EXE file located at a different virtual path, the value of %InstallPath% remains pointing to the original EXE subdirectory.

The method of determining the subdirectory where your EXE is running may vary. In C++, the code looks similar to this:

Obtaining %InstallPath% manually

char buf[_MAX_PATH];
GetModuleFilename(GetModuleHandle(0), buf, sizeof(buf)); // get the name of the running EXE
char *last_slash=0;
for (char *sptr=buf; *sptr; sptr++) // located last slash
if (*sptr=='\\')
last_slash=sptr;

*last_slash=0; // chop off last slash and EXE filename
char *install_path=buf; // remaining string is InstallPath

Obtaining %InstallPath% through EnvironmentVariables.

Using Thinstall, you can add an environment variable INSTALLPATH = %InstallPath%. When this is set using Thinstall's environment variable system, the value of %InstallPath% will be expanded and placed in the environment variable INSTALLPATH before your program starts. You can then query the environment variable INSTALLPATH to obtain the expanded value. In C++, you can read an envrionment variable like this:

char buf[_MAX_PATH];
GetEnvironmentVariable("INSTALLPATH", buf, sizeof(buf));

*note: you have to add the variable INSTALLPATH to your Thinstall project in order for this to work.

Windows 95 / 98 Compatabiliy Notes

Thinstall obtains the path for special folders such as "%Common AppData%" using 2 methods:

Method 1: Use shfolder.dll to obtain the path.

On windows 95 shfolder.dll does not exist, so this method may be skipped.

On windows 98 the version of shfolder.dll installed may not support the Folder Path you desire, for more details on which Folder Paths are supported for which versions of shfolder.dll, see this link:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/enums/csidl.asp

Method 2: Use the registry keys found at HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Current Version\Explorer\Shell Folders

On many versions of Windows, the desired Folder Path registry key may not exists

Compatability Solution

Include a copy of shfolder.dll in your Thinstall project, preferably version 5.0 or higher. By including this DLL in your project, the EXE size will only become about 15K larger, and Thinstall will be able to preform macro expansion on all the folder paths listed above. You should include a copy of shfolder.dll in your project if you use any of the following macros (and wish to support Windows 95/98)

Macros that may require shfolder.dll 5.0 or higher to be included

%Common StartMenu% %StartMenu%
%Common AppData% %Local AppData% %AppData%
%Common Startup% %Startup%
%Common Programs% %Programs%
%Common Favorites% %Favorites%
%SendTo%
%Templates%
%Recent%
%NetHood%
%Fonts%
%Personal%
%Profile%

Macros that may require shfolder.dll 6.0 or higher to be included
%Profiles%

Note: Thinstall's .NET Framework Import feature will automatically include shfolder.dll in your project for you.