# Bookmarks module

Copyright © 1995-2007 Opera Software ASA. All rights reserved. This file is part of the Opera web browser. It may not be distributed under any circumstances.

1. Introduction
2. Interface overview and API documentation
3. Use-cases
4. Supported standards
5. Implementation and design
6. References

## Introduction

The Bookmarks module provides support for adding, modifying, removing and storing bookmarks.

Current information about the Bookmarks module.

## Interface overview and API documentation

### API documentation

The API documentation is extracted automatically by Doxygen.

### Overview

A folder structure of bookmarks is represented by a tree structure of objects of type BookmarkItem. A BookmarkItem represents both bookmarks and folders of bookmarks. Information about each bookmark such as name, URL and description is stored in each BookmarkItem as BookmarkAttribute. To identify a bookmark each BookmarkItem also has a uid (unique identification).

To add new bookmarks, change the folder structure, delete or move bookmarks etc. the class BookmarkManager is used.

When loading and saving bookmarks the BookmarkManager class and an implementation of the BookmarkStorageProvider interface class is used.

There are several functions available for setting different restrictions on the total number of bookmarks, the number of bookmarks in each folder and maximum folder depth. It is also possible to set restrictions on the length of the different attributes of a bookmark, for example maximum length of a name, URL or description. If an attribute restriction is violated the attribute can either be cut at the specified maximum length or an error may be returned.

A minimal user interface is provided through opera:bookmarks.

## Use-cases

### Creating and modifying bookmarks

A new bookmark is added using AddBookmark or AddNewBookmark. The latter sets a timer which will cause the bookmarks to be saved to storage when the time is out. Modification of a bookmark is achieved using the function SetAttribute.

### Delete and move bookmarks

Bookmarks or folders of bookmarks may be deleted or moved. In case a trash folder has been added, deleting a bookmark will mean moving it to the trash folder. When a bookmark has been deleted a timer is set which will cause the bookmarks to be saved when time is out.

### Loading bookmarks

To load bookmarks first create an BookmarkManager object and then an BookmarkStorageProvider object. Depending on which type of storage the bookmarks are stored on, different derived classes may be used. Currently only BookmarkIniStorage is supported. By writing a class that inherits BookmarkStorageProvider more formats and storage forms may be used. Using this class the bookmarks must be stored in an ini-file. Then to find out when all bookmarks are loaded a listener BookmarkManagerListener must be registered. OnBookmarksLoaded is called when all bookmarks are loaded.

When using BookmarkIniStorage the method OpenLoad must be called before using it with LoadBookmarks. The parameters to this method are a filename and an OpFileFolder.

### Saving bookmarks

Saving bookmarks is done in almost the same way as loading bookmarks. A BookmarkStorageProvider is needed and also a BookmarkManager. To save all bookmarks to storage SaveBookmarks is called. When all bookmarks are saved the method OnBookmarksSaved is called on registered BookmarkManagerListener objects.

When using BookmarkIniStorage some of the methods OpenSave or OpenLoad must have been called supplying the filename and folder where the ini-file is located.

## Supported standards

n/a

## Implementation and design

See also the API documentation.

### Implementation

The BookmarkManager class contains almost all functionality needed by a user of the bookmarks module. In order to support a large number of bookmarks and slow or unreliable storage forms, both saving and loading are asynchronous. Thus when BookmarkStorageProvider::SaveBookmark or BookmarkStorageProvider::LoadBookmark is called, BookmarkManager calls BookmarkStorageProvider::SaveBookmark or BookmarkStorageProvider::LoadBookmark and then saves its state and returns. The BookmarkStorageProvider may then for example connect to a host on the internet or just read or write to some file. When the BookmarkStorageProvider is done it calls BookmarkManager::BookmarkIsSaved or BookmarkManager::BookmarkIsLoaded. Then, in case no error occurred, the BookmarkManager sends a message to the main message handler. When this message is processed BookmarkManager::HandleCallback is called and SaveBookmarks or LoadBookmarks is called again. Now the previous state is loaded and if there are more bookmarks the loop continues. When all bookmarks are saved or loaded the function BookmarkManagerListener::OnBookmarksSaved or BookmarkManagerListener::OnBookmarksLoaded is called.

The BookmarkStorageProvider class defines an interface to a storage form. In this way different storage forms may be implemented. The only storage form currently supported is BookmarkIniStorage which stores bookmarks in an INI-file using prefsfile.

The BookmarkItem class holds all information associated to a particular bookmark. Every such information is an attribute which is defined in the BookmarkAttribute class. The supported attributes are defined in BookmarkAttributeType.

A user interface is accessed by opera:bookmarks. This is generated by the class OperaBookmarks and the function OperaBookmarks::GenerateData. This function generates a HTML document containing javascript which calls functions for adding, deleting, moving, saving and loading bookmarks. These functions are defined in the class JS_Opera in the dom module. They use the functionality provided by the BookmarkManager.

### Memory management

#### Heap usage

Each bookmark contain a number of attributes and also a unique identifier. All of these are allocated on the heap. They are freed when the bookmark holding them is freed.

#### Stack usage

There are no recursive calls.

#### Static memory usage

There is one global pointer to the BookmarkManager object.

#### OOM policies

All functions return OpStatus::ERR_NO_MEMORY to the caller when out of memory.

### Performance

## References

- Prefsfile module