1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/places/mozIAsyncHistory.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,188 @@
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
1.6 + * file, 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 +interface nsIVariant;
1.12 +
1.13 +[scriptable, uuid(41e4ccc9-f0c8-4cd7-9753-7a38514b8488)]
1.14 +interface mozIVisitInfo : nsISupports
1.15 +{
1.16 + /**
1.17 + * The machine-local (internal) id of the visit.
1.18 + */
1.19 + readonly attribute long long visitId;
1.20 +
1.21 + /**
1.22 + * The time the visit occurred.
1.23 + */
1.24 + readonly attribute PRTime visitDate;
1.25 +
1.26 + /**
1.27 + * The transition type used to get to this visit. One of the TRANSITION_TYPE
1.28 + * constants on nsINavHistory.
1.29 + *
1.30 + * @see nsINavHistory.idl
1.31 + */
1.32 + readonly attribute unsigned long transitionType;
1.33 +
1.34 + /**
1.35 + * The referring URI of this visit. This may be null.
1.36 + */
1.37 + readonly attribute nsIURI referrerURI;
1.38 +};
1.39 +
1.40 +[scriptable, uuid(ad83e137-c92a-4b7b-b67e-0a318811f91e)]
1.41 +interface mozIPlaceInfo : nsISupports
1.42 +{
1.43 + /**
1.44 + * The machine-local (internal) id of the place.
1.45 + */
1.46 + readonly attribute long long placeId;
1.47 +
1.48 + /**
1.49 + * The globally unique id of the place.
1.50 + */
1.51 + readonly attribute ACString guid;
1.52 +
1.53 + /**
1.54 + * The URI of the place.
1.55 + */
1.56 + readonly attribute nsIURI uri;
1.57 +
1.58 + /**
1.59 + * The title associated with the place.
1.60 + */
1.61 + readonly attribute AString title;
1.62 +
1.63 + /**
1.64 + * The frecency of the place.
1.65 + */
1.66 + readonly attribute long long frecency;
1.67 +
1.68 + /**
1.69 + * An array of mozIVisitInfo objects for the place.
1.70 + */
1.71 + [implicit_jscontext]
1.72 + readonly attribute jsval visits;
1.73 +};
1.74 +
1.75 +/**
1.76 + * Shared Callback interface for mozIAsyncHistory methods. The semantics
1.77 + * for each method are detailed in mozIAsyncHistory.
1.78 + */
1.79 +[scriptable, uuid(1f266877-2859-418b-a11b-ec3ae4f4f93d)]
1.80 +interface mozIVisitInfoCallback : nsISupports
1.81 +{
1.82 + /**
1.83 + * Called when the given place could not be processed.
1.84 + *
1.85 + * @param aResultCode
1.86 + * nsresult indicating the failure reason.
1.87 + * @param aPlaceInfo
1.88 + * The information that was given to the caller for the place.
1.89 + */
1.90 + void handleError(in nsresult aResultCode,
1.91 + in mozIPlaceInfo aPlaceInfo);
1.92 +
1.93 + /**
1.94 + * Called for each place processed successfully.
1.95 + *
1.96 + * @param aPlaceInfo
1.97 + * The current info stored for the place.
1.98 + */
1.99 + void handleResult(in mozIPlaceInfo aPlaceInfo);
1.100 +
1.101 + /**
1.102 + * Called when all records were processed.
1.103 + */
1.104 + void handleCompletion();
1.105 +
1.106 +};
1.107 +
1.108 +[scriptable, function, uuid(994092bf-936f-449b-8dd6-0941e024360d)]
1.109 +interface mozIVisitedStatusCallback : nsISupports
1.110 +{
1.111 + /**
1.112 + * Notifies whether a certain URI has been visited.
1.113 + *
1.114 + * @param aURI
1.115 + * URI being notified about.
1.116 + * @param aVisitedStatus
1.117 + * The visited status of aURI.
1.118 + */
1.119 + void isVisited(in nsIURI aURI,
1.120 + in boolean aVisitedStatus);
1.121 +};
1.122 +
1.123 +[scriptable, uuid(1643EFD2-A329-4733-A39D-17069C8D3B2D)]
1.124 +interface mozIAsyncHistory : nsISupports
1.125 +{
1.126 + /**
1.127 + * Gets the available information for the given array of places, each
1.128 + * identified by either nsIURI or places GUID (string).
1.129 + *
1.130 + * The retrieved places info objects DO NOT include the visits data (the
1.131 + * |visits| attribute is set to null).
1.132 + *
1.133 + * If a given place does not exist in the database, aCallback.handleError is
1.134 + * called for it with NS_ERROR_NOT_AVAILABLE result code.
1.135 + *
1.136 + * @param aPlaceIdentifiers
1.137 + * The place[s] for which to retrieve information, identified by either
1.138 + * a single place GUID, a single URI, or a JS array of URIs and/or GUIDs.
1.139 + * @param aCallback
1.140 + * A mozIVisitInfoCallback object which consists of callbacks to be
1.141 + * notified for successful or failed retrievals.
1.142 + * If there's no information available for a given place, aCallback
1.143 + * is called with a stub place info object, containing just the provided
1.144 + * data (GUID or URI).
1.145 + *
1.146 + * @throws NS_ERROR_INVALID_ARG
1.147 + * - Passing in NULL for aPlaceIdentifiers or aCallback.
1.148 + * - Not providing at least one valid GUID or URI.
1.149 + */
1.150 + [implicit_jscontext]
1.151 + void getPlacesInfo(in jsval aPlaceIdentifiers,
1.152 + in mozIVisitInfoCallback aCallback);
1.153 +
1.154 + /**
1.155 + * Adds a set of visits for one or more mozIPlaceInfo objects, and updates
1.156 + * each mozIPlaceInfo's title or guid.
1.157 + *
1.158 + * aCallback.handleResult is called for each visit added.
1.159 + *
1.160 + * @param aPlaceInfo
1.161 + * The mozIPlaceInfo object[s] containing the information to store or
1.162 + * update. This can be a single object, or an array of objects.
1.163 + * @param [optional] aCallback
1.164 + * A mozIVisitInfoCallback object which consists of callbacks to be
1.165 + * notified for successful and/or failed changes.
1.166 + *
1.167 + * @throws NS_ERROR_INVALID_ARG
1.168 + * - Passing in NULL for aPlaceInfo.
1.169 + * - Not providing at least one valid guid, or uri for all
1.170 + * mozIPlaceInfo object[s].
1.171 + * - Not providing an array or nothing for the visits property of
1.172 + * mozIPlaceInfo.
1.173 + * - Not providing a visitDate and transitionType for each
1.174 + * mozIVisitInfo.
1.175 + * - Providing an invalid transitionType for a mozIVisitInfo.
1.176 + */
1.177 + [implicit_jscontext]
1.178 + void updatePlaces(in jsval aPlaceInfo,
1.179 + [optional] in mozIVisitInfoCallback aCallback);
1.180 +
1.181 + /**
1.182 + * Checks if a given URI has been visited.
1.183 + *
1.184 + * @param aURI
1.185 + * The URI to check for.
1.186 + * @param aCallback
1.187 + * A mozIVisitStatusCallback object which receives the visited status.
1.188 + */
1.189 + void isURIVisited(in nsIURI aURI,
1.190 + in mozIVisitedStatusCallback aCallback);
1.191 +};
