summaryrefslogtreecommitdiff
path: root/toolkit/components/places/mozIAsyncHistory.idl
blob: 35c8cc3a662a41475985d8f0ba411f1a43d72dce (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIURI;
interface nsIVariant;

[scriptable, uuid(41e4ccc9-f0c8-4cd7-9753-7a38514b8488)]
interface mozIVisitInfo : nsISupports
{
  /**
   * The machine-local (internal) id of the visit.
   */
  readonly attribute long long visitId;

  /**
   * The time the visit occurred.
   */
  readonly attribute PRTime visitDate;

  /**
   * The transition type used to get to this visit.  One of the TRANSITION_TYPE
   * constants on nsINavHistory.
   *
   * @see nsINavHistory.idl
   */
  readonly attribute unsigned long transitionType;

  /**
   * The referring URI of this visit.  This may be null.
   */
  readonly attribute nsIURI referrerURI;
};

[scriptable, uuid(ad83e137-c92a-4b7b-b67e-0a318811f91e)]
interface mozIPlaceInfo : nsISupports
{
  /**
   * The machine-local (internal) id of the place.
   */
  readonly attribute long long placeId;

  /**
   * The globally unique id of the place.
   */
  readonly attribute ACString guid;

  /**
   * The URI of the place.
   */
  readonly attribute nsIURI uri;

  /**
   * The title associated with the place.
   */
  readonly attribute AString title;

  /**
   * The frecency of the place.
   */
  readonly attribute long long frecency;

  /**
   * An array of mozIVisitInfo objects for the place.
   */
  [implicit_jscontext]
  readonly attribute jsval visits;
};

/**
 * Shared Callback interface for mozIAsyncHistory methods. The semantics
 * for each method are detailed in mozIAsyncHistory.
 */
[scriptable, uuid(1f266877-2859-418b-a11b-ec3ae4f4f93d)]
interface mozIVisitInfoCallback : nsISupports
{
  /**
   * Called when the given place could not be processed.
   *
   * @param aResultCode
   *        nsresult indicating the failure reason.
   * @param aPlaceInfo
   *        The information that was given to the caller for the place.
   */
  void handleError(in nsresult aResultCode,
                   in mozIPlaceInfo aPlaceInfo);

  /**
   * Called for each place processed successfully.
   *
   * @param aPlaceInfo
   *        The current info stored for the place.
   */
  void handleResult(in mozIPlaceInfo aPlaceInfo);

  /**
   * Called when all records were processed.
   */
  void handleCompletion();

};

[scriptable, function, uuid(994092bf-936f-449b-8dd6-0941e024360d)]
interface mozIVisitedStatusCallback : nsISupports
{
  /**
   * Notifies whether a certain URI has been visited.
   *
   * @param aURI
   *        URI being notified about.
   * @param aVisitedStatus
   *        The visited status of aURI.
   */
  void isVisited(in nsIURI aURI,
                 in boolean aVisitedStatus);
};

[scriptable, uuid(1643EFD2-A329-4733-A39D-17069C8D3B2D)]
interface mozIAsyncHistory : nsISupports
{
  /**
   * Gets the available information for the given array of places, each
   * identified by either nsIURI or places GUID (string).
   *
   * The retrieved places info objects DO NOT include the visits data (the
   * |visits| attribute is set to null).
   *
   * If a given place does not exist in the database, aCallback.handleError is
   * called for it with NS_ERROR_NOT_AVAILABLE result code.
   *
   * @param aPlaceIdentifiers
   *        The place[s] for which to retrieve information, identified by either
   *        a single place GUID, a single URI, or a JS array of URIs and/or GUIDs.
   * @param aCallback
   *        A mozIVisitInfoCallback object which consists of callbacks to be
   *        notified for successful or failed retrievals.
   *        If there's no information available for a given place, aCallback
   *        is called with a stub place info object, containing just the provided
   *        data (GUID or URI).
   *
   * @throws NS_ERROR_INVALID_ARG
   *         - Passing in NULL for aPlaceIdentifiers or aCallback.
   *         - Not providing at least one valid GUID or URI. 
   */
  [implicit_jscontext]
  void getPlacesInfo(in jsval aPlaceIdentifiers,
                     in mozIVisitInfoCallback aCallback);

  /**
   * Adds a set of visits for one or more mozIPlaceInfo objects, and updates
   * each mozIPlaceInfo's title or guid.
   *
   * aCallback.handleResult is called for each visit added.
   *
   * @param aPlaceInfo
   *        The mozIPlaceInfo object[s] containing the information to store or
   *        update.  This can be a single object, or an array of objects.
   * @param [optional] aCallback
   *        A mozIVisitInfoCallback object which consists of callbacks to be
   *        notified for successful and/or failed changes.
   *
   * @throws NS_ERROR_INVALID_ARG
   *         - Passing in NULL for aPlaceInfo.
   *         - Not providing at least one valid guid, or uri for all
   *           mozIPlaceInfo object[s].
   *         - Not providing an array or nothing for the visits property of
   *           mozIPlaceInfo.
   *         - Not providing a visitDate and transitionType for each
   *           mozIVisitInfo.
   *         - Providing an invalid transitionType for a mozIVisitInfo.
   */
  [implicit_jscontext]
  void updatePlaces(in jsval aPlaceInfo,
                    [optional] in mozIVisitInfoCallback aCallback);

  /**
   * Checks if a given URI has been visited.
   *
   * @param aURI
   *        The URI to check for.
   * @param aCallback
   *        A mozIVisitStatusCallback object which receives the visited status.
   */
  void isURIVisited(in nsIURI aURI,
                    in mozIVisitedStatusCallback aCallback);
};