/*
 * 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 "flockIWebService.idl"

#include "nsIDOMXULElement.idl"


/**
 * Represents a web service that supports webmail services such as Yahoo! Mail
 * and Gmail.
 */
[scriptable, uuid(cb6b5caa-5e8b-4981-8e7e-c0e87b3c44ee)]
interface flockIMailWebService : flockIWebService {
  /*
   * Retrieve the login URL for the service.
   *
   * DEFAULT IMPLEMENTATION: Yes.
   *
   * @return The login URL for the service.
   */
  AString getLoginURL();
};


/**
 * Represents a web service account for a  webmail service such as
 * Yahoo! Mail or Gmail.
 */
[scriptable, uuid(51AFE3DF-5095-42B0-8310-4A0A87DF0024)]
interface flockIMailWebServiceAccount : flockIWebServiceAccount {
  /*
   * Retrieve the compose message URL for the service.
   *
   * DEFAULT IMPLEMENTATION: Yes.
   *
   * @param aMailParams (in) The mail parameters in either of the following
   *                         formats:
   *                         1) mailto:foo@bar.com?subject=msg1&body=msg2...
   *                         2) to=foo@bar.com&subject=mesg1&body=msg2...
   * @return The compose message URL for the service.
   */
  AString getComposeURL(in AString aMailParams);

  /*
   * Does any special handling necessary after the compose URL has loaded.
   *
   * DEFAULT IMPLEMENTATION: Yes.
   *
   * @param aComposeURL (in) The compose message URL for the service.
   * @param aTabBrowser (in) The tab browser which contains the compose page.
   */
  void onComposeURLLoaded(in AString aComposeURL,
                          in nsIDOMXULElement aTabBrowser);

  /*
   * Retrieve the account email address.
   *
   * DEFAULT IMPLEMENTATION: No.
   *
   * @return The account email address.
   */
  AString getEmailAddress();

  /*
   * Retrieve the inbox URL for the account.
   *
   * DEFAULT IMPLEMENTATION: Yes.
   *
   * @return The inbox URL for the account.
   */
  AString getInboxURL();

  /*
   * Retrieve the unread messages for the account.
   *
   * DEFAULT IMPLEMENTATION: Yes.
   *
   * @param aCheckNow (in) True to query the webmail service for new unread
   *                       messages before returning the unread messages.
   * @return The unread messages in a JSON string containing:
   *         lastCheckedDate,
   *         array of messages (containing; from, subject and the message URL).
   */
  AString getUnreadMessages(in boolean aCheckNow);

  /*
   * Retrieve the URL to upgrade to the service's pro account.
   *
   * DEFAULT IMPLEMENTATION: Yes.
   *
   * @return A JSON string containing the title of the pro account
   *         (eg Yahoo! Mail Plus) and the URL to upgrade to the pro account.
   */
  AString getUpgradeAccount();

  /*
   * Is this the primary webmail account?
   *
   * DEFAULT IMPLEMENTATION: Yes.
   *
   * @return true if this is the primary webmail account.
   */
  boolean isPrimary();

  /*
   * Refreshes the unread message list from the webmail service.
   *
   * DEFAULT IMPLEMENTATION: Yes.
   */
  void refreshUnreadMessageList();

  /*
   * Sets the account as the primary webmail account and unsets the former.
   *
   * DEFAULT IMPLEMENTATION: Yes.
   */
  void setAsPrimary();
};
