/*
 * 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 "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://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 *
 * @see flockISocialWebServiceAccount
 */
[scriptable, uuid(98332f29-f973-40c5-8cb1-6d93b1064fb1)]
interface flockISocialWebService : flockIWebService {
  /**
   * 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);

  /**
   * 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://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 *
 * @see flockISocialWebService
 */
[scriptable, uuid(c43a99f7-0c33-4f0b-9a97-485f2d5eb8ca)]
interface flockISocialWebServiceAccount : flockIWebServiceAccount {
  
  /** Indicates whether accounts have friend actions */
  readonly attribute boolean hasFriendActions;
  
  /** Indicates whether accounts have status message for display */
  readonly attribute boolean isStatusSupported;
  
  /** 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 aListener (in) aListener.onSuccess() will be called
   *        back when the call succeeds
   */
  void setStatus(in AString aStatusMessage, in flockIListener aListener);
  
  /**
   * 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();
  
  /**
   * Returns an array of action descriptors. Each action descriptor has the
   * following fields:
   * o label - the name of the action as it should be displayed in the UI
   * o icon - the chrome address of the icon graphic corresponding to the action
   *     (optional)
   * o spec - possible values:
   *   o "newtab:<url>" - tells the UI to open a new tab with the specified URL
   *   o "mediaquery:<query>" - tells the UI to open the media bar with the
   *       specified stream
   *   o "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. 
   *
   * @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();

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

  /**
   * Returns an array of action descriptors. Each action descriptor has the
   * following field:
   * o spec - possible values:
   *   o "newtab:<url>" - tells the UI to open a new tab with the specified URL
   *   o "mediaquery:<query>" - tells the UI to open the media bar with the
   *       specified stream
   *   o "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. 
   *
   * When some piece of content is dragged onto a FriendCard to be shared with
   * that friend, getSharingAction() is called to find out how this service
   * wants to share that particular piece of content. The nsITransferable object
   * is passed in as an argument so that the service can switch sharing methods
   * based on the type of content, if desired.
   *
   * @param aFriendURN (in) the RDF node ID of the friend for whom we are
   *        trying to get a list of actions for.
   * @param aTransferable (in) use to determine type of content
   * @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 getSharingAction(in AString aFriendURN, in nsITransferable aTransferable);

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

  /**
   * Returns an action spec to be performed if 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.
   */
  AString getPostLinkAction(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);
};
