michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: /**
michael@0:  * Used to enumerate over elements defined by its implementor.
michael@0:  * Although hasMoreElements() can be called independently of getNext(),
michael@0:  * getNext() must be pre-ceeded by a call to hasMoreElements(). There is
michael@0:  * no way to "reset" an enumerator, once you obtain one.
michael@0:  *
michael@0:  * @version 1.0
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(D1899240-F9D2-11D2-BDD6-000064657374)]
michael@0: interface nsISimpleEnumerator : nsISupports {
michael@0:   /**
michael@0:    * Called to determine whether or not the enumerator has
michael@0:    * any elements that can be returned via getNext(). This method
michael@0:    * is generally used to determine whether or not to initiate or
michael@0:    * continue iteration over the enumerator, though it can be
michael@0:    * called without subsequent getNext() calls. Does not affect
michael@0:    * internal state of enumerator.
michael@0:    *
michael@0:    * @see getNext()
michael@0:    * @return true if there are remaining elements in the enumerator.
michael@0:    *         false if there are no more elements in the enumerator.
michael@0:    */                                            
michael@0:   boolean hasMoreElements();
michael@0: 
michael@0:   /**
michael@0:    * Called to retrieve the next element in the enumerator. The "next"
michael@0:    * element is the first element upon the first call. Must be
michael@0:    * pre-ceeded by a call to hasMoreElements() which returns PR_TRUE.
michael@0:    * This method is generally called within a loop to iterate over
michael@0:    * the elements in the enumerator.
michael@0:    *
michael@0:    * @see hasMoreElements()
michael@0:    * @throws NS_ERROR_FAILURE if there are no more elements
michael@0:    *                          to enumerate.
michael@0:    * @return the next element in the enumeration.
michael@0:    */
michael@0:   nsISupports getNext();
michael@0: };