Rationale

A GroupDownload represents a collection of downloads that will be performed as an atomic operation, that means, if a single download fails the group fails and for the group to succeed all downloads most be downloaded correctly.

Interface

The following defines the public interface exposed by the DownloadManager.

• ObjectPath: Most be provided by the download manager.

  Interface: com.canonical.applications.GroupDownload

Methods

totalSize(OUT UInt64 size)

• Returns the total size of the download. The download is calculated using the total sizes of the child downloads.

  • Arguments

    • OUT UInt64 size: The total size of the group.

progress(OUT UInt64 count, OUT UInt64 started, OUT UInt64 paused, OUT UInt64 finished )

• Returns the progress of the different child downloads.

  • Arguments

    • OUT UInt64 count: The total count of downloads in the group.

    • OUT UInt64 started: The count of downloads that have been started and are in progress. According to the device the download manager will start one or more downloads at a time.

    • OUT UInt64 paused: The count of downloads that have not yet been started.

    • OUT UInt64 finished: The count of downloads that have been successfully completed.

metadata(OUT Dict<String, Variant> metadata)

• Returns the metadata that was used for each of the single downloads.

  • Arguments

    • OUT Dict<String, Variant> metadata: The metadata used for each of the downloads.

setThrottle(IN UInt64 value)

• Allows to set the throttle to be used in each of the downloads that are performed as part of the group download.

  • Arguments

    • IN UInt64 value: The throttle to be used by each of the downloads.

throttle(OUT UInt64 value)

• Returns the throttle that is currently used in each of the downloads that are performed as part of the group download.

  • Arguments

    • OUT UInt64 value: The throttle currently used by each of the downloads.

allowGSMDownload(IN Bool isAllowed)

• Allows to set if a GSM connection can be used to perform each of the downloads that form part of the group download.

  • Arguments

    • IN Bool isAllowed: Bool indicating the the download should use the GSM connection or not.

isGSMDownloadAllowed(OUT Bool isAllowed)

• Returns if the downloads that are part of the group are allowed to use the GSM connection to download.

  • Arguments

    • IN Bool isAllowed: Bool indicating the the download should use the GSM connection or not.

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 a download finished and the download manager is checking its checksum. This signal is emitted for each of the downloads that were set to have a hash. 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 a download finished and the download manager is executing a post processing command that might have been passed. This signal is emitted for each of the downloads that has a post download command. 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 Array<String> localPaths)

• Emitted when the download finished. This signal is just emitted when all children downloads have been finished and all hash checks have been correct. 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 Array<String> localPaths: List with all the new created local paths with the data that was downloaded by the download manager.

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. This signal contains the progress of all children download and the total. There are some cases in which 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 to be downloaded.

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

Code Examples