1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/places/mozIAsyncLivemarks.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,213 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this file,
1.6 + * You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIURI;
1.11 +
1.12 +interface mozILivemarkCallback;
1.13 +interface mozILivemarkInfo;
1.14 +interface mozILivemark;
1.15 +
1.16 +interface nsINavHistoryResultObserver;
1.17 +
1.18 +[scriptable, uuid(5B48E5A2-F07A-4E64-A935-C722A3D60B65)]
1.19 +interface mozIAsyncLivemarks : nsISupports
1.20 +{
1.21 + /**
1.22 + * Creates a new livemark
1.23 + *
1.24 + * @param aLivemarkInfo
1.25 + * mozILivemarkInfo object containing at least title, parentId,
1.26 + * index and feedURI of the livemark to create.
1.27 + * @param [optional] aCallback
1.28 + * Invoked when the creation process is done. In case of failure will
1.29 + * receive an error code.
1.30 + * @return {Promise}
1.31 + * @throws NS_ERROR_INVALID_ARG if the supplied information is insufficient
1.32 + * for the creation.
1.33 + * @deprecated passing a callback is deprecated. Moreover, for backwards
1.34 + * compatibility reasons, when a callback is provided this method
1.35 + * won't return a promise.
1.36 + */
1.37 + jsval addLivemark(in jsval aLivemarkInfo,
1.38 + [optional] in mozILivemarkCallback aCallback);
1.39 +
1.40 + /**
1.41 + * Removes an existing livemark.
1.42 + *
1.43 + * @param aLivemarkInfo
1.44 + * mozILivemarkInfo object containing either an id or a guid of the
1.45 + * livemark to remove.
1.46 + * @param [optional] aCallback
1.47 + * Invoked when the removal process is done. In case of failure will
1.48 + * receive an error code.
1.49 + *
1.50 + * @return {Promise}
1.51 + * @throws NS_ERROR_INVALID_ARG if the id/guid is invalid.
1.52 + * @deprecated passing a callback is deprecated. Moreover, for backwards
1.53 + * compatibility reasons, when a callback is provided this method
1.54 + * won't return a promise.
1.55 + */
1.56 + jsval removeLivemark(in jsval aLivemarkInfo,
1.57 + [optional] in mozILivemarkCallback aCallback);
1.58 +
1.59 + /**
1.60 + * Gets an existing livemark.
1.61 + *
1.62 + * @param aLivemarkInfo
1.63 + * mozILivemarkInfo object containing either an id or a guid of the
1.64 + * livemark to retrieve.
1.65 + * @param [optional] aCallback
1.66 + * Invoked when the fetching process is done. In case of failure will
1.67 + * receive an error code.
1.68 + *
1.69 + * @return {Promise}
1.70 + * @throws NS_ERROR_INVALID_ARG if the id/guid is invalid or an invalid
1.71 + * callback is provided.
1.72 + * @deprecated passing a callback is deprecated. Moreover, for backwards
1.73 + * compatibility reasons, when a callback is provided this method
1.74 + * won't return a promise.
1.75 + */
1.76 + jsval getLivemark(in jsval aLivemarkInfo,
1.77 + [optional] in mozILivemarkCallback aCallback);
1.78 +
1.79 + /**
1.80 + * Reloads all livemarks if they are expired or if forced to do so.
1.81 + *
1.82 + * @param [optional]aForceUpdate
1.83 + * If set to true forces a reload even if contents are still valid.
1.84 + *
1.85 + * @note The update process is asynchronous, observers registered through
1.86 + * registerForUpdates will be notified of updated contents.
1.87 + */
1.88 + void reloadLivemarks([optional]in boolean aForceUpdate);
1.89 +};
1.90 +
1.91 +[scriptable, function, uuid(62a426f9-39a6-42f0-ad48-b7404d48188f)]
1.92 +interface mozILivemarkCallback : nsISupports
1.93 +{
1.94 + /**
1.95 + * Invoked when a livemark is added, removed or retrieved.
1.96 + *
1.97 + * @param aStatus
1.98 + * Whether the request was completed successfully.
1.99 + * Use Components.isSuccessCode(aStatus) to check this.
1.100 + * @param aLivemark
1.101 + * A mozILivemark object representing the livemark, or null on removal.
1.102 + */
1.103 + void onCompletion(in nsresult aStatus,
1.104 + in mozILivemark aLivemark);
1.105 +};
1.106 +
1.107 +[scriptable, uuid(6e40d5b1-ce48-4458-8b68-6bee17d30ef3)]
1.108 +interface mozILivemarkInfo : nsISupports
1.109 +{
1.110 + /**
1.111 + * Id of the bookmarks folder representing this livemark.
1.112 + */
1.113 + readonly attribute long long id;
1.114 +
1.115 + /**
1.116 + * The globally unique identifier of this livemark.
1.117 + */
1.118 + readonly attribute ACString guid;
1.119 +
1.120 + /**
1.121 + * Title of this livemark.
1.122 + */
1.123 + readonly attribute AString title;
1.124 +
1.125 + /**
1.126 + * Id of the bookmarks parent folder containing this livemark.
1.127 + */
1.128 + readonly attribute long long parentId;
1.129 +
1.130 + /**
1.131 + * The position of this livemark in the bookmarks parent folder.
1.132 + */
1.133 + readonly attribute long index;
1.134 +
1.135 + /**
1.136 + * Time this livemark's details were last modified. Doesn't track changes to
1.137 + * the livemark contents.
1.138 + */
1.139 + readonly attribute PRTime lastModified;
1.140 +
1.141 + /**
1.142 + * The URI of the syndication feed associated with this livemark.
1.143 + */
1.144 + readonly attribute nsIURI feedURI;
1.145 +
1.146 + /**
1.147 + * The URI of the website associated with this livemark.
1.148 + */
1.149 + readonly attribute nsIURI siteURI;
1.150 +};
1.151 +
1.152 +[scriptable, uuid(9f6fdfae-db9a-4bd8-bde1-148758cf1b18)]
1.153 +interface mozILivemark : mozILivemarkInfo
1.154 +{
1.155 + // Indicates the livemark is inactive.
1.156 + const unsigned short STATUS_READY = 0;
1.157 + // Indicates the livemark is fetching new contents.
1.158 + const unsigned short STATUS_LOADING = 1;
1.159 + // Indicates the livemark failed to fetch new contents.
1.160 + const unsigned short STATUS_FAILED = 2;
1.161 +
1.162 + /**
1.163 + * Status of this livemark. One of the STATUS_* constants above.
1.164 + */
1.165 + readonly attribute unsigned short status;
1.166 +
1.167 + /**
1.168 + * Reload livemark contents if they are expired or if forced to do so.
1.169 + *
1.170 + * @param [optional]aForceUpdate
1.171 + * If set to true forces a reload even if contents are still valid.
1.172 + *
1.173 + * @note The update process is asynchronous, it's possible to register a
1.174 + * result observer to be notified of updated contents through
1.175 + * registerForUpdates.
1.176 + */
1.177 + void reload([optional]in boolean aForceUpdate);
1.178 +
1.179 + /**
1.180 + * Returns an array of nsINavHistoryResultNode objects, representing children
1.181 + * of this livemark. The nodes will have aContainerNode as parent.
1.182 + *
1.183 + * @param aContainerNode
1.184 + * Object implementing nsINavHistoryContainerResultNode, to be used as
1.185 + * parent of the livemark nodes.
1.186 + */
1.187 + jsval getNodesForContainer(in jsval aContainerNode);
1.188 +
1.189 + /**
1.190 + * Registers a container node for updates on this livemark.
1.191 + * When the livemark contents change, an invalidateContainer(aContainerNode)
1.192 + * request is sent to aResultObserver.
1.193 + *
1.194 + * @param aContainerNode
1.195 + * Object implementing nsINavHistoryContainerResultNode, representing
1.196 + * this livemark.
1.197 + * @param aResultObserver
1.198 + * The nsINavHistoryResultObserver that should be notified of changes
1.199 + * to the livemark contents.
1.200 + */
1.201 + void registerForUpdates(in jsval aContainerNode,
1.202 + in nsINavHistoryResultObserver aResultObserver);
1.203 +
1.204 + /**
1.205 + * Unregisters a previously registered container node.
1.206 + *
1.207 + * @param aContainerNode
1.208 + * Object implementing nsINavHistoryContainerResultNode, representing
1.209 + * this livemark.
1.210 + *
1.211 + * @note it's suggested to always unregister containers that are no more used,
1.212 + * to free up the associated resources. A good time to do so is when
1.213 + * the container gets closed.
1.214 + */
1.215 + void unregisterForUpdates(in jsval aContainerNode);
1.216 +};
