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

/**
 * Represents a web service that supports uploading of rich media (eg. photos,
 * video).  Generally, a service that implements flockIMediaUplaodWebService
 * will also implement flockIMediaWebService.
 *
 * More documentation here:
 * http://developer.flock.com/wiki/Accounts_Management
 *
 * @see flockIMediaWebService
 * @see flockIMediaAccount
 * @see flockIMediaUploadAccount
 */
[scriptable, uuid(73596a3d-1234-4d97-8fd8-a46868fafa42)]
interface flockIMediaUploadWebService : flockILoginWebService {
  /**
   * Query the server to get information about the current user's account.
   *
   * @param aFlockListener (in) the listener used to pass the result.
   *                  onSuccess(result, topic) will be return,
   *                  only result holding a relevant value.
   *
   *                  result is a nsIPropertyBag2 holding the following values:
   *                  @li boolean isPremium;
   *                  @li string maxFileSize;
   *                  @li string maxSpace;
   *                  @li string usageUnits;
   *                  @li string usedSpace;
   *                  @li string username;
   */
  void getAccountStatus(in flockIListener aFlockListener);

  /**
   * Gets albums that are only upload endpoints.
   *
   * @param aFlockListener (in) Specifies a callback listener
   * @param aUsername (in) Specifies a username to operate the search as
   */
  void getAlbumsForUpload(in flockIListener aFlockListener,
                          in AString aUsername);

  void createAlbum(in flockIListener aFlockListener,
                   in AString aAccountId,
                   in AString aAlbumName);

  /**
   * Return true if the service supports aFeature, false otherwise.
   * Available features:
   *    fileName
   *    title
   *    description
   *    privacy
   *    tags
   *    notes (means notes associated to a specific point in the image)
   */
  boolean supportsFeature(in AString aFeature);

  /**
   * Upload one photo to the service
   * @param aFlockListener (in) the listener used to pass the result.
   *    onSuccess(result, topic) will be called, with result being
   *    a flockIMediaItem representing the photo on the service.
   * @param aUpload (in) the metadata for the photo
   * @param aFilename (in) the filename on the local hard disk
   *    (usually a copy of the original file in the user's profile dir)
   */
  void upload(in flockIPhotoUploadAPIListener aUploadListener,
              in flockIPhotoUpload aUpload,
              in AString aFilename);
};


/**
 * Represents a web service account that supports uploading of rich media (eg.
 * photos, video).
 *
 * @see flockIMediaWebService
 * @see flockIMediaAccount
 */
[scriptable, uuid(fe173aae-8f49-4bd4-beda-41ec1e09b232)]
interface flockIMediaUploadAccount : flockIMediaAccount {
};
