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

#include "nsIDOMXULElement.idl"


/**
 * Represents a web service that supports webmail services such as Yahoo! Mail
 * and Gmail.
 *
 * This interface has no methods on it. We use it to determine e.g.
 * which services to place under the Webmail folder in the AS&S sidebar.
 */
[scriptable, uuid(d1a8ceeb-b8a2-4e5d-9186-acd3952dba56)]
interface flockIMailWebService : flockILoginWebService {
};


/**
 * Represents a web service account for a webmail service such as
 * Yahoo! Mail or Gmail.
 */
[scriptable, uuid(6a168a79-cdfc-43ef-ba92-7c5815d34b0e)]
interface flockIWebmailAccount : 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,
   *         newestMessageDate,
   *         unreadMesageCount,
   *         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();

  /**
   * Flock may detect, perhaps after a failed API call, that this account's
   * session has expired.
   *
   * DEFAULT IMPLEMENTATION: Yes.
   *
   * @return true if the account's session has expired.
   */
  boolean isSessionExpired();

  /**
   * 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();
};
