/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2008
 * 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"
#include "flockIPerson.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;
};

/**
 * Represents a web service that supports browsing of streams or collections of
 * rich media (eg. photos, video).
 *
 * More documentation here:
 * http://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 *
 * @see flockIMediaWebServiceAccount
 * @see flockIMediaUploadAccount
 */
[scriptable, uuid(C24095D7-428C-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.
   */
  void decorateForMedia(in nsIDOMHTMLDocument aDocument);

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

  void getAlbums(in flockIListener aListener, 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 aListener,
              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);
  
  /**
   * 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://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 *
 * @see flockIMediaWebService
 */
[scriptable, uuid(3DA68B30-5EE8-11DB-B0DE-0800200C9A66)]
interface flockIMediaWebServiceAccount : flockIWebServiceAccount {
};
