gecko/toolkit/components/places/mozIAsyncHistory.idl
Nicholas Nethercote b89a8ac1c0 Bug 905017 (part 1) - Minimize inclusions of JS engine headers in .h and .idl files. r=billm.
--HG--
extra : rebase_source : 984c61ab12f46be0509b1ce0d458d9a6e5841c64
2013-08-17 15:50:18 -07:00

189 lines
5.5 KiB
Plaintext

/* 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);
};