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


interface nsITransferable;


/**
 * A "Social" web service is one which supports the concept of "contacts"
 * (a.k.a. "friends", "buddies", etc.).  This generally means that Flock will
 * try to import the contacts so that they can appear in the browser UI, along
 * with relevant notifications as to their status, new content, etc.
 *
 * More documentation here:
 * http://developer.flock.com/wiki/Accounts_Management
 *
 * @see flockISocialAccount
 */
[scriptable, uuid(04f98050-f012-11dc-95ff-1569200c9a66)]
interface flockISocialWebService : flockILoginWebService {
  /**
   * Clear media notification for a given person
   *
   * Typically, this function is called when the user consumes the
   * media of one of his friends. This function set the unseen items
   * count to 0, dismissing the notification for that friend.
   *
   * @param aPersonUrn (in) the RDF URN of the person to clear media
   */
  void markAllMediaSeen(in AString aPersonUrn);

  /**
   * Parse the provided status message text into a DOM element.
   */
  nsIDOMElement parseStatus(in nsIDOMDocument aDocument,
                            in AString aStatusMessage);

  /**
   * Maximum length (in characters) that a status message can be.
   * For services which do not support status, set to 0.
   */
  readonly attribute long maxStatusLength;
};


/**
 * Represents an account with a "social" web service.
 *
 * More documentation here:
 * http://developer.flock.com/wiki/Accounts_Management
 *
 * @see flockISocialWebService
 */
[scriptable, uuid(6506d5c9-1598-4edb-b7be-8956a23cd22d)]
interface flockISocialAccount : flockIWebServiceAccount {
  
  /** Indicates whether accounts have friend actions */
  readonly attribute boolean hasFriendActions;
  
  /** Indicates whether accounts have me status message for display */
  readonly attribute boolean isMeStatusSupported;
  
  /** Indicates whether accounts have friends status message for display */
  readonly attribute boolean isFriendStatusSupported;

  /** Indicates whether accounts status message can be set via API call */
  readonly attribute boolean isStatusEditable;

  /** Indicates whether accounts support a "Post Link" action */
  readonly attribute boolean isPostLinkSupported;

  /** Indicates whether accounts support a "My Media Favorites" action */
  readonly attribute boolean isMyMediaFavoritesSupported;

  /**
   * Set the status message.
   *
   * @param aStatusMessage (in) the status message to be set
   * @param aFlockListener (in) aFlockListener.onSuccess() will be called
   *        back when the call succeeds
   */
  void setStatus(in AString aStatusMessage, in flockIListener aFlockListener);
  
  /**
   * Returns the status string to be used in the editor widget
   *
   * @return the editable status string
   */
  AString getEditableStatus();
  
  /**
   * Formats a status message as it ought to be displayed.
   *
   * @param aStatusMessage (in) the pre-formatted status string
   * @return the full status message
   */
  AString formatStatusForDisplay(in AString aStatusMessage);

  /**
   * Formats a friend activity description as it ought to be displayed.
   *
   * @param aFriendActivityUrn (in) the RDF node ID of the friend activity
   *        to be used.
   * @return the formatted friend activity description
   */
  AString formatFriendActivityForDisplay(in AString aFriendActivityUrn);

  /**
   * Returns an array of me-notification descriptors, each of which consists of
   * the following pieces of information:
   * - tooltip (used as a tooltip in the UI, eg. "Poke", "Message",
   *            "Friend Request"...)
   * - metricsName (the name to be reported to the metrics services when the
                    me-notificaitons is clicked)
   * - class (class name)
   * - count (the number of new notifications of this type. 0 always means no
   *          new. -1 means that there are new noties, but we can't tell how 
              many.)
   * - URL (to be opened in a new tab, to view the actual notifications on the
   *        web service) 
   *
   * @return a JSON string, since we know it will only ever be called from
   *         JavaScript, and JSON is easier to deal with than nsIArrays, etc. 
   */
  AString getMeNotifications();

  /**
   * Formats a friend update type description as it ought to be displayed.
   *
   * @param aLastUpdateType (in) the last update type
   * @param aStatus (in) the status of the last update
   * @return the formatted friend activity description
   */
  AString getFormattedFriendUpdateType(in AString aLastUpdateType,
                                       in AString aStatus);

  /**
   * Returns a JSON string representation of an array of action descriptors.
   * Each action descriptor has the following fields:
   * <ul>
   * <li><strong>label</strong> - the name of the action as it should be
   *     displayed in the UI</li>
   * <li><strong>icon</strong> - the chrome address of the icon graphic
   *     corresponding to the action (optional)</li>
   * <li><strong>spec</strong> - possible values:<ul>
   *   <li>"newtab:<url>" - tells the UI to open a new tab with the specified
   *       URL</li>
   *   <li>"newwindow:<url>" - tells the UI to open a new window with the
   *       specified URL</li>
   *   <li>"mediaquery:<query>" - tells the UI to open the media bar with the
   *       specified stream</li>
   *   <li>"method:<interface>:<methodname>" - tells the UI to QI the service
   *       to the specified interface and then call the specified method.
   *       aFriendURN is always passed in as a parameter to this method.</li>
   *   </ul></li>
   * </ul>
   * The newtab and newwindow action spec strings may contain "%currentURL%" as
   * a substitution, which will be replaced with the URL of the current page.
   *
   * @param aFriendURN (in) the RDF node ID of the friend for whom we are
   *        trying to get a list of actions for.
   * @return a JSON string, since we know it will only ever be called from
   *         JavaScript, and JSON is easier to deal with than nsIArrays, etc.
   */
  AString getFriendActions(in AString aFriendURN);
  
  /**
   * @return the number of friends associated with this account.
   */
  long getFriendCount();

  /**
   * Returns an enumerator on the friends for this account.
   *
   * @return a nsISimpleEnumerator of coop Identities.
   */
  nsISimpleEnumerator enumerateFriends();

  /**
   * Returns the URL of the invite friends page associated with the account
   *
   * @return the URL of the invite friends page.
   */
  AString getInviteFriendsURL();

  /**
   * Performs a service-specific action to share arbitrary content with
   * a friend of the logged-in user.
   *
   * @param aFriendURN (in) the RDF node ID of the friend with whom we are
   *        sharing content.
   * @param aTransferable (in) The content to be shared.
   */
  void shareWithFriend(in AString aFriendURN, in nsITransferable aTransferable);

  /**
   * Returns the URL of the profile page associated with the identity specified
   * by aFriendURN.
   *
   * @return the URL of the friend profile page
   */
  AString getProfileURLForFriend(in AString aFriendURN);

  /**
   * Performs a service-specific action to post arbitrary data when the user
   * executes the "Post Link" action for this account.
   *
   * @param aTransferable (in) resulting from a drag and drop onto the Post
   *        Link button. Extract the URL from this transferable. If null, then
   *        the Post Link button was clicked: use the current tab's URL.
   */
  void postLink(in nsITransferable aTransferable);

  /**
   * Clear me notifications of a certain type
   *
   * Typically, this function is called when the user consumes
   * a notification of type aType from their me-card.
   *
   * @param aType (in) the type of me notification to clear
   */
  void markAllMeNotificationsSeen(in AString aType);

  /**
   * Sends a "Check out Flock!" kind of message to the selected friend.
   *
   * @param aFriendURN (in) the URN of the friend we are messaging.
   */
  void shareFlock(in AString aFriendURN);

  /**
   * Perform any service-specific action with the selected friend.
   *
   * @param aAction (in) arbitrary string to select an action.
   * @param aFriendURN (in) the URN of the friend to act upon.
   * @param aActivityURN (in) optional URN of the activity to act upon.
   */
  void friendAction(in AString aAction,
                    in AString aFriendURN,
                    in AString aActivityURN);
};
