Using the Windows 7 Libraries : WORKING WITH KNOWN FOLDERS

Known folders are essentially those folders that the system already knows about — they're the folders that the system is designed to provide. The KnownFolders class contains a host of these folder listings as individual properties. For example, if you want to access a list of entries in the Administrative Tools folder of the Control Panel, you use the KnownFolders.AdminTools property. In fact, you might be surprised at just how many folders it contains. Here's a list of the folders you can access (including a special All property that accesses all the known folders):

The purpose of the KnownFolders class is to provide you with quick access to every common folder on a system. You obtain a substantial amount of information about the entries as well. For example, you can determine whether an entry is simply a link or a real file. It's also possible to obtain a list of properties for the entry. Although the Known Folders example described in the sections that follow works exclusively with the KnownFolders.Documents property, it does show you what you can achieve using any of the KnownFolder properties.

1. Configuring the Known Folders Example

This example begins with a Windows Forms application. You'll need to add a List button (btnList) to obtain a list of the known folders and their content, and a list box (lstOutput) to output the results of the query. In addition, you'll need to add a reference to Microsoft.WindowsAPICodePack.Shell.DLL and provide the following using statement:

using Microsoft.WindowsAPICodePack.Shell;

2. Writing the Known Folders Example Code

The Known Folders example provides you with a view of the kinds of information you can obtain from the KnownFolders.Documents property — it doesn't describe every kind of information you can obtain. All the KnownFolders properties will provide similar sorts of information. Listing 1 shows the code you need for this example.

Example 1. Displaying known folder information

private void btnList_Click(object sender, EventArgs e)
{
    // Clear the previous information.
    lstOutput.Items.Clear();

    // Display generic information about the Documents
    // known folder.
    lstOutput.Items.Add("Documents Known Folder:");
    lstOutput.Items.Add("\tCanonical Name: " +
        KnownFolders.Documents.CanonicalName);
    lstOutput.Items.Add("\tCategory: " +

KnownFolders.Documents.Category);
    lstOutput.Items.Add("\tDefinition Options: " +
        KnownFolders.Documents.DefinitionOptions);
    lstOutput.Items.Add("\tFile Attributes: " +
        KnownFolders.Documents.FileAttributes);
    lstOutput.Items.Add("\tFolder ID: " +
        KnownFolders.Documents.FolderId);
    lstOutput.Items.Add("\tLocalized Name: " +
        KnownFolders.Documents.LocalizedName);
    lstOutput.Items.Add("\tLocalized Name Resource ID: " +
        KnownFolders.Documents.LocalizedNameResourceId);
    lstOutput.Items.Add("\tPath: " +
        KnownFolders.Documents.Path);
    lstOutput.Items.Add("\tRelative Path: " +
        KnownFolders.Documents.RelativePath);

    // Add a space prior to enumeration.
    lstOutput.Items.Add("");

    // Enumerate the content of the Documents known folder.
    foreach (var Document in KnownFolders.Documents)
    {
        // Output generic object information.
        lstOutput.Items.Add("Document Type: " + Document.GetType());
        lstOutput.Items.Add("Document Name: " + Document.Name);
        lstOutput.Items.Add("Display Name: " +
            Document.GetDisplayName(DisplayNameType.Url));
        lstOutput.Items.Add("Is this a FileSystem object? " +
            Document.IsFileSystemObject);
        lstOutput.Items.Add("Is this a link? " + Document.IsLink);

        // If this is a ShellFileSystemFolder, output some
        // additional information.
        if (Document.GetType() == typeof(ShellFileSystemFolder))
        {
            // Convert to a specific type.
            ShellFileSystemFolder ThisFolder =
                (ShellFileSystemFolder)Document;

            // Display the ShellfileSystemFolder information.
            lstOutput.Items.Add("Parsing Name: " +
                ThisFolder.ParsingName);
            lstOutput.Items.Add("Path: " + ThisFolder.Path);

            // Enumerate the documents in the folder.
            lstOutput.Items.Add("Contents:");
            foreach (var FolderDoc in ThisFolder)
            {
                lstOutput.Items.Add("\tName: " + FolderDoc.Name);
            }
        }

        // Add a space between items.
        lstOutput.Items.Add("");
    }
}

					  

Each KnownFolders property provides some basic information about the folder as a whole, so the application begins by displaying this information. Some information, such as KnownFolders.Documents.Path, appears as a simple string, while other information appears as part of an enumeration, such as KnownFolders.Documents.DefinitionOptions. These top-level properties are always enumerable because they contain other elements such as files and folders. So after the code displays the basic information about the folder, it begins displaying information about the folder content using a foreach loop.

Notice that the code defines Document as type var. That's because Document can be of several different types, depending on the content of the selected folder. In this case, the two most common content types are ShellFile (for files) and ShellFileSystemFolder (for folders). You could also see a ShellLink object in this case. The point is that you can't assume anything about the content of Document.

The IDE is smart enough to provide you with a list of basic properties common to all the objects that Document contains. The code displays a number of these items on-screen. Most of the properties are simple strings. However, at least one property, named Properties, is extremely complex, as shown in Figure 1. In this case, there are 43 properties used to define the ShellFile, AccessODBC.DSN, and Figure 1 shows just two of them. You can use Properties to discover significant details about the object in question.

Figure 1. Some properties, such as the one named Properties, are extremely complex.

Most of the entries provided as output in this example are properties. However, there's one method you need to know about, GetDisplayName(). This method comes in handy because it lets you present the display name for an object using a special format. In this case, the example presents the display name using the DisplayNameType.Url format.

You need to become familiar with the objects that a particular KnownFolders property can contain. For example, the KnownFolders.Documents property can contain objects of type ShellFileSystemFolder, which has some special properties. In order to process this special information, the code first compares the type of the current Document object to typeof(ShellFileSystemFolder). If the object types are the same, the code displays properties that are special for a ShellFileSystemFolder object, such as Path.

Figure 2. Known folder listings tell you a lot about the structure of data on a system.

A ShellFileSystemFolder object is a container that can hold other objects. The example only processes one level of objects. Normally, you'd build a recursive routine to parse the entire folder tree. In this case, the output simply contains the name of each object within the ShellFileSystemFolder object. Figure 2 shows typical output from this example.