thunderbird-dev 11.0.1+build1-0ubuntu2 / usr / share / idl / thunderbird-11.0.1 / nsINntpUrl.idl

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * 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.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Joshua Cranmer <Pidgeot18@gmail.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"
#include "MailNewsTypes2.idl"

interface nsIMsgDBHdr;
interface nsINNTPNewsgroupPost;

typedef long nsNewsAction;

/**
 * Represents specific attributes to a URL for news usage.
 *
 * Note that the urls represented by this interface can be one of five schemes:
 * [s]news, nntp[s], or news-message. Any URI that is valid under RFC 5538 will
 * be accepted. However, it is possible for some queries to be invalid. There
 * are also a few important things to note:
 *
 * - Missing authorities in [s]news: URIs cause nsIMsgMailNewsUrl::server and
 *   nsIMsgMessageUrl::folder to be null.
 * - nsIMsgMailNewsUrl::server and nsIMsgMessageUrl::folder will be null if the
 *   specified server does not actually exist. In addition, the folder is null
 *   if the group is not currently subscribed on that server.
 * - Although news-message URIs are parsable, there is no protocol handler
 *   associated with this url. To run these, you should convert these to the
 *   corresponding [s]news or nntp URL, and set the original one in
 *   nsIMsgMessageUrl::uri and ::originalSpec.
 * - A URI that results in an ActionUnknown will not be run.
 * - Cancel URIs require the original spec to also be set, so it can find both
 *   the message ID and the group/key combination.
 * * Some actions require either a group or a message id. Since actions can be
 *   set after the fact, these conditions are not verified.
 */
[scriptable, uuid(5f250c8c-d6b7-48b7-8ff4-7ff51dba19ae)]
interface nsINntpUrl : nsISupports {
  /// For ActionPostArticle URIs, the message to be posted.
  attribute nsINNTPNewsgroupPost messageToPost;

  /**
   * The action that this URL will take when run.
   *
   * Most actions can be automatically determined from the URL spec as follows:
   *
   * 1. The query string is searched for the appropriate action.
   *
   * 2. A non-empty message ID or key is found (sets ActionFetchArticle).
   *
   * 3. A non-empty group is found (ActionGetNewNews or ActionListGroups).
   */
  attribute nsNewsAction newsAction;

  /// For ActionGetNewNews URIs, whether or not to get older messages.
  attribute boolean getOldMessages;

  /**
   * The group portion of the URI, if one is present.
   *
   * This group name is fully unescaped; if you need to construct news URLs with
   * this value, be sure to escape it first.
   */
  readonly attribute ACString group;

  /// The message ID portion of the URI, if one is present
  readonly attribute ACString messageID;

  /// The message key portion of the URI or nsMsgKey_None if not present
  readonly attribute unsigned long key;

  /// The action of this news URI could not be determined
  const nsNewsAction ActionUnknown = 0;
  /// Fetch the contents of an article
  const nsNewsAction ActionFetchArticle = 1;
  /// Fetch the part of an article (requires ?part=)
  const nsNewsAction ActionFetchPart = 2;
  /// Save the contents of an article to disk
  const nsNewsAction ActionSaveMessageToDisk = 3;
  /// Cancel the article (requires ?cancel)
  const nsNewsAction ActionCancelArticle = 4;
  /// Post an article
  const nsNewsAction ActionPostArticle = 5;
  /// List the non-expired ids in the newsgroup (requires ?list-ids)
  const nsNewsAction ActionListIds = 6;
  /// Do an online newsgroup search (requires ?search)
  const nsNewsAction ActionSearch = 7;
  /// Retrieve new messages from the server
  const nsNewsAction ActionGetNewNews = 8;
  /// List groups for subscribe
  const nsNewsAction ActionListGroups = 9;
  /// List new groups for subscribe (requires ?new-groups)
  const nsNewsAction ActionListNewGroups = 10;

  /// Constant for the default NNTP over ssl port number
  const PRInt32 DEFAULT_NNTP_PORT = 119;

  /// Constant for the default NNTP over ssl port number
  const PRInt32 DEFAULT_NNTPS_PORT = 563;
};