DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (31ec81b5d7bb)

VCS Links

Line Code
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 189 190 191 192 193 194 195 196 197 198 199 200 201 202
/* 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 mozILivemarkCallback;
interface mozILivemarkInfo;
interface mozILivemark;

interface nsINavHistoryResultObserver;

[scriptable, uuid(1dbf174c-696e-4d9b-af0f-350da50d2249)]
interface mozIAsyncLivemarks : nsISupports
{
  /**
   * Creates a new livemark
   *
   * @param aLivemarkInfo
   *        mozILivemarkInfo object containing at least title, parentId,
   *        index and feedURI of the livemark to create.
   * @param [optional] aCallback
   *        Invoked when the creation process is done.  In case of failure will
   *        receive an error code.
   *
   * @throws NS_ERROR_INVALID_ARG if the supplied information is insufficient
   *         for the creation.
   */
  void addLivemark(in jsval aLivemarkInfo,
                   [optional]in mozILivemarkCallback aCallback);

  /**
   * Removes an existing livemark.
   *
   * @param aLivemarkInfo
   *        mozILivemarkInfo object containing either an id or a guid of the
   *        livemark to remove.
   * @param [optional] aCallback
   *        Invoked when the removal process is done.  In case of failure will
   *        receive an error code.
   *
   * @throws NS_ERROR_INVALID_ARG if the id/guid is invalid.
   */
  void removeLivemark(in jsval aLivemarkInfo,
                      [optional]in mozILivemarkCallback aCallback);

  /**
   * Gets an existing livemark.
   *
   * @param aLivemarkInfo
   *        mozILivemarkInfo object containing either an id or a guid of the
   *        livemark to retrieve.
   * @param aCallback
   *        Invoked when the fetching process is done.  In case of failure will
   *        receive an error code.
   *
   * @throws NS_ERROR_INVALID_ARG if the id/guid is invalid or an invalid
   *         callback is provided.
   */
  void getLivemark(in jsval aLivemarkInfo,
                   in mozILivemarkCallback aCallback);

  /**
   * Reloads all livemarks if they are expired or if forced to do so.
   *
   * @param [optional]aForceUpdate
   *        If set to true forces a reload even if contents are still valid.
   *
   * @note The update process is asynchronous, observers registered through
   *       registerForUpdates will be notified of updated contents.
   */
  void reloadLivemarks([optional]in boolean aForceUpdate);
};

[scriptable, function, uuid(62a426f9-39a6-42f0-ad48-b7404d48188f)]
interface mozILivemarkCallback : nsISupports
{
  /**
   * Invoked when a livemark is added, removed or retrieved.
   *
   * @param aStatus
   *        Whether the request was completed successfully.
   *        Use Components.isSuccessCode(aStatus) to check this.
   * @param aLivemark
   *        A mozILivemark object representing the livemark, or null on removal.
   */
  void onCompletion(in nsresult aStatus,
                    in mozILivemark aLivemark);
};

[scriptable, uuid(6e40d5b1-ce48-4458-8b68-6bee17d30ef3)]
interface mozILivemarkInfo : nsISupports
{
  /**
   * Id of the bookmarks folder representing this livemark.
   */
  readonly attribute long long id;

  /**
   * The globally unique identifier of this livemark.
   */
  readonly attribute ACString guid;

  /**
   * Title of this livemark.
   */
  readonly attribute AString title;

  /**
   * Id of the bookmarks parent folder containing this livemark.
   */
  readonly attribute long long parentId;

  /**
   * The position of this livemark in the bookmarks parent folder.
   */
  readonly attribute long index;

  /**
   * Time this livemark's details were last modified.  Doesn't track changes to
   * the livemark contents.
   */
  readonly attribute PRTime lastModified;

  /**
   * The URI of the syndication feed associated with this livemark.
   */
  readonly attribute nsIURI feedURI;

  /**
   * The URI of the website associated with this livemark.
   */
  readonly attribute nsIURI siteURI;
};

[scriptable, uuid(9f6fdfae-db9a-4bd8-bde1-148758cf1b18)]
interface mozILivemark : mozILivemarkInfo
{
  // Indicates the livemark is inactive.
  const unsigned short STATUS_READY = 0;
  // Indicates the livemark is fetching new contents.
  const unsigned short STATUS_LOADING = 1;
  // Indicates the livemark failed to fetch new contents.
  const unsigned short STATUS_FAILED = 2;

  /**
   * Status of this livemark.  One of the STATUS_* constants above.
   */
  readonly attribute unsigned short status;

  /**
   * Reload livemark contents if they are expired or if forced to do so.
   *
   * @param [optional]aForceUpdate
   *        If set to true forces a reload even if contents are still valid.
   *
   * @note The update process is asynchronous, it's possible to register a
   *       result observer to be notified of updated contents through
   *       registerForUpdates.
   */
  void reload([optional]in boolean aForceUpdate);

  /**
   * Returns an array of nsINavHistoryResultNode objects, representing children
   * of this livemark.  The nodes will have aContainerNode as parent.
   *
   * @param aContainerNode
   *        Object implementing nsINavHistoryContainerResultNode, to be used as
   *        parent of the livemark nodes.
   */
  jsval getNodesForContainer(in jsval aContainerNode);

  /**
   * Registers a container node for updates on this livemark.
   * When the livemark contents change, an invalidateContainer(aContainerNode)
   * request is sent to aResultObserver.
   *
   * @param aContainerNode
   *        Object implementing nsINavHistoryContainerResultNode, representing
   *        this livemark.
   * @param aResultObserver
   *        The nsINavHistoryResultObserver that should be notified of changes
   *        to the livemark contents.
   */
  void registerForUpdates(in jsval aContainerNode,
                          in nsINavHistoryResultObserver aResultObserver);

  /**
   * Unregisters a previously registered container node.
   *
   * @param aContainerNode
   *        Object implementing nsINavHistoryContainerResultNode, representing
   *        this livemark.
   *
   * @note it's suggested to always unregister containers that are no more used,
   *       to free up the associated resources.  A good time to do so is when
   *       the container gets closed.
   */
  void unregisterForUpdates(in jsval aContainerNode);
};