Using the File System

The file system is one of the most significant application services provided by Windows. Integration with the file system is not only crucial to the smooth operation of your application, but also to the overall usability and reliability of the system.

Location of Files

Store your application's files and the files it generates in system-defined folders such as Program Files, My Documents, and Application Data. Avoid placing any files in the root folder of the user's hard disk unless the user specifies this as the target location. These system-defined locations help keep user data and application code separate. This makes system administration and backup easier and provides better support for shared-use scenarios. Using the prescribed folders also makes the system more robust. Files and folders are organized more predictably. This helps keep users from inadvertently modifying files, which might result in compromising the integrity of your application or the system.

Where to Store Files
Folder	What to store

My Documents	User-created documents or data files
My Documents\My Pictures	User-created images, including those created with cameras or scanners
Program Files\Application Name	Read-only implementation files and libraries or samples
Program Files\Common Files\	Shared services or components Company Name
Documents and Settings\User Name\	User customizable per-user Application Data\Application Name application data available to roaming users
Documents and Settings\User Name\	Discardable or local per-user Application Data\Local Settings\ application data not necessary for Application Name roaming users
Documents and Settings\All Users\	Other local-user dynamic data that Application Data\Application Name applies to all users

The SHGetFolderPath() API, exported from the redistri-butable Shfolder.dll file, enables you to find the locations (and localized names) of the standard system folders. For more information about shell basics, see the MSDN Online Web site at http://msdn.microsoft.com/ui/guide/shell.asp.

Program Files

To store your application's read-only files, create a subfolder within the Program Files folder. Include your application's executable (.exe) files as well as any .dll files, Help files, clip art or other fixed library files, and other support files used by your application. You can use the Common Files subfolder for any shared components (such as .dll files). For files that you do not want the user to access directly, set the hidden file attribute.

Also consider the layout of files you provide with your application. In addition to the recommended structure for your main executable file and its support files, you may want to create special folders for documents, templates, conversion tools, or other files that the user accesses directly.

Documents and Other User-Created Data Files

Save all user-created document files in the My Documents folder. Use this as the default location for your application's Save As dialog box. Save all user-generated images in the My Pictures subfolder. Avoid creating your own subfolders in My Documents and My Pictures unless your application generates multiple related files for user-created data. In that case, it may be better to develop a structure that keeps the associated files together.

Application Data

Create other miscellaneous files that the user doesn't directly access in the Application Data folder. For example, include custom dictionaries, mail stores, user history and other caches, index files, and log files. If you provide multiple applications, within the Application Data folder you can create a folder with your company's name that contains subfolders for each product.

The system provides three Application Data folders for the following types of files:

User Name folder (for example, for Windows 2000, C:\Documents and Settings\user name) — Store per-user customization files.
Local Settings folder — Store per-user files that do not apply when the user roams, such as discardable data or temporary files.
All Users folder — Store local application data common to all users, such as log files, hidden databases, and index files.

File Naming Conventions

Avoid cryptic file names, especially names that contain obscure abbreviations. With Windows support for long file names (up to 255 characters), you can define comprehensible names for the files and folders that are available to users.

Always use the long file name when displaying the name of a file. Long file names can include any character except the following:

When your application automatically supplies a file name, use a name that communicates information about its creation. For example, files created by a particular application should use either the application-supplied type name or the short type name as a proposed name — for example, worksheet or document. When a file by that name already exists in the target folder, add a number to the end of the proposed name — for example, Document (2). When adding numbers to the end of a proposed file name, use the first number of an ordinal sequence that does not conflict with an existing name in that folder. When you create a file name, the system automatically creates an MS-DOS file name (alias) for a file.

Do not display file name extensions (the "dot 3 extension") unless the user chooses the option to display extensions or the file type is not registered. To correctly handle when to display extensions, use the system function SHGetFileInfo() to display file names. This ensures that the file name is displayed correctly based on user preferences.

The system automatically formats a file name correctly if you use the SHGetFileInfo or GetFileTitle function. For more information about these functions, see the Microsoft Platform SDK on the MSDN Online Web site at http://msdn.microsoft.com/ui/guide/sdk.asp.

Because the system uses a file's extension (typically three characters) to describe a file type, do not use extensions to distinguish different forms of the same file type. For example, if your application has a function that automatically backs up a file, name the backup file Backup of file name.ext (using its existing extension) or some reasonable equivalent, not file name.bak. The latter implies that the file's type has changed. Similarly, do not use a Windows file name extension unless your file fits the type description.

When your application saves a file, make sure you preserve the file's creation date and other attributes that are stored separately from the file's contents. For simple applications that open and save a file, this happens automatically. However, more sophisticated applications may create a temporary file, DEL ete the original file, and rename the temporary file to the original file name. In this case, the application should copy the creation date, security information, or other external data from the old file to the new file using the standard system functions. For example, the ReplaceFile() function in Windows 2000 transfers all of this information. Certain system file management functionality depends on a file's accurate creation date.

When a file is copied, use the words "Copy of" as part of the generated file name — for example, Copy of Sample for a file named Sample. If the prefix "Copy of" is already assigned to a file, include a number in parentheses — for example, Copy (2) of Sample. You can apply the same naming scheme to links, except the prefix would be "Link to" or "Shortcut to."

It is also important to support UNC paths for identifying the location of files and folders. UNC paths and file names have the following form.

Using UNC names enables users to directly browse the network and open files without having to make explicit network connections.

Wherever possible, display the full name of a file (without the extension). The number of characters you can display depends on the font used and the context in which the name is displayed. In any case, supply enough characters that users can reasonably distinguish between names. Take into account common prefixes such as "Copy of" or "Shortcut to." If you don't display the full name, indicate that it has been truncated by adding an ellipsis at the cutoff point.

In cases where a file name is displayed but cannot be edited, you can use an ellipsis to abbreviate path names. In that case, include at least the first two entries of the beginning and the end of the path, using ellipses in place of the middle entries, as shown in the following example.

When you use an icon to represent a network resource, label the icon with the name of the resource. If you need to show the network context rather than using a UNC path, label the resource using the following format.

Shared User Data Files

When you store a file in the shared space of the network, the file should be readily accessible to all users. You must design the file to be opened by multiple users at the same time. The level of concurrent access you need to provide depends on the file type; that is, for some files you may support only concurrent access by word, paragraph, section, page, and so on. Provide clear visual cues as to which information can be changed and which cannot. When you cannot easily support access by multiple users, provide the users with an option to open a copy of the file if the original is already open.

Disk Cleaners

If you provide a temporary file cache that the user can empty, register a Disk Cleanup manager with the system. A disk cleaner is a COM object that implements the IEmptyVolumeCache interface.

The system provides a standard dialog box that enables the user to manage temporary storage. The system provides access to this dialog box through the low-disk-space message box, the Maintenance Wizard, and the disk properties window. When this dialog box is displayed, it will call your Disk Cleanup manager to reclaim temporarily used disk space. For information about registering a Disk Cleanup manager and integrating your application with the Maintenance Wizard, see the documentation included in the Microsoft Platform SDK on the MSDN Online Web site at http://msdn.microsoft.com/ui/guide/sdk.asp.