BookmarkBridge User Manual
|
|
|
Chapter 3. How BookmarkBridge Works
Hacking BookmarkBridge Source
This section is for software developers wishing to hack BookmarkBridge's source code or
add support for a new browser to BookmarkBridge.
Make sure you have already read through the section on
Compiling BookmarkBridge From Source
before continuing. BookmarkBridge is written in C++ and makes heavy use of the STL
(Standard Template Library) and polymorphism (virtual functions).
Adding Support For a New Browser
Each browser in BookmarkBridge is implemented using a C++ class derived from the BrowserBk class.
BrowserBk is an abstract base class, meaning you can't declare an instance of the class because it
contains pure virtual functions that must be overridden in derived classes. Below is a discussion
of the member functions of BrowserBk.
You will need to understand many important concepts in order to implement a BrowserBk class. Far
too many, in fact, to easily explain in this document. The absolutely best way to learn this stuff
is to look at the source for one of the other browsers, Opera (opera.cpp) or Internet Explorer
(iexplore.cpp). "Use the source, Luke."
I wouldn't recommend starting with Mozilla (mozilla.cpp). It's easily the most
complex of the browser implementations because of the complicated HTML parsing involved in reading
the bookmarks.html file.
Your BrowserBk class must properly handle international character sets. Most browsers use UTF-8
to encode character sets and implement Unicode internally. You should expect to encouter international
characters in a bookmark or folder title or description (if your browser supports descriptions). The
QString class makes it easy to handle UTF-8. QString is implemented internally using Unicode. See
the Opera class (opera.cpp) for a good example of how to use QString to handle UTF-8 for Unicode.
Since BookmarkBridge is a cross-platform product, an unfortunate reality is that Windows and Unix
specify file and directory paths differently. Luckily, Qt does a good job of encapsulating most of
this. The QDir class does a good job of hiding most of the differences between the platforms and
provides a platform-independent way of browsing directories and handling path separators. QDir handles
paths using Unix forward-slash separators. Windows will not handle it well if you pass one of these
paths to the CreateFile() function. For this reason, I highly recommend using Qt classes for file I/O.
If you must call a non-Qt file I/O function (such as access()), use QDir::convertSeparators().
In order to catch most critters before shipping BookmarkBridge, a rather extensive set of regression
tests has been implemented. Under Windows, the tests are implemented in a batch file, using the
Windows 2000 or XP command interpreter. I highly doubt the batch file would run under Windows 9x.
Under Unix, the tests are implemented with a Bash script. The Internet Explorer portion of the tests
is implemented using Python, on both platforms. When adding support for a new browser to BookmarkBridge,
it is important to add it to each of the regression tests. Believe me, they will catch a surprising number
of bugs.
The Browser List
The browserlist.h header file defines a structure that contains an entry for each browser supported
by BookmarkBridge. The browserlist.cpp file declares a global instance of this structure. For each
browser, the list contains a pointer to a character string name, and two static class member functions
from the browser's class. The first, called classFactory() is used to allocate an instance of the
browser class, and returns a pointer to the BrowserBk base class. BookmarkBridge uses this instance
to call the virtual functions of the derived class. The list also contains a pointer to the class's
static saveBookmarks() function. BookmarkBridge calls this function to save the global bookmark
tree to the browser's bookmark database.
BrowserBk Class Member Functions
- virtual bool AreBookmarksReadonly(const QString &bookmarks)
-
This function is called when BookmarkBridge needs to know if a browser's bookmarks
are being accessed in a read-only fashion. In other words, are the bookmarks on a
read-only filesystem? The base class implementation uses the access() function.
The parameter to the function is the path to the bookmark database.
- virtual bool AreBookmarksValid(const QString &bookmarks) = 0
-
This function is called when BookmarkBridge needs to know if the given path
is a valid location for the browser's bookmarks. The Mozilla class implementation
reads the first couple of lines of the bookmarks.html file given in the first parameter
and compares them against the first two lines it knows should be in a Mozilla bookmarks.html file.
This is a pure virtual function which means your browser class must override
this function.
- virtual bool BrowseForBookmarks(QString &bookmarks, QWidget *parent) = 0
-
This function is called when the user wants to browse for the bookmarks for this
browser. If the location for an existing bookmarks file is known, it is passed
in the first parameter. This function should display a dialog box to the user
allowing them to browse. See the Mozilla class for an example of how to browse
for a file and the IExplore class for an example of how to browse for a directory.
This is a pure virtual function which means your browser class must override
this function.
- static BrowserBk * classFactory(void)
-
This function is called when BookmarkBridge needs to allocate an instance of your
browser class. A pointer to this function is stored by BookmarkBridge (see the
section on the browser list above). It expects to receive back a pointer to a
new instance of your browser class (casted down to the BrowserBk base class).
- virtual bool DetectBrowser(QStringList &paths)
-
This function is called when BookmarkBridge wants your class to try to locate any
installations of its browser on the system. The BrowserBk implementation of this
function returns false, indicating that no browser was detected.
If your browser is only available for Windows or Unix
then use conditional compilation to override the function only
on the supported platform. See the IExplore class for an example of this.
The function parameter is a pointer to a QStringList class, which represents an
array of strings, similar to vector. If it's possible for the user to install
more than instance of your browser on the system (two different versions, perhaps), the
function should attempt to locate all installations and place them in the paths variable.
See the Opera class for an example of this. The function should return true if it
found at least one installation.
- virtual bool IsBrowserRunning(void)
-
The base class version of this function returns false.
- virtual bool readBookmarks(const QString &path, BRWSNUM browserOrd) = 0
-
This function is called by BookmarkBridge when it needs the class to read the
browser's bookmark database, specified in the first parameter. The second parameter
contains the browser number, assigned to each unique installation of each browser.
This number is used to identify the browser or browsers that contain a bookmark.
The function should read the bookmarks into a tree, contained in a BkFolder class.
The function needs to save this BkFolder instance for later use by the root() function.
- virtual BkFolder & root(void) = 0
-
This function needs to return a reference to the BkFolder instance populated by the
readBookmarks() function.
Table of Contents
Previous:
Source Code Roadmap
Next:
None
BookmarkBridge is Copyright © 2003 by Ken Schenke.
All Rights Reserved. This program is free
software; you can redistribute it and/or modify it under the terms of the
GNU General Public License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later version.