The information in this article applies to:
- Microsoft ActiveX SDK, version 1.0
- Internet Client SDK, version 4.0
SUMMARY
The Favorites Reader is intended as a demonstration of some of the basic
Shell APIs, particularly the determination of URLs from Internet Shortcuts.
Favorites Reader is a generic iterator of any set of shell folders and
subfolders but its main focus is to provide the links from the user's
Favorites Folder.
The original intention for this object was to make it easy to add a list of
favorite links to a Web site, most likely using the Active Server Pages
(ASP) feature of Internet Information Server (IIS). What better place to
find an ever-changing, up-to-date list of favorite links than in your own
Favorites folder?
The following file is available for download from the Microsoft Software
Library:
~ Favread.exe (size: 43870 bytes)
For more information about downloading files from the Microsoft Software
Library, please see the following article in the Microsoft Knowledge Base:
ARTICLE-ID: Q119591
TITLE : How to Obtain Microsoft Support Files from Online Services
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
- Copy the Favorites.asp file to an appropriate location in your Web
site's directory.
- Modify the line reading:
<% Fav.AltPath = "<Path To Your Favorites Folder>" %>
near the end to point to the path of a particular Favorites folder on a
computer that you want to display.
- 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.)
- 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.