/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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 nsIMsgDBHdr;
interface nsIMsgThread;

/**
 * nsIJSIterator implements the JavaScript iterator protocol.
 * For details on the JS side, see:
 * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol
 */
[scriptable, uuid(4406175e-1aa4-414c-ad7c-86bd76e102f8)]
interface nsIJSIterator : nsISupports {
  /**
   * @returns {{value: Object, done: Boolean}} the iteration state.
   * 'value' holds the next item, and 'done' flags the end of the iteration.
   * (notionally, both 'value' and 'done' are always present, but a missing
   * 'done' is considered to be false, and 'value' should be ignored if
   * 'done' is true, according to the protocol).
   */
  [implicit_jscontext]
  jsval next();
};


/**
 * nsIMsgEnumerator is an object for iterating forward over an ordered set of
 * messages (nsIMsgHdrs). There is no provision to reset the iteration.
 */
[scriptable, uuid(5760cb6d-1a71-485f-ad85-5a98a9da2104)]
interface nsIMsgEnumerator : nsISupports {
  /**
   * Implements the JavaScript iterable protocol, which allows
   * for...of constructs and the like.
   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol
   * NOTE: the nsIMsgEnumerator is "used up" by iterator(), just as it is by
   * getNext()/hasMoreElements(). So you can only loop over the enumerator once.
   */
  [symbol]
  nsIJSIterator iterator();

  /**
   * Called to determine whether or not there are any messages remaining
   * to be retrieved from the enumerator.
   *
   * @returns true if getNext() may be called to fetch a message, or
   *          false if there are no more messages.
   */
  boolean hasMoreElements();

  /**
   * Called to retrieve the next message in the set.
   *
   * @returns the next element in the enumeration.
   */
  nsIMsgDBHdr getNext();
};

/**
 * nsIMsgThreadEnumerator is an object for iterating forward over an ordered set of
 * message threads (nsIMsgThread). There is no provision to reset the iteration.
 */
[scriptable, uuid(e39ae1a8-2b94-4f2b-abb4-250171047501)]
interface nsIMsgThreadEnumerator : nsISupports {
  /**
   * Implements the JavaScript iterable protocol, which allows
   * for...of constructs and the like.
   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol
   * NOTE: the nsIMsgThreadEnumerator is "used up" by iterator(), just as it is by
   * getNext()/hasMoreElements(). So you can only loop over the enumerator once.
   */
  [symbol]
  nsIJSIterator iterator();

  /**
   * Called to determine whether or not there are any messages remaining
   * to be retrieved from the enumerator.
   *
   * @returns true if getNext() may be called to fetch a message, or
   *          false if there are no more messages.
   */
  boolean hasMoreElements();

  /**
   * Called to retrieve the next thread in the set.
   *
   * @returns the next element in the enumeration.
   */
  nsIMsgThread getNext();
};
