||<> || = Rationale = The !DownloadManager represents the entry point for the DBus API provided by the [[DownloadService| 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 [[DownloadService/Download|Download]] object that will allow to perform the download of the provided url. The download is not started until the start method from the [[DownloadService/Download|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 [[DownloadService/HashAlgorithm|algorithm]] used to calculate the hash. 4. The [[DownloadService/Metadata|metadata]] of the download. 5. The [[DownloadService/Headers|headers]] of the download * '''''OUT !ObjectPath path:''''' The DBus !ObjectPath of the new created [[DownloadService/Download|download]] created that the application can use to perform the download. '''createDownloadGroup(IN Arra group, IN String algorithm, IN Bool allowGSM, IN Dict metadata, IN Dict headers)''' This method allows the creation of a [[DownloadService/GroupDownload|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 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 [[DownloadService/SpecialUsesCases|Download manager special use cases]]. 3. The hash of the download. * '''''IN String algorithm:''''' The [[DownloadService/HashAlgorithm|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 metadata:''''' The [[DownloadService/Metadata|metadata]] to be used in each individual download of the group. * '''''IN Dict headers:''''' The [[DownloadService/Headers|headers]] to be used in each individual download of the group. * '''''OUT !ObjectPath path:''''' The DBus !ObjectPath of the new created [[DownloadService/GroupDownload|group download]] created that the application can use to perform the download. '''getAllDownloads(OUT Array 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 paths:''''' An array with all the !ObjectPaths of the downloads created by the calling application. '''getAllDownloadsWithMetadata(IN String name, IN String value, OUT Array 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 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: {{{#!highlight xml }}} = Code Examples = == Python == Small script that shows how to use the !DownloadManager to create a single download, track its process and finish the script. {{{#!highlight python #!/usr/bin/python3 from gi.repository import GLib import dbus from dbus.mainloop.glib import DBusGMainLoop DBusGMainLoop(set_as_default=True) MANAGER_PATH = '/' MANAGER_IFACE = 'com.canonical.applications.DownloadManager' DOWNLOAD_IFACE = 'com.canonical.applications.Download' IMAGE_FILE = 'http://i.imgur.com/y51njgu.jpg' def download_created(path): """Deal with the download created signal.""" print('Download created in %s' % path) def finished_callback(path, loop): """Deal with the finis signal.""" print('Download performed in "%s"' % path) loop.quit() def progress_callback(total, progress): """Deal with the progress signals.""" print('Progress is %s/%s' % (progress, total)) if __name__ == '__main__': bus = dbus.SessionBus() loop = GLib.MainLoop() manager = bus.get_object('com.canonical.applications.Downloader', MANAGER_PATH) manager_dev_iface = dbus.Interface(manager, dbus_interface=MANAGER_IFACE) # ensure that download created works manager_dev_iface.connect_to_signal('downloadCreated', download_created) down_path1 = manager_dev_iface.createDownload((IMAGE_FILE, "", "", dbus.Dictionary({}, signature="sv"), dbus.Dictionary({}, signature="ss"))) down_path2 = manager_dev_iface.createDownload((IMAGE_FILE, "", "", dbus.Dictionary({}, signature="sv"), dbus.Dictionary({}, signature="ss"))) down_path3 = manager_dev_iface.createDownload((IMAGE_FILE, "", "", dbus.Dictionary({}, signature="sv"), dbus.Dictionary({}, signature="ss"))) download1 = bus.get_object('com.canonical.applications.Downloader', down_path1) download2 = bus.get_object('com.canonical.applications.Downloader', down_path2) download3 = bus.get_object('com.canonical.applications.Downloader', down_path3) download_dev_iface1 = dbus.Interface(download1, dbus_interface=DOWNLOAD_IFACE) download_dev_iface2 = dbus.Interface(download2, dbus_interface=DOWNLOAD_IFACE) download_dev_iface3 = dbus.Interface(download3, dbus_interface=DOWNLOAD_IFACE) # connect to signals download_dev_iface1.connect_to_signal('progress', progress_callback) download_dev_iface2.connect_to_signal('progress', progress_callback) download_dev_iface3.connect_to_signal('progress', progress_callback) download_dev_iface3.connect_to_signal('finished', lambda path: finished_callback(path, loop)) download_dev_iface1.start() download_dev_iface2.start() download_dev_iface3.start() loop.run() }}}