/**
 * 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 "nsISupports.idl"
#include "nsISimpleEnumerator.idl"
#include "nsIDictionary.idl"
#include "flockIError.idl"
#include "flockIListener.idl"
#include "flockIMediaItem.idl"
#include "flockIPhotoUpload.idl"

/**
 * A generic JavaScript wrapper for Facebook's api.
 *
 * Reference: http://developers.facebook.com/index.php
 *
 * All api calls except auth.createToken() and auth.getSession() are exposed.
 * These calls are wrapped in the authenticate() method.
 */
[scriptable, uuid(53b077f0-6155-11db-b0de-0800200c9a66)]
interface flockIFacebookAPI: nsISupports
{
  attribute AString uid;
  readonly attribute boolean isLoggedIn;

  /**
   * Authenticate with Facebook using the desktop method
   *
   * @li 1) call auth.createToken() to create a shared token
   * @li 2) open a window with Facebook's API authorization page
   * @li 3) call auth.getSession() to get session/secret for subsequent calls.
   *
   * Notes:
   *   Ability to directly call auth.createToken() is not exposed.
   *   Ability to directly call auth.getSession() is not exposed.
   *
   * @param aListener (in) a flockIListener which responds whether the user
   *                       was successful authenticated / session setup
   */ 
  void authenticate(in flockIListener aListener);

  void deauthenticate();

  /**
   * Get a list of identifiers for friends of the authenticated user
   *
   * @param aListener (in) a flockIListener which responds onSuccess with the
   *                       list of identifers for the user's friends.
   *                       (example identifier: @c iPF_ahrjO4z3fpYh8-ySIMA.. )
   */
  void friendsGet(in flockIListener aListener);

  /**
   * Get a list containing all notifications of the currently logged in user
   *
   * @param aListener (in) a flockIListener which responds onSuccess with the
   *                       notifications list
   */
  void notificationsGet(in flockIListener aListener);

  /**
   * Get a list of pending friends request
   */
  void requestsGet(in flockIListener aListener);

  /**
   * Get a struct of messages count data
   */
  void messagesCount(in flockIListener aListener);

  /**
   * Check if the session is still valid
   *
   * @param aListener (in) a flockIListener which responds onSuccess if
   *                       session is still valid, or onError if the session
   *                       is not or there were other problems.
   */
  void sessionPing(in flockIListener aListener);

  /**
   * Get information for a list of users (specified by identifiers)
   *
   * @param aListener (in) a flockIListener which responds onSuccess with a
   *                       wrappedJS object. The object correspond to the
   *                       JSON response from Facebook.
   *                       see: http://developer.facebook.com/documentation.php
   * 
   * @param users (in) a comma seperated list of users for which to retrieve
   *                   info.
   *
   * @param fields (in) an optional comma seperated list of fields requested
   *                    from the service (ex: @c 'clubs,books,birthday' ).
   *                    If not specified the query will be for a (flock)
   *                    default set of fields.
   */
  void usersGetInfo(in flockIListener aListener,
                    in AString users,
                    in AString fields);

  /**
   * Get the list of users, friends of the current authenticated user,
   * who uploaded at least one photo since aLastSeen
   *
   * @param aListener (in) a flockIListener which responds onSuccess with a
   *                       nsISimpleEnumerator of property bags. Each property
   *                       bag contains:
   *                       AString uid: the user id on Facebook
   *                       Int32 count: the number of photos uploaded
   *                       since aLastSeen
   *
   *
   * @param aLastSeen (in) the date from which we want to observe updates,
   *                       as a string containing the number of seconds
   *                       since Epoch.
   *
   */
  void getUpdatedMediaFriends(in flockIListener aListener,
                              in string aLastSeen);

  void eventsGetInWindow();
  void friendsGetAppUsers();
  void friendsGetTyped();
  void friendsAreFriends();
  void messagesGetCount();
  void photosGetAlbums();
  void photosGetCommentCount();
  void photosGetFromAlbum();
  void photosGetOfUser();
  void pokesGetCount();

  string getFacebookURL(in string aUrlType, in string aFriendId);

  /**
   * Get a list of albums for a desired user
   *
   * @param aListener (in) A flockIListener which responds
   *                       flickIListener#onSuccess() with an enumerator of
   *                       flockIPhotoAlbum.
   * @param aUserId (in) A user id to get albums for.
   */
  void getAlbums(in flockIListener aListener, in AString aUserId);

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

  /**
   * Get a list of photos, optionally from a particular album
   *
   * @param aListener (in) A flockIListener which responds
   *                       flockIListener#onSuccess() with an enumerator of
   *                       flockIPhotoAlbum.
   * @param aSubj (in) [optional] Return only photos tagged with this user's
   *                              user id.
   * @param aAlbumID (in) [optional] Return photos only from this album.
   * @param aPidList (in) [optional] Only return photos form this comma
   *                                 seperated list.
   *
   * Note: if aSubj is set then only photos tagged with the user id will
   *       be returned as a subset of the other to params.
   */
  void getPhotos(in flockIListener aListener,
                 in AString aSubj,
                 in AString aAlbumID,
                 in AString aPidList);

  /**
   * Upload photos to Facebook from the Flock Photo Uploader.
   *
   * @param aListener (in) A flockIPhotoUploadAPIListener which responds
   *                       flockIPhotoUploadAPIListener#onResult() with the
   *                       XML response.
   * @param aPhoto (in) An AString containing the full filename of the photo
   *                    to upload.
   * @param aParams (in) An nsIPropertyBag2 containing paramaters to pass to
   *                     flockIPhotoAPI#upload2.
   * @param aUpload (in) A flockIPhotoUpload.
   */
  void uploadPhotosViaUploader(in flockIPhotoUploadAPIListener aListener,
                               in AString aPhoto,
                               in nsIPropertyBag2 aParams,
                               in flockIPhotoUpload aUpload);

  /**
   * Tag photos in Facebook
   * @param aListener (in) A flockIListener which responds...
   * @param aPid (in) An AString containing the id of the photo to be tagged.
   * @param aTagUid (in) An AString containing the user id of the user being
   *                     tagged. Either aTagUid or aTagText must be
   *                     specified.
   * @param aTagText (in) An AString containing some text identifying the
   *                      person being tagged. Either aTagUid or aTagText
   *                      must be specified. This parameter is ignored if
   *                      aTagUid is specified.
   * @param aX (in) An AString containing the horizontal position of the tag,
   *                as a percentage from 0 to 100 from the left of the photo.
   * @param aY (in) An AString containing the vertical position of the tag,
   *                as a percentage from 0 to 100 from the top of the photo.
   * @param aTags (in) An AString containing a JSON-serialized array
   *                   representing a list of tags to be added to the photo.
   *                   If the aTags parameter is specified, the aX, aY,
   *                   aTagUid, and aTagText parameters are ignored. Each
   *                   tag in the list must specify: "x", "y", and either
   *                   the user id "uid" or free-form "text"
   *                   identifying the person being tagged. An example of
   *                   this is the string:
   *                     [ {"x":"30.0","y":"30.0","uid":1234567890},
   *                       {"x":"70.0","y":"70.0","text":"some person"} ]
   */
  void addTag(in flockIListener aListener,
              in AString aPid,
              in AString aTagUid,
              in AString aTagText,
              in AString aX,
              in AString aY,
              in AString aTags);

  /**
   * Set the status of the current user.
   *
   * @param aListener (in) A flockIListener which responds... (may be null)
   * @param aFQLQuery (in) An AString containing the new status text.
   *                       Leave blank to clear the status.
   */
  void setStatus(in flockIListener aListener,
                 in AString aNewStatus);


  /**
   * Perform a FQL query.
   *
   * @param aListener (in) A flockIListener which responds
   *                       flockIListener#onSuccess() with the XML response.
   * @param aFQLQuery (in) An AString containing the FQL query to perform.
   */
  void doFQLQuery(in flockIListener aListener, in AString aFQLQuery);

  /**
   * Create a facebookPhoto ojbect
   */
  flockIMediaItem createPhoto();
};
