Download Manager API: API Description

Download Manager API: API Description
- Use cases
- API class structure

The S60 Download Manager enables its clients to download files over HTTP(S) in a separate subsession that can continue if the client application stops running. The Download Manager is composed of two main parts:

Server
UI library

The server downloads the files; it can handle multiple simultaneous downloads. The UI library contains a set of dialogs that are employed when a download requires user interaction. This library provides menus that can easily integrate with the options menu of the client application.

The client application is responsible for all downloads. A typical client of the Download Manager has the following characteristics:

Requires files to be downloaded from the network
Requires the ability to suspend and resume download events
Requires persistence during download
Does not require rendered Web content
Wants to avoid using the HTTP stack directly
Benefits the standard dialogs and notification messages provided by the UI library

The client application must pass its UID to the Download Manager upon its construction. The client can configure the download to do one of the following if the application closes:

Continue (default behavior)
Pause
Delete

Upon restart, the ongoing or paused download can be retrieved. The following table describes the subsystems of the Download Manager.

**Table 1:** Download Manager subsystems
Subsystem	Description
Download Manager server	Provides the download functionality.
Client application	The host application. The client application and the Download Manager server run in separate threads.
Download Manager client API	Provides communication between the client and the server.
Download Manager User Interface (UI) library	Provides the download menu and dialogs for user interaction with the Download Manager.

The Download Manager API enables developers to do the following:

Create a Download Manager session and set its attributes
Set and query session attributes
Specify what happens to the downloading file if the client application closes
Start, pause, resume, or reset a download
Set and query attributes for individual download events
Add or remove Observers
Move the downloaded file to a predefined location
Specify the Internet access point ID for the next network connection
Close a Download Manager session

Logical and Technical Classification

The Download Manager API is classified as a Library API. It provides classes and functions that are used in the context of the client's thread. The classes and functions can be used independently of each other.

The Download Manager API is a Client-Server interface.

Audience

This API is intended for developers who wish to create and interact with HTTP(S) download events for the S60 platform. The reader should be familiar with the C++ programming language and the Symbian operating system.

Development Environment Requirements

The Download Manager API is compatible with any application that complies with S60 3rd Edition.

The classes and methods for this API are defined in the Epoc32\Include\DownloadMgrClient.h file.

To set up the environment for development, follow these steps:

Set up a network connection for your emulator.
Link with the DownloadMgr.lib library.
If you want to utilize the Download Manager's UI library, you must link with the DownloadMgrUiLib.lib file and include the CDownloadMgrUiLibRegistry.h header file
Include any of the following header files, according to your needs:
- CDownloadMgrUiUserInteractions.h
- CDownloadMgrUiDownloadsList.h
- CDownloadMgrUiDownloadMenu.h

About the Download Manager Server

The Download Manager Server utilizes the Symbian OS client-server framework. This enables downloads to run in a separate process that continues in the event of a power outage or client application crash. Each download event is treated as a separate subsession.

The Download Manager Engine supports the following :

Multiple simultaneous downloads
HTTP(S) protocols with the following features:
- Cookies
- User agent header
- Digital Rights Management (DRM) support
- HTTP authentication (basic and digest)
Explicit specification of the Internet access point
Pause and resumption of download sessions, including following a reboot of the client application
Persistent storage of the downloaded files
High level of configurability

Downloads are visible only to the host application.

About the Download Manager UI Library

The Download Manager UI library contains the following information:

Integrated options menu
Status of ongoing downloads
Notification messages for resuming downloads
Notification message that an ongoing download is being deleted
Authentication dialog
Confirmation dialog to continue the download after its content type is identified
Confirmation query about opening content after download is complete
Storage location for files with unsupported content types
Error messages
Notification of ongoing download after a client application crash or loss of power

Use cases

This section describes the types of things you can do with the Download Manager API. The main use cases are as follows:

Connecting to the Download Manager Server
Declaring an Observer
Creating a session
Creating a download
Managing downloads
Querying attributes
Setting attribute values
Closing a Download Manager session
Displaying a list of downloads
Adding the Download Menu to the Options Menu
Installing dialogs
Registering UI components
Controlling automatic event handling
Terminating the client application

API class structure

The following table contains descriptions of the structural classes. All of these classes are defined in the DownloadMgrClient.h header file.

**Table 2:** Download Manager API Structural Classes
Class Name	Class Description
`RHttpDownload`	Class that represents an individual download subsession. Provides functions that: Start a download Pause a download Reset a download Delete a download Move downloaded content to a previously specified location
`RHttpDownloadMgr`	Class that represents a Download Manager session. Provides functions that: Create a Download Manager session Create a new download subsession Create a new download subsession for a Content Object Descriptor (COD) or an Open Mobile Alliance (OMA) Download Descriptor (DD) Add the client to the Observer list Remove the client from the Observer list List all of the downloads for the current session Find a download with a specified URL Find the value of an attribute of a specified type Set the default value of an attribute of a specified type Pause all downloads Resume all downloads Reset all downloads Delete all downloads Disconnect the HTTP(S) connection and pause all downloads Close the Download Manager session
`MHttpDownloadMgrObserver`	Observer interface for notification of download events Provides functions that indicate that an event occurred.
`MHttpDownloadMgrNextUriObserver`	Interface for notification about the next-URI of a Content Object Descriptor (COD) or an OMA Download Descriptor (DD) download. Provides functions that send the URI of the next OMA download to the client.
`THttpDownloadEvent`	Enumeration that contains the download events. This class provides no functions. Download events can include: Created In progress Paused Completed Failed Moved from one client to another Memory card or other storage media removed from the phone Downloaded content is stored in a memory card or other storage media inserted in the phone Deleted Already running Deleting

The following table describes the structural classes of the UI Library. The classes named with a C prefix are defined in the header file having the same name as the class. The MDownloadMgrUiLibRegModel class is in the CDownloadMgrUiLibRegistry.h header file.

**Table 3:** UI Library Structural Classes
Class Name	Class Description
`CDownloadMgrUiLibRegistry`	Class that supports registration of the User Interactions (dialogs) and the Downloads List. Provides functions that: Construct the UI Library Registry Destruct the UI Library Registry Construct a Downloads List Construct a User Interactions dialog
`CDownloadMgrUiUserInteractions`	Class that supports dialogs for the following user interactions: Confirms that a content-type header has arrived Handles completed downloads Queries HTTP authentication credentials Queries proxy authentication credentials Notifies the user of errors Enables the user to cancel downloads before terminating the client application Prepares for termination of the client application Notifies the user that the system terminated the client application
`CDownloadMgrUiDownloadsList`	Class that represents the Downloads List component. It provides functions that: Display the list of downloads Cancel the display of the list of downloads Return the number of downloads in the Downloads List Access the Download Menu utility Indicate whether or not the Downloads List is visible
`CDownloadMgrUiBase`	Abstract base class for UI Library classes with UI controls. It supports `set` and `get` attributes belonging to the derived classes. These attributes are different from the attributes of the Download Manager session and subsession. The derived classes define and support these attributes. These classes are listed in the relevant sections of the UI Library class descriptions. Provides functions that: Set the value of a specified attribute of a specified type from the UI Library Get the value of a specified attribute of a specified type from the UI Library
`CDownloadMgrUiLibRegModel`	Abstract class that enables access to the resources of the UI Library Registry. This class is defined in the `CDownloadMgrUiLibRegistry.h` header file. Clients of the UI Library are not required to derive from this class. Provides functions that: Count the number of downloads in a Download Manager session Indicate whether or not the Downloads List is installed Indicate whether or not the User Interactions dialogs are installed Return the UID of the client application that installed the UI Library Return a reference to the Downloads List installed Return a reference to the observed Download Manager session Return a reference to the User Interactions (dialogs) installed
`CDownloadMgrUiDownloadMenu`	Class that supports the Download Menu for the client. The client is not required to construct a Download Menu object. Instead, an instance can be reached with `CDownloadMgrUiDownloadsList::DownloadMenu`. This class provides a function that inserts a menu item into the client application's menu to access the Downloads List.