The Tiny Wrapper Class for URL History Interface in C#

• Download demo project - 20.59 KB

Introduction

This article describes what the UrlHistoryWrapper class is and how to use it. The UrlHistoryWrapper class is a tiny class that wraps the C# equivalence of the IURLHistory interface in the MSDN document. They are wrapped into easy to use C# classes. This class provides the following features:

1. Enumerate the items in the history cache.
2. Place the specified URL into the history. If the URL does not exist in the history, an entry is created in the history. If the URL does exist in the history, it is overwritten.
3. Clears history on a per-user basis.
4. Queries the history and reports whether a particular URL has been visited by the current user.

To see these features in action, "start" or "start without debugging" the URLHIstoryDemo program from the Visual Studio .NET menu.

1. You can see the URL history in the DataGrid. Push "Enumerate" button, and the program refreshes the URL history. When you type "file" in the TextBox at the top of the form, and then push "Enumerate" button, the program displays history items that match what you have typed into the TextBox (in this example, "file").
2. When you type anything in the "URL" TextBox and the "Title" TextBox in the "Add or Delete URL" GroupBox, and then push "Add" button, the URL you typed is placed into the history. The new record is displayed at the bottom of the DataGrid.
3. If you really really really want to clear the URL history except today's history, push "Clear All the History" button. This option will delete all the history except today's history, and "Temporary Internet Files" of your browser stores copies of all the pages you visit when you are surfing on the internet.
4. When you type the URL in the "URL" TextBox in the "Query URL" GroupBox, and then push "Search" button, the program queries the history and reports whether a particular URL has been visited by the current user.

Using the Code (How to Use the UrlHistoryWrapper Class)

The UrlHistoryWrapper class resides in UrlHistoryLibrary namespace and is available in UrlHistoryLibrary.dll assembly. To add the class library to your project, follow these steps:

1. In Solution Explorer, expand the project node you want to add a reference to.
2. Right-click the References node for the project and select Add Reference from the shortcut menu.
3. To add a reference to a component, do the following:
   1. In the Add Reference dialog box, select the tab indicating the Project.
   2. In the top pane, select the UrlHistoryLibrary.dll, and then click the Select button. If the UrlHistoryLibrary.dll is not in the list, you may locate it using the Browse button. The UrlHistoryLibrary.dll appears in the SelectedComponents pane of the dialog box. Click OK.
   3. UrlHistoryLibrary.dll will appear under the References node of the project.
4. Add a using UrlHistoryLibrary; to your source code.
5. Add a UrlHistoryWrapperClass field to your Form class with the following statement. Add a HistoryWrapperClass.STATURLEnumerator field to enumerate the items in the history cache and add an ArrayList field.

   UrlHistoryWrapperClass urlHistory;
   UrlHistoryWrapperClass.STATURLEnumerator enumerator;
   ArrayList list;

6. In the constructor, add the following code after InitializeComponent call:

   //Initialize the UrlHistoryWrapperClass class
   urlHistory = new UrlHistoryWrapperClass();
   //Returns an enumerator that can iterate through the history cache.
   enumerator = urlHistory.GetEnumerator();
   list = new ArrayList();

To enumerate the items in the history cache and store them in the ArrayList object, call the GetUrlHistory method on the enumerator as follows:

enumerator.GetUrlHistory(list);

The following code does the same thing:

while(enumerator.MoveNext())
{
    list.Add(enumerator.Current);
}
enumerator.Reset();

By calling the SetFilter method on the enumerator before enumerating the items in the history cache with the following code, MoveNext() compares the specified URL with each URL in the history list to find matches. MoveNext() then copies the list of matches to a buffer. SetFilter method is used to specify the URL to compare.

enumerator.SetFilter(textBoxFilter.Text , STATURLFLAGS.STATURLFLAG_ISTOPLEVEL);
while(enumerator.MoveNext())
{    
    list.Add(enumerator.Current);
}
enumerator.Reset();

UrlHistoryWrapperClass has GetEnumerator method. UrlHistoryWrapperClass.STATURLEnumerator class has MoveNext, Reset methods, and Current property. But these classes do not implement IEnumerable interface nor IEnumerator interface. The items in the history cache change often, and enumerator needs to reflect the data as it existed at a specific point in time. But Inside C# by Tom Archer does not recommend this approach.

To place the specified URL into the history, call the AddHistoryEntry method on the UrlHistoryWrapperClass object.

urlHistory.AddHistoryEntry(textBoxURL.Text, 
  textBoxTitle.Text, ADDURL_FLAG.ADDURL_ADDTOHISTORYANDCACHE);

The first argument of this method is the string of the URL to place in the history. The second argument is the string of the title associated with that URL. The last argument is the flag which indicates where a URL is placed in the history.

To clear history on a per-user basis, call the ClearHistory method on the UrlHistoryWrapperClass object. This method will delete all the history except today's history, and Temporary Internet Files of your browser stores copies of all the pages you visit when you are surfing on the Internet.

urlHistory.ClearHistory();

To query the history and report whether a particular URL has been visited by the current user, call the QueryURL method on the UrlHistoryWrapperClass object.

STATURL s = urlHistory.QueryUrl(textBoxQueriedURL.Text, 
             STATURL_QUERYFLAGS.STATURL_QUERYFLAG_TOPLEVEL);
if(s.pwcsUrl != null)
{
    //Queried URL has been visited by the current user.
}
else 
{
    //Queried URL has not been visited by the current user.
}

The first argument of this method is the string of the URL to query. The second argument is one of the IUrlHistory flags. This method returns STATURL structure. If the returned STATURL's pwcsUrl is not null, the queried URL has been visited by the current user.

I deliberately avoided mentioning the DeleteHistoryEntry method, because it does not work. It is supposed to delete the specified URL from the history. That is why the "Delete" button on the demo application is disabled. I do not know how to work it out. I do not know whether the following link might help...

• MSDN

Points of Interest

I learned a bit of C# and the .NET Framework. The most annoying problem is that I have to use COM and Win32 API against my intention and without experience with COM and Win32API. As a matter of fact, I borrowed the type library from Eduardo A. Morcillo and referenced it in Visual Studio .NET and creates the Interop assembly. And then disassembled that Interop assembly. I used IL (Intermediate Language) in that Interop assembly file to write the source code in the file urlhist.cs". I think there are people who learned a bit of C# but don't know about COM. I hope my tiny class library is helpful for such people to use IUrlhistory interface without difficulty.

History

• 22^nd June, 2004: Initial post
• 5^th March, 2010: Updated the solution to .NET 3.5 version on Windows 7