/*
 * 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 "nsIDOMHTMLDocument.idl"
#include "nsIWritablePropertyBag2.idl"
#include "flockIWebService.idl"
#include "flockIListener.idl"
#include "flockIPhotoUpload.idl"
#include "flockIMediaItem.idl"


[scriptable, uuid(cfcffc53-7c57-418c-ae84-f66ddd7b3f77)]
interface flockIPhotoAlbum: nsISupports {
  attribute AString id;
  attribute AString title;
  attribute AString url;
  attribute boolean isPublic;
};

[scriptable, uuid(b208bef0-5658-11db-b0de-0800200c9a66)]
interface flockIMediaChannel: nsISupports {
  attribute AString id;
  attribute boolean supportsSearch;
  attribute AString title;
  attribute nsISimpleEnumerator subChannels;
};

/**
 * Represents a web service that supports browsing of streams or collections of
 * rich media (eg. photos, video).
 *
 * More documentation here:
 * http://developer.flock.com/wiki/Accounts_Management
 *
 * @see flockIMediaAccount
 * @see flockIMediaUploadAccount
 */
[scriptable, uuid(C24095D7-1234-4E28-A642-20F4F657C8C8)]
interface flockIMediaWebService : flockIWebService {
  /**
   * Adds to the document metadata indicating the presence (or not)
   * of media streams, in order to light up the media icon from the
   * URL bar.
   * @param aDocument (in) an HTML document to check
   * @param aAccount (in) the XPCOM account which has already been
   *        detected as logged in on this page.  If not provided, then no
   *        account was detected as being logged in for aDocument.
   */
  void decorateForMedia(in nsIDOMHTMLDocument aDocument,
                        in flockIWebServiceAccount aAccount);

  void findByUsername(in flockIListener aFlockListener, in AString aUsername);

  void getAlbums(in flockIListener aFlockListener, in AString aUsername);

  /**
   * Return the channel identified by AChannelId
   * @param AChannelId (in) the channel to return
   *
   * @return the media channel, or null if the channel doesn't exist
   */
  flockIMediaChannel getChannel(in AString AChannelId);

  /**
   * Enumerate through all channels
   *
   * @return a nsISimpleEnumerator of flockIMediaChannel
   */
  nsISimpleEnumerator enumerateChannels();

  /**
   * Return the formatter to display media item from this service
   *
   * @return a flockIMediaItemFormatter, or null if the default
   *         formatter should be used
   */
  flockIMediaItemFormatter getMediaItemFormatter();

  void migrateAccount(in AString aId, in AString aUsername);

  /**
   * Search service for photos.
   * @param aQuery (in) Specifies which media stream. Examples:
   *                    @li all
   *                    @li interestingness
   *                    @li user:44124365282@N01
   *                    @li user:44124365282@N01:sulfur
   *                    @li pool:35034354696@N01
   *
   *                    To specify that the stream should be filtered you
   *                    append ?mySearchTerm, like so:
   *                    @c user:44124365282@N01:sulfur?yosh
   *
   * @param aCount (in) The number of items you'd like to be returned.
   *                    Note that receiving this number is not guaranteed.
   *
   * @param aPage (in) Used in combination with aCount for pagination.
   *
   * @param aRequestId (in) Used to keep track of requests
   */
  void search(in flockIListener aFlockListener,
              in AString aQuery,
              in long aCount,
              in long aPage,
              in AString aRequestId);

  /**
   * For a given query, return whether or not it supports search.
   *
   * @param aQuery (in) The query in question.
   */
  boolean supportsSearch(in AString aQuery);

  /**
   * For a given query, return the URL of the associated icon.
   * (Most services will just return the same icon for any query)
   *
   * @param aQuery (in)
   */
  AString getIconForQuery(in AString aQuery);

  /**
   * Whether the service supports the concept of a user in the media bar.
   * This enables drill down into that user's media stream.
   */
  readonly attribute boolean supportsUsers;
};


/**
 * Represents an account with a media web service.
 *
 * More documentation here:
 * http://developer.flock.com/wiki/Accounts_Management
 *
 * @see flockIMediaWebService
 */
[scriptable, uuid(516ba5e4-ec91-4eae-b682-23c4132d94bf)]
interface flockIMediaAccount : flockIWebServiceAccount {
};
