/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2009
 * http://flock.com
 *
 * This file may be used under the terms of the
 * GNU General Public License Version 2 or later (the "GPL"),
 * http://www.gnu.org/licenses/gpl.html
 *
 * 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.
 *
 * END FLOCK GPL
 */

#include "nsISupports.idl"
#include "flockIListener.idl"
#include "flockIWebServiceAPI.idl"

[scriptable, uuid(7A66AF86-1234-4C35-9CB1-D1A026CC5F73)]
interface flockIOnetAPI : flockIAuthenticatedAPI {

  /**
   * Create an album for this user
   *
   * @param aAccountId (in) The id of the account.
   * @param aAlbumTitle (in) The title of the new album to create.
   * @param aFlockListener (in) A flockIListener which responds
   *                       flockIListener#onSuccess() with the album that
   *                       was created.
   */
  void createAlbum(in flockIListener aFlockListener,
                   in AString aAccountId,
                   in AString aAlbumTitle);

  /**
   * Get the photo albums of a specified user.
   * @param aFlockListener (in) a flockIListener to use to return the albums
   *                        via flockIListener#onSuccess, or any errors
   *                        via flockIListener#onError.
   * @param aUsername (in) Username of the user
   */
  void getAlbums(in flockIListener aFlockListener, in AString aUsername);

  /**
   * Get the an XML feed from Onet
   * @param aFlockListener (in) a flockIListener to use to return the feed
   *                        via flockIListener#onSuccess, or any errors
   *                        via flockIListener#onError.
   * @param aFeedURL (in) URL of the feed to be parsed
   */
  void getFeed(in flockIListener aFlockListener,
               in AString aFeedURL);

  /**
   * Helper function to convert query string parameters into a form the Onet
   * API requires.
   * @param aMethodName (in) The API method name of the call
   * @param aParams (in) Parameters to encode for the call
   */
  nsISupports prepare(in AString aMethodName, in nsISupports aParams);

};
