1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docshell/base/nsIDownloadHistory.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,58 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + * vim: sw=2 ts=2 sts=2
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIURI;
1.13 +
1.14 +/**
1.15 + * This interface can be used to add a download to history. There is a separate
1.16 + * interface specifically for downloads in case embedders choose to track
1.17 + * downloads differently from other types of history.
1.18 + */
1.19 +[scriptable, uuid(4dcd6a12-a091-4f38-8360-022929635746)]
1.20 +interface nsIDownloadHistory : nsISupports {
1.21 + /**
1.22 + * Adds a download to history. This will also notify observers that the
1.23 + * URI aSource is visited with the topic NS_LINK_VISITED_EVENT_TOPIC if
1.24 + * aSource has not yet been visited.
1.25 + *
1.26 + * @param aSource
1.27 + * The source of the download we are adding to history. This cannot be
1.28 + * null.
1.29 + * @param aReferrer
1.30 + * [optional] The referrer of source URI.
1.31 + * @param aStartTime
1.32 + * [optional] The time the download was started. If the start time
1.33 + * is not given, the current time is used.
1.34 + * @param aDestination
1.35 + * [optional] The target where the download is to be saved on the local
1.36 + * filesystem.
1.37 + * @throws NS_ERROR_NOT_AVAILABLE
1.38 + * In a situation where a history implementation is not available,
1.39 + * where 'history implementation' refers to something like
1.40 + * nsIGlobalHistory and friends.
1.41 + * @note This addition is not guaranteed to be synchronous, since it delegates
1.42 + * the actual addition to the underlying history implementation. If you
1.43 + * need to observe the completion of the addition, use the underlying
1.44 + * history implementation's notifications system (e.g. nsINavHistoryObserver
1.45 + * for toolkit's implementation of this interface).
1.46 + */
1.47 + void addDownload(in nsIURI aSource, [optional] in nsIURI aReferrer,
1.48 + [optional] in PRTime aStartTime,
1.49 + [optional] in nsIURI aDestination);
1.50 +
1.51 + /**
1.52 + * Remove all downloads from history.
1.53 + *
1.54 + * @note This removal is not guaranteed to be synchronous, since it delegates
1.55 + * the actual removal to the underlying history implementation. If you
1.56 + * need to observe the completion of the removal, use the underlying
1.57 + * history implementation's notifications system (e.g. nsINavHistoryObserver
1.58 + * for toolkit's implementation of this interface).
1.59 + */
1.60 + void removeAllDownloads();
1.61 +};
