gecko/toolkit/components/places/mozIAsyncHistory.idl
Philipp von Weitershausen 3cf892bb40 Bug 676110 - Part 1: IDL changes for mozIVisitInfoCallback::handleCompletion. r=mak sr=rstrong
--HG--
extra : rebase_source : c18547a0bfcf74f7742683133b5a826c3ce9a63c
2011-08-19 10:11:20 -07:00

190 lines
5.4 KiB
Plaintext

/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is Places Async History API.
*
* The Initial Developer of the Original Code is
* the Mozilla Foundation.
* Portions created by the Initial Developer are Copyright (C) 2010
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Shawn Wilsher <me@shawnwilsher.com>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
interface nsIURI;
interface nsIVariant;
%{C++
#include "jsapi.h"
%}
/**
* @status EXPERIMENTAL
*/
[scriptable, uuid(1a3b1260-4bdb-45d0-a306-dc377dd9baa4)]
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;
/**
* The sessionId of this visit.
*
* @see nsINavHistory.idl
*/
readonly attribute long long sessionId;
};
/**
* @status EXPERIMENTAL
*/
[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;
};
/**
* @status EXPERIMENTAL
*/
[scriptable, uuid(1f266877-2859-418b-a11b-ec3ae4f4f93d)]
interface mozIVisitInfoCallback : nsISupports
{
/**
* Called when the given mozIPlaceInfo object could not be processed.
*
* @param aResultCode
* nsresult indicating the failure reason.
* @param aPlaceInfo
* The information that was being entered into the database.
*/
void handleError(in nsresult aResultCode,
in mozIPlaceInfo aPlaceInfo);
/**
* Called for each visit added, title change, or guid change when passed to
* mozIAsyncHistory::updatePlaces. If more than one operation is done for
* a given visit, only one callback will be given (i.e. title change and
* add visit).
*
* @param aPlaceInfo
* The information that was being entered into the database.
*/
void handleResult(in mozIPlaceInfo aPlaceInfo);
/**
* Called when the mozIAsyncHistory::updatePlaces has finished processing
* all mozIPlaceInfo records.
*/
void handleCompletion();
};
/**
* @status EXPERIMENTAL
*/
[scriptable, uuid(f79ca67c-7e57-4511-a400-ea31001c762f)]
interface mozIAsyncHistory : nsISupports
{
/**
* Adds a set of visits for one or more mozIPlaceInfo objects, and updates
* each mozIPlaceInfo's title or guid.
*
* @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);
};