Chris, John, Devs: Addressing the problem of Windows’ “Special folders”

I just came across a big problem in the Spybot S&D thread again, which should be addressed once and for all — if anyhow possible: Windows’ “Special Folders” like %APPDATA% or “All users Application Data”.

Windows addresses special folder locations via so-called CSIDLs, and starting from Vista, it uses what we call KNOWNFOLDERIDs. It is vitally important to use these instead of trying to hard-code stuff like

%ALLUSERSPROFILE%\Application Data\whatever

into PA installers. Because they will fail on many systems!

For instance, let’s take the “local application data” (an easy one):

On an English-language Windows XP system, this will (usually) be

C:\Documents and Settings\username\Local Settings\Application Data

On a German-language Windows XP, it would look like

C:\Dokumente und Einstellungen\username\Lokale Einstellungen\Anwendungsdaten

Or on a Spanish system

C:\Documents and Settings\username\Configuración local\Datos de programa

Or even

C:\Users\username\AppData\Local

if you’re running Windows 7 with the English locale active. See what I mean?

To further complicate things, some of them are now file system junctions under Windows 7, which have special access settings. (Actually, much like symlinks on Linux.) Plus, users do have the possibility to actually move some of these locations (like putting their personal profile data onto another drive).

It seems the only universally working way is to always ask the operating system for the real names and locations of these “special places”. Because that will always return correct results, and we could be sure that a Portable App will function correctly, be it under Windows XP, or a foreign-language Windows 7.

I lately had this discussion over at Piriform’s CCleaner Forum. You might want to read my article “Getting Special Folders right on ALL systems” over there. It also contains some VBScript code (yuk!) to show what should be done. (In a clumsy way, by setting up environment variables.)

I strongly feel that the Portable Apps Platform should do this right from the beginning. I haven’t had a look yet on which of the (possibly) needed variables the NSIS system already provides, but I strongly suggest we should have at least most of the CSIDL-based plus some of the KNOWNFOLDERID-based (Vista and newer) in order to provide users with the greatest and most glitch-free PA experience — even on foreign-language systems, and all versions.

Getting hold of these “special locations” from the operating system within some part of NSIS code, and providing them as variables to use in PA development would be great. (And much better than setting up a zillion large environment variables!) I offer my help in getting this straight.

Here’s a list of the ones I currently address with the environment variables set by my VBScript. We might need a few more to address each and every issue correctly, though. I strongly feel using the “official” special paths would make the developers’ and the users’ lives much easier …

---

1. VARIABLES THAT MAKE SENSE WITH PORTABLE APPS (YOU SHOULD USE THESE)

These are most useful to use with Portable Apps/NSIS file operations. They will access the "right" special folders on almost any Windows 2000, XP, Vista or 7 machine, independent of its locale settings.

%CDBurning% (CSIDL_CDBURN_AREA, 0x3b)

V6.0: The file system directory that acts as a staging area for files waiting to be written to a CD.
A typical path is C:\Documents and Settings\username\Local Settings\Application Data\Microsoft\CD Burning.

%CommonFavorites% (CSIDL_COMMON_FAVORITES, 0x1f)

The file system directory that serves as a common repository for favorite items common to all users.

%CommonOEMLinks% (CSIDL_COMMON_OEM_LINKS, 0x3a)

This value is recognized in Windows Vista for backward compatibility, but the folder itself is no longer used. I’ve seen it come back in Windows 7, though.

%CommonStartup% (CSIDL_COMMON_STARTUP, 0x18)

The file system directory that contains the programs that appear in the Startup folder for all users.
A typical path is C:\Documents and Settings\All Users\Start Menu\Programs\Startup.

%Cookies% (CSIDL_COOKIES, 0x21)

The file system directory that serves as a common repository for Internet cookies.
A typical path is C:\Documents and Settings\username\Cookies.

%DesktopDirectory% (CSIDL_DESKTOPDIRECTORY, 0x10)

The file system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself).
A typical path is C:\Documents and Settings\username\Desktop.

%Favorites% (CSIDL_FAVORITES, 0x06)

The file system directory that serves as a common repository for the user's favorite items.
A typical path is C:\Documents and Settings\username\Favorites.

%History% (CSIDL_HISTORY, 0x22)

The file system directory that serves as a common repository for Internet history items.

%InternetCache% (CSIDL_INTERNET_CACHE, 0x20)

V4.72: The file system directory that serves as a common repository for temporary Internet files.
A typical path is C:\Documents and Settings\username\Local Settings\Temporary Internet Files.

%LocalAppData% (CSIDL_LOCAL_APPDATA, 0x1c)

V5.0: The file system directory that serves as a data repository for local (nonroaming) applications.
A typical path is C:\Documents and Settings\username\Local Settings\Application Data.

%Music% (CSIDL_MYMUSIC, 0x0d)

The file system directory that serves as a common repository for music files.
A typical path is C:\Documents and Settings\User\My Documents\My Music.

%Personal% (CSIDL_PERSONAL, 0x05)

V6.0: The virtual folder that represents the My Documents desktop item. This is equivalent to CSIDL_MYDOCUMENTS.
Previous to V6.0: The file system directory used to physically store a user's common repository of documents.
A typical path is C:\Documents and Settings\username\My Documents.
This should be distinguished from the virtual My Documents folder in the namespace. To access that virtual folder, use SHGetFolderLocation, which returns the ITEMIDLIST for the virtual location, or refer to the technique described in Managing the File System.

%Pictures% (CSIDL_MYPICTURES, 0x27)

V5.0: The file system directory that serves as a common repository for image files.
A typical path is C:\Documents and Settings\username\My Documents\My Pictures.

%Profile% (CSIDL_PROFILE, 0x28)

V5.0: The user's profile folder.
A typical path is C:\Users\username.
Applications should not create files or folders at this level; they should put their data under the locations referred to by CSIDL_APPDATA or CSIDL_LOCAL_APPDATA. However, if you are creating a new Known Folder the profile root referred to by CSIDL_PROFILE is appropriate.

%ProgramData% (CSIDL_COMMON_APPDATA, 0x23)

V5.0: The file system directory that contains application data for all users.
A typical path is C:\Documents and Settings\All Users\Application Data.
This folder is used for application data that is not user specific. For example, an application can store a spell-check dictionary, a database of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
This information will not roam and is available to anyone using the computer.

%ProgramFiles% (CSIDL_PROGRAM_FILES, 0x26)

V5.0: The Program Files folder.
A typical path is C:\Program Files.

%ProgramFilesCommon% (CSIDL_PROGRAM_FILES_COMMON, 0x2b)

V5.0: A folder for components that are shared across applications.
A typical path is C:\Program Files\Common. Valid only for Windows XP.

%ProgramFilesCommonX86% (CSIDL_PROGRAM_FILES_COMMONX86, 0x2c)

%ProgramFilesX86% (CSIDL_PROGRAM_FILESX86, 0x2a)

%PublicDesktop% (CSIDL_COMMON_DESKTOPDIRECTORY, 0x19)

The file system directory that contains files and folders that appear on the desktop for all users.
A typical path is C:\Documents and Settings\All Users\Desktop.

%PublicDocuments% (CSIDL_COMMON_DOCUMENTS, 0x2e)

The file system directory that contains documents that are common to all users.
A typical path is C:\Documents and Settings\All Users\Documents.

%PublicMusic% (CSIDL_COMMON_MUSIC, 0x35)

V6.0: The file system directory that serves as a repository for music files common to all users.
A typical path is C:\Documents and Settings\All Users\Documents\My Music.

%PublicPictures% (CSIDL_COMMON_PICTURES, 0x36)

V6.0: The file system directory that serves as a repository for image files common to all users.
A typical path is C:\Documents and Settings\All Users\Documents\My Pictures.

%PublicVideos% (CSIDL_COMMON_VIDEO, 0x37)

V6.0: The file system directory that serves as a repository for video files common to all users.
A typical path is C:\Documents and Settings\All Users\Documents\My Videos.

%Recent% (CSIDL_RECENT, 0x08)

The file system directory that contains shortcuts to the user's most recently used documents.
A typical path is C:\Documents and Settings\username\My Recent Documents.
To create a shortcut in this folder, use SHAddToRecentDocs.
In addition to creating the shortcut, this function updates the Shell's list of recent documents and adds the shortcut to the My Recent Documents submenu of the Start menu.

%RoamingAppData% (CSIDL_APPDATA, 0x1a)

V4.71: The file system directory that serves as a common repository for application-specific data.
A typical path is C:\Documents and Settings\username\Application Data.
This CSIDL is supported by the redistributable Shfolder.dll for systems that do not have the Microsoft Internet Explorer 4.0 integrated Shell installed.

%Startup% (CSIDL_STARTUP, 0x07)

The file system directory that corresponds to the user's Startup program group.
The system starts these programs whenever any user logs on.
A typical path is C:\Documents and Settings\username\Start Menu\Programs\Startup.

%System% (CSIDL_SYSTEM, 0x25)

V5.0: The Windows System folder.
A typical path is C:\Windows\System32.

%SystemX86% (CSIDL_SYSTEMX86, 0x29)

A typical path is C:\Windows\System32.

%Videos% (CSIDL_MYVIDEO, 0x0e)

V6.0: The file system directory that serves as a common repository for video files.
A typical path is C:\Documents and Settings\username\My Documents\My Videos.

%Windows% (CSIDL_WINDOWS, 0x24)

V5.0: The Windows directory or SYSROOT. This corresponds to the %windir% or %SYSTEMROOT% environment variables.
A typical path is C:\Windows.

---

2. VARIABLES THAT ARE USEFUL FOR SPECIAL REQUIREMENTS

These are intended for more special cases, or declared obsolete, and might not function as intended. You should know what you do, it’s all upon your own risk!

%AdminTools% (CSIDL_ADMINTOOLS, 0x30)

V5.0: The file system directory that is used to store administrative tools for an individual user.
The MMC will save customized consoles to this directory, and it will roam with the user.

%AltStartup% (CSIDL_ALTSTARTUP, 0x1d, obsolete, use "Startup")

The file system directory that corresponds to the user's nonlocalized Startup program group.
This value is recognized in Windows Vista for backward compatibility, but the folder itself no longer exists.

%CommonAdminTools% (CSIDL_COMMON_ADMINTOOLS, 0x2f)

V5.0: The file system directory that contains administrative tools for all users of the computer.

%CommonAltStartup% (CSIDL_COMMON_ALTSTARTUP, 0x1e, obsolete, use "CommonStartup")

The file system directory that corresponds to the nonlocalized Startup program group for all users.
This value is recognized in Windows Vista for backward compatibility, but the folder itself no longer exists.

%CommonPrograms% (CSIDL_COMMON_PROGRAMS, 0x17)

The file system directory that contains the directories for the common program groups that appear on the Start menu for all users.
A typical path is C:\Documents and Settings\All Users\Start Menu\Programs.

%CommonStartMenu% (CSIDL_COMMON_STARTMENU, 0x16)

The file system directory that contains the programs and folders that appear on the Start menu for all users.
A typical path is C:\Documents and Settings\All Users\Start Menu.

%CommonTemplates% (CSIDL_COMMON_TEMPLATES, 0x2d)

The file system directory that contains the templates that are available to all users.
A typical path is C:\Documents and Settings\All Users\Templates.

%Desktop% (CSIDL_DESKTOP, 0x00)

The virtual folder that represents the Windows desktop, the root of the namespace.

%Documents% (CSIDL_MYDOCUMENTS, 0x0c)

V6.0: The virtual folder that represents the My Documents desktop item.
This value is equivalent to CSIDL_PERSONAL.

%Fonts% (CSIDL_FONTS, 0x14)

A virtual folder that contains fonts. A typical path is C:\Windows\Fonts.

%LocalizedResourcesDir% (CSIDL_RESOURCES_LOCALIZED, 0x39)

%NetHood% (CSIDL_NETHOOD, 0x13)

A file system directory that contains the link objects that may exist in the My Network Places virtual folder. It is not the same as CSIDL_NETWORK, which represents the network namespace root.
A typical path is C:\Documents and Settings\username\NetHood.

%PrintHood% (CSIDL_PRINTHOOD, 0x1b)

The file system directory that contains the link objects that can exist in the Printers virtual folder.
A typical path is C:\Documents and Settings\username\PrintHood.

%Programs% (CSIDL_PROGRAMS, 0x02)

The file system directory that contains the user's program groups (which are themselves file system directories).
A typical path is C:\Documents and Settings\username\Start Menu\Programs.

%ResourceDir% (CSIDL_RESOURCES, 0x38)

Windows Vista: The file system directory that contains resource data.
A typical path is C:\Windows\Resources.

%SendTo% (CSIDL_SENDTO, 0x09)

The file system directory that contains Send To menu items.
A typical path is C:\Documents and Settings\username\SendTo.

%StartMenu% (CSIDL_STARTMENU, 0x0b)

The file system directory that contains Start menu items.
A typical path is C:\Documents and Settings\username\Start Menu.

%Templates% (CSIDL_TEMPLATES, 0x15)

The file system directory that serves as a common repository for document templates.
A typical path is C:\Documents and Settings\username\Templates.

---

3. VARIABLES THAT ONLY RETURN CLSIDs

These are not primarily useful for Portable Apps (but can be for other purposes), because they only return CLSIDs. CLSIDs are globally unique identifiers that identify COM class objects, for instance "%RecycleBinFolder%" will return a CLSID of

::{645FF040-5081-101B-9F08-00AA002F954E}

which is the virtual folder that contains the objects in the user's Recycle Bin. (Try typing this into Windows Explorer’s address bar!)

%ComputerFolder% (CSIDL_DRIVES, 0x11)

The virtual folder that represents My Computer, containing everything on the local computer: storage devices, printers, and Control Panel. The folder can also contain mapped network drives.

%ComputersNearMe% (CSIDL_COMPUTERSNEARME, 0x3d)

The folder that represents other computers in your workgroup.
Usually (only) contains a Workgroup or Domain Name.

%ConnectionsFolder% (CSIDL_CONNECTIONS, 0x31)

The virtual folder that represents Network Connections, that contains network and dial-up connections.

%ControlPanelFolder% (CSIDL_CONTROLS, 0x03)

The virtual folder that contains icons for the Control Panel applications.

%InternetFolder% (CSIDL_INTERNET, 0x01)

A virtual folder for Internet Explorer.

%Network% (CSIDL_NETWORK, 0x12)

A virtual folder that represents Network Neighborhood, the root of the network namespace hierarchy.

%PrintersFolder% (CSIDL_PRINTERS, 0x04)

The virtual folder that contains installed printers.

%RecycleBinFolder% (CSIDL_BITBUCKET, 0x0a)

The virtual folder that contains the objects in the user's Recycle Bin.

---

If you’re interested and wish to “peek around” a little, here are links to my VBScript example and it’s ReadMe text:
ReadMe for SetEnvVars (text file)
SetEnvVars.zip (ZIP; as written for use with CCleaner)

Hint: If you play around with SetEnvVars.vbs, set

debug = TRUE

first in line #19. It will then show you everything it does (as message boxes). The WHS (Windows Scripting Host) must be enabled if you wish to execute the VBS via double-clicking. You can of course also invoke wscript.exe (in System32) manually to run it.

Hint 2: SetEnvvars.vbs modifies the User Environment — it stores environment variables there. These can be unset again later, if you wish. You can do that on the command line or using Computer Properties/Environment Variables/User Variables.

If you wish to keep a “snapshot” of your environment before running SetEnvVars.vbs, you can use

set > environment.txt

from a command prompt, which will save all environment variables in a text file.