Rationale

The DownloadManager represents the entry point for the DBus API provided by the ubuntu download service. An application can use the DownloadManager to create downloads that will be performed by the daemon and in this way ensure that the downloads will be completed even if the application is paused or killed by the operating system.

Interface

The following defines the public interface exposed by the DownloadManager.

ObjectPath: /
Interface: com.canonical.applications.DownloaderManager

Methods

createDownload(IN Download download, OUT ObjectPath path)

This method allows the creation of a Download object that will allow to perform the download of the provided url. The download is not started until the start method from the download object is called, the reason for this is that a download might be too fast and signals might be missed.
- Arguments
  - IN Download download: A download is a structure with the following signature (sssa{sv}a{ss}), where the values are:
    1. The url to be downloaded.
    2. The hash of the download. If this value is empty then the hash will not be checked.
    3. The algorithm used to calculate the hash.
    4. The metadata of the download.
    5. The headers of the download
  - OUT ObjectPath path: The DBus ObjectPath of the new created download created that the application can use to perform the download.

createDownloadGroup(IN Arra<GroupDownload> group, IN String algorithm, IN Bool allowGSM, IN Dict<String, Variant> metadata, IN Dict<String, String> headers)

This method allows the creation of a GroupDownload object that will allow to perform the download of a collection of urls so that they are performed as a single atomic operation.
- Arguments
  - IN Array<GroupDownload> group: A group is a structure with the following signature (sss), where the values are:
    1. The url to be downloaded. If this value is empty then the hash will not be checked.
    2. The local file where the download will be stored, please see Download manager special use cases.
    3. The hash of the download.
  - IN String algorithm: The algorithm used to calculate the hash of each of the individual algorithms.
  - IN Bool allowGSM: A bool stating if the download will be allowed over a GSM connection.
  - IN Dict<String, Variant> metadata: The metadata to be used in each individual download of the group.
  - IN Dict<String, String> headers: The headers to be used in each individual download of the group.
  - OUT ObjectPath path: The DBus ObjectPath of the new created group download created that the application can use to perform the download.

getAllDownloads(OUT Array<ObjectPath> paths)

Returns all the downloads created by the application calling the method, that is, the results is no all the downloads from all applications but JUST those of the calling client.
- Arguments
  - OUT Array<ObjectPath> paths: An array with all the ObjectPaths of the downloads created by the calling application.

getAllDownloadsWithMetadata(IN String name, IN String value, OUT Array<ObjectPath> paths )

Returns all the downloads the have a metadata value that matches exactly the provided value.
- Arguments
  - IN String name: The name of the metadata value to check.
  - IN String value: The value of the metadata to check.
  - OUT Array<ObjectPath> paths: An array with all the ObjectPaths of the downloads created by the calling application that have such metadata value.

setDefaultThrottle(IN UInt64 value)

Set the throttle to be used by ALL downloads of ALL applications. This method can be accessed my settings application but will be forbided via AppArmor to click package applications. Each application can set manually this setting per download.
- Arguments
  - IN UInt64 value: The throttle to be used by the downloads.

defaultThrottle(OUT UInt64 value)

Returns the throttle to be used by all the downloads.
- Arguments
  - OUT UInt64 value: The throttle to be used by the downloads.

allowGSMDownload(IN Bool isAllowed)

Set if ALL the downloads can use the GSM connection to be downloaded. This method can be accessed my settings application but will be forbided via AppArmor to click package applications. Each application can set manually this setting per download.
- Arguments
  - IN Bool isAllowed: If GSM is allowed or not.

isGSMDownloadAllowed(OUT Bool isAllowed)

Returns if the downloads are allowed to use the GSM connection to download.
- Arguments
  - OUT Bool isAllowed: If GSM is allowed or not.

Signals

downloadCreated(OUT ObjectPath path)

Signal emitted when a new download is created.
- Arguments
  - OUT ObjectPath path: The path of the new created download.

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.DownloaderManager">
   3     <method name="createDownload">
   4         <arg name="download" type="(sssa{sv}a{ss})" direction="in" />
   5         <arg name="downloadPath" type="o" direction="out" />
   6     </method>
   7 
   8     <method name="createDownloadGroup">
   9         <arg name="downloads" type="a(sss)" direction="in"/>
  10         <arg name="algorithm" type="s" direction="in"/>
  11         <arg name="allowed3G" type="b" direction="in"/>
  12         <arg name="metadata" type="a{sv}" direction="in"/>
  13         <arg name="headers" type="a{ss}" direction="in"/>
  14         <arg name="download" type="o" direction="out" />
  15     </method>
  16 
  17     <method name="getAllDownloads">
  18         <arg name="downloads" type="ao" direction="out" />
  19     </method>
  20 
  21     <method name="getAllDownloadsWithMetadata">
  22         <arg name="name" type="s" direction="in"/>
  23         <arg name="value" type="s" direction="in"/>
  24         <arg name="downloads" type="ao" direction="out" />
  25     </method>
  26 
  27     <method name="setDefaultThrottle">
  28         <arg name="speed" type="t" direction="in"/>
  29     </method>
  30 
  31     <method name="defaultThrottle">
  32         <arg name="speed" type="t" direction="out"/>
  33     </method>
  34 
  35     <method name="allowGSMDownload">
  36         <arg name="allowed" type="b" direction="in"/>
  37     </method>
  38 
  39     <method name="isGSMDownloadAllowed">
  40         <arg name="allowed" type="b" direction="out"/>
  41     </method>
  42 
  43     <signal name="downloadCreated">
  44         <arg name="path" type="o" direction="out"/>
  45     </signal>
  46 
  47  </interface>
  48 </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 #!/usr/bin/python3
   2 
   3 from gi.repository import GLib
   4 import dbus
   5 from dbus.mainloop.glib import DBusGMainLoop
   6 
   7 DBusGMainLoop(set_as_default=True)
   8 
   9 MANAGER_PATH = '/'
  10 MANAGER_IFACE = 'com.canonical.applications.DownloadManager'
  11 DOWNLOAD_IFACE = 'com.canonical.applications.Download'
  12 IMAGE_FILE = 'http://i.imgur.com/y51njgu.jpg'
  13 
  14 
  15 def download_created(path):
  16     """Deal with the download created signal."""
  17     print('Download created in %s' % path)
  18 
  19 
  20 def finished_callback(path, loop):
  21     """Deal with the finis signal."""
  22     print('Download performed in "%s"' % path)
  23     loop.quit()
  24 
  25 
  26 def progress_callback(total, progress):
  27     """Deal with the progress signals."""
  28     print('Progress is %s/%s' % (progress, total))
  29 
  30 if __name__ == '__main__':
  31 
  32     bus = dbus.SessionBus()
  33     loop = GLib.MainLoop()
  34     manager = bus.get_object('com.canonical.applications.Downloader',
  35             MANAGER_PATH)
  36     manager_dev_iface = dbus.Interface(manager, dbus_interface=MANAGER_IFACE)
  37 
  38     # ensure that download created works
  39     manager_dev_iface.connect_to_signal('downloadCreated', download_created)
  40 
  41     down_path1 = manager_dev_iface.createDownload((IMAGE_FILE, "", "",
  42         dbus.Dictionary({}, signature="sv"),
  43         dbus.Dictionary({}, signature="ss")))
  44     down_path2 = manager_dev_iface.createDownload((IMAGE_FILE, "", "",
  45         dbus.Dictionary({}, signature="sv"),
  46         dbus.Dictionary({}, signature="ss")))
  47     down_path3 = manager_dev_iface.createDownload((IMAGE_FILE, "", "",
  48         dbus.Dictionary({}, signature="sv"),
  49         dbus.Dictionary({}, signature="ss")))
  50 
  51     download1 = bus.get_object('com.canonical.applications.Downloader',
  52             down_path1)
  53     download2 = bus.get_object('com.canonical.applications.Downloader',
  54             down_path2)
  55     download3 = bus.get_object('com.canonical.applications.Downloader',
  56             down_path3)
  57 
  58     download_dev_iface1 = dbus.Interface(download1, dbus_interface=DOWNLOAD_IFACE)
  59     download_dev_iface2 = dbus.Interface(download2, dbus_interface=DOWNLOAD_IFACE)
  60     download_dev_iface3 = dbus.Interface(download3, dbus_interface=DOWNLOAD_IFACE)
  61 
  62     # connect to signals
  63     download_dev_iface1.connect_to_signal('progress', progress_callback)
  64     download_dev_iface2.connect_to_signal('progress', progress_callback)
  65     download_dev_iface3.connect_to_signal('progress', progress_callback)
  66     download_dev_iface3.connect_to_signal('finished',
  67             lambda path: finished_callback(path, loop))
  68 
  69     download_dev_iface1.start()
  70     download_dev_iface2.start()
  71     download_dev_iface3.start()
  72 
  73     loop.run()

DownloadService/DownloadManager (last edited 2014-06-18 14:48:19 by ip68-12-7-251)