SAMPLE: FAVREAD Reads Internet Shortcuts from Favorites Folder

MORE INFORMATION

NOTE: This sample requires header files from the Internet Client SDK (InetSDK). It may not compile or build without modification on systems that do not have the InetSDK.

To Use

1. Copy the Favorites.asp file to an appropriate location in your Web site's directory.
2. Modify the line reading the following near the end to point to the path of a particular Favorites folder on a computer that you want to display:

   <% Fav.AltPath = "<Path To Your Favorites Folder>;" %>
   					

3. Give read access privileges to IUSR_ComputerName for the Favorites folders so that the protected process of ASP can access and read the Internet Shortcut files. (Lack of access rights is the most likely cause of problems with FavRead.)
4. Navigate to that ASP page on the Web site using your favorite browser. (for example, "http://example.microsoft.com/favorites.asp")

Object Model

Think of this object as having an internal pointer to an item in a folder. What this pointer points to is undefined until the client calls "First" to set the pointer to the first item. "Next" is then used to move the pointer to the next item in the list. As each item is iterated, the URL and Name properties can be used to obtain the relevant information about each item. In typical Favorites folders, if the URL property is NULL, then the item is likely a folder itself which has items inside. For these items, the Group property can be used to obtain a brand new Favorites Reader object which is pre-initialized and pre-set to the first item in the new folder's list. In this way, a script can easily run through and obtain the name and URL of a whole series of Internet Shortcuts stored in a set of folders and all contained sub-folders.

Properties:

• AltPath: A write-only property that can be used to point the FavReader object at a new directory on the computer. Call First() after setting this property.
• Group: A read-only property that returns a new Favorites Reader object if the current item is a sub-folder.
• Name: The name of the current item in the folder.
• URL: The URL of the current item in the folder if it is an Internet Shortcut.

Methods:

• First() - no parameters This must be called before any items in the folder are enumerated.
• Next() - no parameters Use this to set Favorites Reader to the next item in the folder.

Events:

None

Main Points of Discussion

• Shelldef.h: Favorites Reader includes a file called Shelldef.h which adds definitions for smart-pointers and GUIDs on shell objects. This support is not included in Comdef.h by default. This file can easily be taken from here and used in other projects that make shell calls.
• Because some of the definitions of shell objects in Shelldef.h only exist in the new headers sent out with the Internet Client SDK, make sure the InetSDK include directory is searched first before the Visual C++ 5.0 Include directory when building this sample. Change this setting by selecting Options from the Tools menu in Visual C++ 5.0 and then changing to the "Directories" tab on the Options dialog box.
• One of the key problems, as mentioned above, is access permissions. ASP scripts and objects used by ASP run in a special user context with limited access to the folders on the computer. This special user account is usually named "IUSR_ComputerName" where ComputerName is the official Windows NT computer name of that machine.
  
  This causes a couple of problems for Favorites Reader. First, this computer account usually will not have access to read the Favorites folder on a particular machine. This access needs to be manually granted by the administrator of the machine.
  
  Second, since this is a brand new account and not the logged-on user (there might not even be a logged on user on most Web servers), the default location of the Favorites Folder will not usually point at the correct Favorites Folder. As most Favorites are stored by Internet Explorer on a per-user basis, Favorites Reader should probably get pointed to a specific user's Favorites folder on that machine. Alternatively, the favorites of a particular user could get copied to the default Favorites folder on the machine.
• Favorites Reader uses some of the new C++ smart pointers and new types available in Visual C++ 5.0 such as _bstr_t. These features clean up the code significantly but unfortunately they do require the C Run-time. This does increase the size of the DLL a bit.
• Because Favorites Reader can be used to access the machine's hard-drive, it is not marked safe-for-scripting. It does not persist, so it is not marked safe-for-persistence either.
• COM Objects intended for use in a scripting environment must be more careful about error code return values than those intended for use in C++. Script code usually does very minimal error checking and even the slightest non-SUCCESS value returned to a script engine will usually halt the script.
  
  In the case of Favorites Reader, all methods and propgets return S_OK and use other means to report error. For example, the lack of a Name property most often indicates some sort of error occurred on a particular item. Script can therefore easily ignore these problems and continue with the next item.
• Note the use of IShellFolder::ParseDisplayName to obtain a PIDL from a pathname such as "D:\Winnt\Profiles\Me\Favorites". (see Initialize())
• Note that Favorites Reader uses the shell allocator (SHGetMalloc) to allocate and free most memory for the object. (see StrRetToStr())
• Note the use of the following in get_Group():

  CComObject<CFavReader>::CreateInstance(&fvNew);
  						

  This particular ATL construct creates a new instance of a FavReader object without all the nasty overhead of CoCreateInstance. get_Group() can then easily use the properties and methods of this new object to set it to the proper folder.