Download Manager API: Using the Download Manager API

The Download Manager API consists of the following parts:

• Client API
• Download Manager UI Library

The Client API enables the user to:

• Create a session and set session attributes
• Create a download subsession and set default values for attributes that apply to all downloads in a given session.
• Find a download with a specified URL
• Set an observer for getting next-URIs of COD or OMA DD download subsessions
• Start, pause, and reset download events
• Move or delete downloaded content
• Connect the Download Manager to the server
• Add an Observer to a session and remove it when it is no longer needed

Use Case 1: Connecting to the Download Manager Server

To connect the Download Manager to the server, call the ConnectL function of the RHttpDownloadMgr class, which is located in the DownloadMgrClient.h header file.

To disconnect the Download Manager from the server, call the Close function of the same class.

The following example shows how to connect the Download Manager to the server:

iDownloadMgr.ConnectL(KUidMyApp, *this, ETrue);

Use Case 2: Declaring an Observer

The Download Manager Observer is an interface, implemented by the host application, which listens for download events and performs customized actions based on those events. You must implement the MHttpDownloadMgrObserver interface in order to utilize the Download Manager.

To implement this interface, pass the object that implements the MHttpDownloadMgrObserver interface to the ConnectL function when the Download Manager is constructed. The Download Manager Observer calls the HandleDMgrEventL function every time the state of a download changes.

The following table lists the functions associated with the Download Manager Observer. The AddObserverL and the RemoveObserver functions belong to the RHttpDownloadMgr class. The HandleDMgrEventL function belongs to the MHttpDownloadMgrObserver class. Both classes are located in the DownloadMgrClient.h header file.

The following example shows how to declare an Observer:

class CMyAppUi : public CAknAppUi, 
                 public MHttpDownloadMgrObserver
   {
     public:
        void HandleDMgrEventL( RHttpDownload& aDownload,
                               THttpDownloadEvent aEvent );
    };

void CMyAppUi::HandleDMgrEventL
    ( RHttpDownload& aDownload, THttpDownloadEvent aEvent )
    {
     switch ( aEvent.iDownloadState )
        {
         case EHttpDlCreated:
            {
             // Add new download to the list
             NewDownloadCreatedL( aDownload );
             break;
            }

        case EHttpDlInprogress:
            {
             // Update progress info
             UpdateProgressInfoL( aDownload, aEvent );
             break;
            }

        case EHttpDlPaused:
            {
             DownloadPausedL( aDownload, aEvent );
             break;
            }

        case EHttpDlCompleted:
            {
             DownloadCompletedL( aDownload, aEvent );
             break;
            }
        case EHttpDlFailed:
            {
            DownloadFailedL( aDownload, aEvent );
            break;
            }

        case EHttpDlMoved:
            {
            // Download moved to this session.
            // Add it to the list. 
            NewDownloadCreatedL( aDownload );
            break;
            }

        case EHttpDlMediaRemoved:
            {
             // Remove the download from the list.
             DeleteDownloadL( aDownload );
             break;
            }
            
        case EHttpDlMediaInserted:
            {
             // Add new download to the list.
             NewDownloadCreatedL( aDownload );
             break;
            }
            
        case EHttpDlPausable:
        case EHttpDlNonPausable:
            {
             // Update the download UI data.
             PauseableStateChangedL( aDownload, 
                     aEvent.iDownloadState==EHttpDlPausable );
             break;
            }

        case EHttpDlDeleted:
            {
            // Download is deleted from another client instance.
            DeleteDownloadL( aDownload );
            break;
            }

        case EHttpDlAlreadyRunning:
            {
            // Nothing to do.
            break;
            }

        case EHttpDlDeleting:
            {
            // Download is going to be deleted.
            DeleteDownloadL( aDownload );
            break;
            }

        default:
            {
            break;
            }
        }
    }

Use Case 3: Creating a Session

The functions in the following table create a session and set session attributes. These functions belong to the RHttpDownloadMgr class. This class is located in the DownloadMgrClient.h header file.

The following example shows how to create a session object:

RHttpDownloadManager dmgr;
dmgr.ConnectL( MyAppUid, *this, ETrue );
//Assume that this object implements the MHttpDownloadMgrObserver, 
//which is a common scenario
CleanupClosePushL( dmgr );

…
CleanupStack::PopAndDestroy( &dmgr );

Use Case 4: Creating a Download

The functions in the following table create a download subsession and set default values for attributes that apply to all downloads in a given session. These functions belong to the RHttpDownloadMgr class, which is located in the DownloadMgrClient.h header file.

The developer should choose one of the following functions to create a new download subsession:

• CreateDownloadL
• CreateClientSideDownloadL
• CreateCodDownloadL

The SetDefault< >Attribute functions can be used with any of the Create< >DownloadL functions.

The following example shows how to:

• Create a download
• Enumerate a download

Create a Download

To create a download, call the session's CreateDownloadL function. Note that this does not start the download. To start the download, call the Start function.

TBool result;
_LIT8( KMyUrl, “http://www.series60.com” );
RHttpDownload& download = 
    dmgr.CreateDownloadL( KMyUrl, result ); 
// ’download’ will hold the reference to the newly created 
// download

An alternative method creates a new download even if the URL is already being downloaded:

_LIT8( KMyUrl, “http://www.series60.com” );
RHttpDownload& download = dmgr.CreateDownloadL( KMyUrl ); 

Another method creates a download in the client process, as opposed to in the Download Manager server. Note that client-side downloads can slow the performance of the client process; consider this before creating such downloads.

void CTransactionHandler::ContinueDownloadL( 
     RHTTPTransaction* aTrans )
    {
    TInt transaction = REINTERPRET_CAST( TInt, aTrans );
    TBool isNewDl = ETrue;
    RHttpDownload& dl = dmgr.CreateClientSideDownloadL( 
                             transaction, isNewDl );
    User::LeaveIfError( dl.Start() );
    }

COD or OMA DD descriptors can also be given to the Download Manager for processing:

_LIT8( KCodUrl, "www.index.hu" );
_LIT8( KDdMimeType, "application/vnd.oma.dd+xml" );
// Create a buffer containing OMA DD:
HBufC8* buf = MyGetCodBufLC( KDdMimeType );                        
User::LeaveIfError( iDownloadMgr.SetIntAttribute
                  ( EDlMgrIap, (TInt32)iapId ) );
TBool retVal;
RHttpDownload& download = iDownloadMgr.CreateCodDownloadL
                          ( KCodUrl,
                            *buf,
                            KDdMimeType,
        	                   CEikonEnv::Static(),
        	                   retVal );
...

Enumerate a Download

To enumerate a download, access the array that the Download Manager maintains on the client side.

CDownloadArray& downloads = dmgr.CurrentDownloads();

Use Case 5: Managing Downloads

The following functions start, pause, and reset download events, and delete and move downloaded content. To resume a paused download, call the Start function. These functions belong to the RHttpDownload class, which is located in the DownloadMgrClient.h header file.

The following sections contain examples of how to start, pause, and resume a download.

Start the Download

The download launches automatically if both of the following conditions are true:

• The UI Library is installed
• The EDlAttrAction attribute is set to ELaunch.

download.Start();

The following example queries a URL, and then creates and starts a download.

TBuf<128> url = _L("http://s60testbuda.ccc.fi/dm/blue.jpg");
CAknTextQueryDialog* dlg = CAknTextQueryDialog::NewL( url );
dlg->SetDefaultInputMode(EAknEditorTextInputMode);
TInt cmd = dlg->ExecuteLD( R_TEST_URL_QUERY );

if( cmd == EAknSoftkeyDone )
    {
    // Ask the user for the Internet Access Point ID 
TUint32 iapId( 0 ); 
    TRAPD( err, AskIapIdL( iapId ) );
    User::LeaveIfError( iDownloadMgr.SetUintAttribute( EDlMgrAttrIap, iapId ) );

    HBufC8* url8 = HBufC8::NewLC( url.Length() );
    url8->Des().Copy( url );
    RHttpDownload& download = iDownloadMgr.CreateDownloadL(*url8 );
    CleanupStack::PopAndDestroy( url8 );

    User::LeaveIfError( download.SetIntAttribute( EDlAttrAction, ELaunch ) );
    User::LeaveIfError( download.Start() );
    }

Pause and Resume a Download

The following example shows how to pause and then resume a download.

download.Pause();

There is no function for resuming a paused download. Simply call Start and the download will continue where it left off.

Reset a Download

The following example shows how to reset a download. All content previously downloaded is lost.

download.Reset()

Move a Downloaded File to a Specified Storage Location

The following example shows how to move downloaded content.

TFileName filename( _L(“c:\\temp\\myfile.jpg” );
download.SetStringAttribute( EDlAttrDestFilename,  filename );
download.Move();

Cleanup a Download

The following example cleans up a download.

download.Delete();

Handle Events

The following example shows how to handle the events of the Download Manager server:

1. Check the incoming event to determine whether the content type is known.
2. If the content type is acceptable, call aDownload.Start to resume the download.
3. If the content type is not acceptable, the user is notified.

void CTestAppUi::HandleDMgrEventL( RHttpDownload& aDownload, THttpDownloadEvent aEvent )
    {
    if( EHttpContentTypeReceived == aEvent.iProgressState )
        // Start download again if content-type is acceptable 
        // and UiLib is not installed
        {
        User::LeaveIfError( aDownload.Start() );
        }
    if( EHttpDlCompleted == aEvent.iDownloadState )
        {
        InfoNoteL( _L( "Completed" ) );
        }
    else if( EHttpDlFailed == aEvent.iDownloadState )
        {
        InfoNoteL( _L( "Failed" ) );
        }
    }

Add the Downloads Menu to the Client Application Options Menu

The following example dynamically adds the Downloads Menu to the client application's Options menu in CMyAppUi::DynInitMenuPaneL:

iDownloadMgrUiLibRegistry. DownloadsList().DownloadMenu().AddMenuL
( EMyAppCmdDownloads, aMenuPane, EMyAppCmdPreviousMenuId );

Display the Downloads List

The following example displays the list of downloads belonging to the client application.

iDownloadMgrUiLibRegistry.DownloadsList().DisplayDownloadsListL();

Handle a Completed Download

The following example shows how the client application can handle a completed download directly

iDownloadMgrUiLibRegistry.UserInteractions().HandleDownloadL( aDownload );

Control Automatic Event Handling

The following example shows how the client application can turn automatic completed event handling off. Other events cannot be controlled yet.

download.SetIntAttribute( EDlAttrAction, EDoNothing );

In the example above, the completed download is not handled by the UI Library.

The client can request that the download be handled by the UI Library by means of the following code:

iDownloadMgrUiLibRegistry.UserInteractions().HandleDownloadL( aDownload );

Use Case 6: Querying Attributes

The following functions list all downloads and query the attributes of the session. These functions belong to the RHttpDownloadMgr class, which is located in the DownloadMgrClient.h header file.

The following example shows how to query session-level integer attributes. You can also query String or Boolean attributes by calling the GetStringAttribute and the GetBoolAttribute functions, respectively.

TInt32 exitAction;
dmgr.GetIntAttribute( EDlMgrExitAction, exitAction );

The following example shows how to retrieve the current downloads and their reported URL attributes:

1. Request the array of all the current downloads.
2. Call the GetStringAttribute function with the EDlAttrCurrentUrl parameter to query the URL of each download.

const CDownloadArray& array = iDownloadMgr.CurrentDownloads();
   for( TInt i = 0; i < array.Count(); i++ )
    {
    TBuf8<128> url8;
    User::LeaveIfError( array[i]->GetStringAttribute( EDlAttrCurrentUrl, url8 ));
    HBufC* url = HBufC::NewLC( url8.Length() );
    url->Des().Copy( url8 );
    InfoNoteL( *url );
    CleanupStack::PopAndDestroy( url );
    }  

Use Case 7: Setting Attribute Values

The following functions set the values of Download Manager session attributes and the default values of download attributes. These functions belong to the RHttpDownloadMgr class, which is located in the DownloadMgrClient.h header file.

The following example sets two integer attributes. You can also set String or Boolean attributes by calling the SetStringAttribute and the SetBoolAttribute functions, respectively.

dmgr.SetIntAttribute( EDlMgrExitAction, EExitPause );

The following example shows how to set the default value of an attribute for an individual download.

dmgr.SetDefaultIntAttribute( EDlMgrExitAction, EExitPause );

Use Case 8: Closing a Download Manager Session

The following function closes and cleans up a Download Manager session. It belongs to the RHttpDownloadMgr class, which is located in the DownloadMgrClient.h header file.

The following example shows how the client can respond to client application termination.

TBool OkToExitL();

Using the Download Manager UI Library

The UI Library provides the following:

• Downloads list
• Download menu inserted into the client application Options menu
• Dialogs that give download status or query the user for information
• Registry API that enables you to install the downloads list, menu, and dialogs
• Control of automatic event handling
• Termination of the client application

Use Case 9: Displaying a List of Downloads

The Downloads List maintains and displays the list of downloads and the Options Menu. The CDownloadMgrUiDownloadsList class exposes the Downloads List to the client application. The client application calls the UI library to display a list of downloads by means of the following code:

CDownloadMgrUiDownloadsList::DisplayDownloadsListL();

Use Case 10: Adding the Download Menu to the Options Menu

The Download menu must be dynamically added to the Options menu of the client application. The client application calls the UI library to add the Download menu item to its Options menu by means of the following code:

CDownloadMgrUiDownloadsList::DownloadMenu().AddMenuL 
( TInt  aCommandId, 
  CEikMenuPane& aMenuPane, 
  TInt aPreviousId );

The following example shows how to install the Download List and the Download Menu.

void CMyAppUi::ConstructL()
{
// Connect to the Download Manager
// RHttpDownloadMgr iDMgr; 
User::LeaveIfError( iDMgr.Connect( KMyAppUid, *this, ETrue ) );
    // Create the UI Library Registry
    // CDownloadMgrUiLibRegistry * iUiReg;
    iUiReg = CDownloadMgrUiLibRegistry::NewL( iDMgr );
// Install the Downloads List and get a pointer to it
// CDownloadMgrUiDownloadsList * iMgrDownloadsList; 
iDMgrDownloadsList = &iUiReg->RegisterDownloadsListL();
}

CMyAppUi::~CMyAppUi()
{
delete iUiReg;
// iDMgrDownloadsList is owned by iUiReg.
iDMgr.Close();
}

void CMyAppUi::DynInitMenuPaneL( TInt  aMenuId, 
                                 CEikMenuPane*  aMenuPane)
{
if ( aMenuId == R_MYAPPUI_OPTIONS_MENU_PANE )
    {
     iDMgrDownloadsList->DownloadMenu().AddMenuL( KMyAppCmdDownloadMenu, *aMenuPane, KMyAppCmdPreviousId );
     }
}

void CMyAppUi:: HandleCommandL( TInt  aCommand )
{
 switch( aCommand )
    {
     ……
     case KMyAppCmdDownloadMenu:
         {
          iDMgrDownloadsList->DisplayDownloadsListL();
          break;
         }
     ……
     }
}

Use Case 11: Installing Dialogs

Dialogs are available to support the following user interactions:

• Confirm that the download can be continued
• Handle completed downloads. They are either opened, saved, or postponed for later handling.
• Query HTTP authentication credentials
• Query proxy authentication credentials
• Notify the user of errors
• Enable the user to cancel downloads before terminating the client application
• Notify the user that the system terminated the client application

These dialogs are usually called automatically when the corresponding event occurs. In addition, the client application can handle a download directly by means of the following code:

void CDownloadMgrUiUserInteractions::HandleDownloadL( RHttpDownload& aDownload );

The following example shows how to install the Download Manager UI User Interactions (dialogs).

void CMyAppUi::ConstructL()
{
// Connect to the Download Manager
//RHttpDownloadMgr iDMgr; 
User::LeaveIfError( iDMgr.Connect( KMyAppUid, *this, ETrue ) );
// Create the UI Library Registry
    // CDownloadMgrUiLibRegistry * iUiReg;
    iUiReg = CDownloadMgrUiLibRegistry::NewL(iDMgr);
//Install the User Interactions (dialogs) and get a pointer to
    //  it
//CDownloadMgrUiUserInteractions* idMgrUserInteractions;
iDMgrUserInteractions = &iUiReg->RegisterUserInteractionsL();
}

CMyAppUi::~CMyAppUi()
{
 delete iUiReg;
     // iDMgrUserInteractions is owned by iUiReg.
 iDMgr.Close();
}     

When CMyApp uses iDMgr to download a URL, then iDMgr uses CDownloadMgrUiUserInteractions to interact with the user.

Use Case 12: Registering UI Components

The UI Library Registry enables you to register the following UI components:

• Downloads List
• Menu by means of the Downloads List
• Dialogs

The CDownloadMgrUiLibRegistry class represents the Registry. The Registry owns the registered UI components; the clients should only refer to them. To register the UI components, pass a default RHttpDownloadMgr as an argument, as shown in the following code:

static CDownloadMgrUiLibRegistry* NewL( RHttpDownloadMgr& aDownloadMgr ); 

By default, no UI component is registered. To register a UI component, call the following methods of CDownloadMgrUiLibRegistry:

CDownloadMgrUiUserInteractions& RegisterUserInteractionsL();
CDownloadMgrUiDownloadsList& RegisterDownloadsListL(); 

Use Case 13: Controlling Automatic Event Handling

By default, the User Interactions observer handles almost every event. When a download completes, this interface opens the handler application or saves the file to a location specified by the user. The client application can turn automatic handling of the completed state on or off by means of the following functions of the CDownloadMgrUiUserInteractions class:

void SetBoolAttributeL( const TUint aAttribute, TBool aValue ); 
void GetBoolAttributeL( const TUint aAttribute, TBool& aValue );

Note that currently only the following aAttribute is supported:

EUiLibAttrCompletedStateHandling

Use Case 14: Terminating the Client Application

The client application can be closed by the user or by the system.

Termination by the User

To respond to a Back, Close, or Exit command, the client application can call the OkToExitL function of the CDownloadMgrUiUserInteractions class:

TBool OkToExitL();

This function returns ETrue if the user wishes to exit and cancel all downloads. It returns EFalse if the user does not wish to exit. The client application can decide whether or not it wants to exit; it does not have to obey what this function returns.

The following example shows how the client application can be closed by the user.

void CClientAppUi::HandleComandL( TInt aCommand )
{
 switch ( aCommand )
     {
     case EEikCmdExit:
     // called only when the system closes the client
     // application
          {
          iUserExit = EFalse;
          Exit();
          break;
          } 
      case EClientAppCmdUserExit:
          {
           if ( iUserInteractions->OkToExitL() )
               {
               iUserExit = ETrue;
               Exit();
               }
           else
               {
               break;  //do not close the application 
               }
          }
      }
  }

Termination by the System

If the client application receives the EEikCmdExit command from the system, then the client application can call the PrepareToExit function. The UI library initializes a Grouped Soft Notification (GSN) if any downloads are paused, in progress, or completed.

TInt PrepareToExit( CEikAppUi& aAppUi,
                    TClientAppExitType aExitType,
                    TVwsViewId aViewId, 
                    TUid aCustomMessageId,
                    const TDesC8& aViewActivationMsg );

A simplified version of this method is as follows:

TInt PrepareToExit( TUint32 aAppUid,
                    TUint32 aViewId,
                    TUint32 aCustomMessageId );

The following example shows how the client application can respond to termination by the system.

The following functionality can be added to the application's destructor. Note that CClientAppUi::HandleCommandL must be modified as illustrated in the previous example (case EEikCmdExit).

CClientAppUi::~CClientAppUi ()
{
 if ( !iUserExit && iUserInteractions )  
      //system closes app
       {
        TVwsViewId viewId( TUid::Uid(KThisAppUid), 
                               TUid::Uid(KThisAppUid) );
        TUid customMessageId( TUid(0) );
        TBufC8<1> viewActivationMsg ( kNullDesC8 );
        // PrepareToExit initializes soft notifications 
        iUserInteractions->PrepareToExit 
           ( /* CEikAppUi& */*this, 
             ETerminatedBySystem, 
             viewId, 
             customMessageId, 
             viewActivationMsg );
       }
delete iUiRegistry;
iDownloadManager.Close();
}

Error handling

The Download Manager API uses the Symbian operating system's exception handling (leave processing) mechanisms. It does not define any error codes of its own.

Memory overhead

The RAM consumption of the Download Manager is directly proportional to the size of the content being downloaded.

Extensions to the API

The Download Manager API does not support extensions at this time.