/*
 * 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 "flockIPerson.idl"
#include "nsISimpleEnumerator.idl"
#include "flockISocialWebService.idl"

[scriptable, uuid(9afb1665-34cc-4878-8522-3c9b8ab4d4d5)]
interface flockIPeopleUtils: nsISupports
{
  /**
   * Add a person to the friends list of a given account, on the local
   * storage. This function should only be called by back-end services,
   * and only to locally add people that are on the friends list of the
   * user on the server.
   *
   * @param aAccount : the account to add the person to
   * @param aPerson : the new person to be added
   *
   * @return the id of the newly added person in the storage layer
   */
  AString addPerson(in flockISocialWebServiceAccount aAccount,
                    in flockIPerson aPerson);

  /**
   * Remove a person from the friends list of a given account, on the local
   * storage. This function should only be called by back-end services,
   * and only to locally remove people that are no longer on the friends list
   * of the user on the server.
   *
   * @param aAccount : the account to remove the person from
   * @param aPerson : the person to be removed
   *
   * @return nothing
   */
  void removePerson(in flockISocialWebServiceAccount aAccount,
                    in flockIPerson aPerson);

  /**
   * Retrieves the person represented by aPersonUrn
   *
   * @param aPersonUrn : the urn of Person to return
   *
   * @return flockIPerson representation of person
   */
  flockIPerson getPerson(in AString aPersonUrn);

  /**
   * Increments the number of unseen media for a given friend. Currently
   * the UI is not exposing the number, only showing "new stuff/no new stuff".
   *
   * @param aAccount : the account to which the person is friend of
   * @param aPersonId : the id of the person who has new media
   * @param aCount : the number of new unseen media (NOT the total number)
   * @param aLatest : the timestamp of the most recent unseen media
   *                  for that person
   *
   * @return nothing
   */
  void incrementMedia(in flockISocialWebServiceAccount aAccount,
                      in AString aPersonId,
                      in long aCount,
                      in long long aLatest);

  /**
   * Cause the people icon in the Flockbar (close to the favorites toolbar)
   * to light up, indicating new information on the user's account.
   * It will stay orange until the user opens the people sidebar.
   *
   * @return nothing
   */
  void lightPeopleIcon();
};
