Rationale

A Download represents a single url to be downloaded by the ubuntu download manager.

Interface

The following defines the public interface exposed by the DownloadManager.

ObjectPath: Most be provided by the download manager.
Interface: com.canonical.applications.Download

Methods

totalSize(OUT UInt64 size)

Returns the total size of the download. There are cases where the server does not return the download size correctly, in those cases the value returned is 0.
- Arguments
  - OUT UInt64 size: The size of the download.

progress(OUT UInt64 received)

Returns the amount of data that has been downloaded so far from the server.
- Arguments
  - OUT UInt64 received: The amount of that downloaded so far and that it is in memory or disk.

metadata(OUT Dict<String, Variant> metadata)

Returns the metadata that was passed to the download when it was created.
- Arguments
  - arg: The metadata associated with the download.

setThrottle(IN UInt64 speed)

Allows to set the throttle to be used in the download so that not all the available bandwidth is used.
- Arguments
  - IN UInt64 speed: The throttle to be used.

throttle(OUT UInt64 speed)

The throttle that has been set to be using with the download.
- Arguments
  - OUT UInt64 speed: The throttle currently used with the download.

allowGSMDownload(IN Bool isAllowed)

Set the download to be allowed to use a GSM connection to perform the download.
- Arguments
  - IN Bool isAllowed: If the download can be performed over a GSM connection.

isGSMDownloadAllowed(OUT Bool isAllowed)

Returns if the current download is allowed to use a GSM connection to perform the download.
- Arguments
  - OUT Bool isAllowed: Bool stating if the download can be currently performed over a GSM connection.

start

Notifies the download manager that the download can be performed. There is no guarantee that the data will start immediately to be downloaded but that it will be queued to be performed in the near future. Once the download is started the signals will be emitted (progress, error, canceled, finished..)

pause

Notifies the download manager that the download has been paused. When a download is paused all partial download information/data is stored so that the download can be resumed at the same point as the download was paused.

resume

Notifies the download manager that the download can be resumed. There is no guarantee that the data will start immediately to be downloaded but that it will be queued in the near future.

cancel

Notifies the download manager that the download has been canceled. Once a download has been canceled the download manager will clean all resources and all finished downloads will be removed from the system.

Signals

started(OUT Bool started)

Emitted when the download was started. This does not mean that the download is being performed but that the download has been placed in the download manager queue of downloads to be performed. After this signal is emitted, signals such as progress will be emitted.
- Arguments
  - OUT Bool started: Bool indicating if the download was correctly set to be started..

paused(OUT Bool paused)

Emitted when the download was paused. This signal means that the download will not be performed and that all temp data downloaded will be stored so that the download can be started at the same point that it was paused.
- Arguments
  - OUT Bool paused: Bool indicating if the download was correctly paused..

resumed(OUT Bool resumed)

Emitted when the download was resumed. This does not mean that the download is being performed but that the download has been placed in the download manager queue of downloads to be performed at the same point that it was paused, that is, already downloaded data will NOT be redownloaded.
- Arguments
  - OUT Bool resumed: Bool indicating if the download was correctly resumed..

canceled(OUT Bool canceled)

Emitted when the download or one of its children was canceled.
- Arguments
  - OUT Bool canceled: Bool indicating if the download or one of its children was canceled..

hashing(OUT String localPath)

Emitted when the download finished and the download manager is checking its checksum. The signal has an out parameter because when performing the download there is no guarantee that a file is already present in the file system and therefore the download manager might have prepended an integer at the end of the local file.
- Arguments
  - OUT String localPath: The local path in where the download was performed.

processing(OUT String localPath)

Emitted when the download finished and the download manager is executing a post processing command that might have been passed. The signal has an out parameter because when performing the download there is no guarantee that a file is already present in the file system and therefore the download manager might have prepended an integer at the end of the local file.
- Arguments
  - OUT String localPath: The local path in where the download was performed.

finished(OUT String localPath)

Emitted when the download finished and correct. If a hash and hash algorithm was provided the signals implies that the hash was also checked and the client does not need to do it. The signal has an out parameter because when performing the download there is no guarantee that a file is already present in the file system and therefore the download manager might have prepended an integer at the end of the local file.
- Arguments
  - OUT String localPath: The local path in where the download was performed.

error(OUT String errorMsg)

Emitted when there was an error performing the download. This signal is emitted when one or more of the children downloads of the group had an error.
- Arguments
  - OUT String errorMsg: The reason of the error..

progress(OUT UInt64 received, OUT UInt64 total)

Emitted every time the progress of the download is updated. There are some cases in witch the total cannot be calculated due to an error in the server side, for those cases the received value and the total value are the same yet the finished signal is not emitted.
- Arguments
  - OUT UInt64 received: Total data received so far.
  - OUT UInt64 total: Total data received so far.

DBus API XML Definition

The following is an XML definition of the DBus interface that can be used to generate adapters in different languages:

   1 <node>
   2   <interface name="com.canonical.applications.Download">
   3 
   4     <method name="totalSize">
   5         <arg name="total" type="t" direction="out"/>
   6     </method>
   7 
   8     <method name="progress">
   9         <arg name="received" type="t" direction="out"/>
  10     </method>
  11 
  12     <method name="metadata">
  13         <arg name="data" type="a{sv}" direction="out" />
  14     </method>
  15 
  16     <method name="setThrottle">
  17         <arg name="speed" type="t" direction="in"/>
  18     </method>
  19 
  20     <method name="throttle">
  21         <arg name="speed" type="t" direction="out"/>
  22     </method>
  23 
  24     <method name="allowGSMDownload">
  25         <arg name="allowed" type="b" direction="in"/>
  26     </method>
  27 
  28     <method name="isGSMDownloadAllowed">
  29         <arg name="allowed" type="b" direction="out"/>
  30     </method>
  31 
  32     <method name="start" />
  33     <method name="pause" />
  34     <method name="resume" />
  35     <method name="cancel" />
  36 
  37     <signal name="started">
  38         <arg name="success" type="b" direction="out"/>
  39     </signal>
  40 
  41     <signal name="paused">
  42         <arg name="success" type="b" direction="out"/>
  43     </signal>
  44 
  45     <signal name="resumed">
  46         <arg name="success" type="b" direction="out"/>
  47     </signal>
  48 
  49     <signal name="canceled">
  50         <arg name="success" type="b" direction="out"/>
  51     </signal>
  52 
  53     <signal name="hashing">
  54         <arg name="path" type="s" direction="out"/>
  55     </signal>
  56 
  57     <signal name="processing">
  58         <arg name="path" type="s" direction="out"/>
  59     </signal>
  60 
  61     <signal name="finished">
  62         <arg name="path" type="s" direction="out"/>
  63     </signal>
  64 
  65     <signal name="error">
  66         <arg name="error" type="s" direction="out"/>
  67     </signal>
  68 
  69     <signal name="progress">
  70         <arg name="received" type="t" direction="out"/>
  71         <arg name="total" type="t" direction="out"/>
  72     </signal>
  73 
  74  </interface>
  75 </node>

Code Examples

Python

Small script that shows how to use the DownloadManager to create a single download, track its process and finish the script.

   1 import gobject
   2 import dbus
   3 from dbus.mainloop.glib import DBusGMainLoop
   4 
   5 DBusGMainLoop(set_as_default=True)
   6 
   7 MANAGER_PATH = '/'
   8 MANAGER_IFACE = 'com.canonical.applications.DownloaderManager'
   9 DOWNLOAD_IFACE = 'com.canonical.applications.Download'
  10 IMAGE_FILE = 'http://i.imgur.com/y51njgu.jpg'
  11 
  12 
  13 def download_created(path):
  14     """Deal with the download created signal."""
  15     print 'Download created in %s' % path
  16 
  17 
  18 def finished_callback(path, loop):
  19     """Deal with the finis signal."""
  20     print 'Download performed in "%s"' % path
  21     loop.quit()
  22 
  23 
  24 def progress_callback(total, progress):
  25     """Deal with the progress signals."""
  26     print 'Progress is %s/%s' % (progress, total)
  27 
  28 if __name__ == '__main__':
  29 
  30     bus = dbus.SessionBus()
  31     loop = gobject.MainLoop()
  32     manager = bus.get_object('com.canonical.applications.Downloader',
  33             MANAGER_PATH)
  34     manager_dev_iface = dbus.Interface(manager, dbus_interface=MANAGER_IFACE)
  35 
  36     # ensure that download created works
  37     manager_dev_iface.connect_to_signal('downloadCreated', download_created)
  38 
  39     down_path = manager_dev_iface.createDownload((IMAGE_FILE, "", "", {}, {}))
  40 
  41     download = bus.get_object('com.canonical.applications.Downloader',
  42             down_path)
  43 
  44     download_dev_iface = dbus.Interface(download, dbus_interface=DOWNLOAD_IFACE)
  45 
  46     # connect to signals
  47     download_dev_iface.connect_to_signal('progress', progress_callback)
  48     download_dev_iface.connect_to_signal('finished',
  49             lambda path: finished_callback(path, loop))
  50 
  51     download_dev_iface.start()
  52 
  53     loop.run()