pjs/mailnews/news/public/nsINNTPHost.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.0 (the "NPL"); you may not use this file except in
 * compliance with the NPL.  You may obtain a copy of the NPL at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the NPL is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
 * for the specific language governing rights and limitations under the
 * NPL.
 *
 * The Initial Developer of this code under the NPL is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
 * Reserved.
 */

#include "nsISupports.idl"

interface nsINNTPNewsgroup;
interface nsINNTPNewsgroupList;

[scriptable, uuid(6b128da0-d74f-11d2-b7f9-00805f05ffa5)]
interface nsINNTPHost : nsISupports {

    void Initialize(in string name, in long port);
    
    attribute boolean supportsExtensions;
    void AddExtension(in string extension);
    boolean QueryExtension(in string extension);

    attribute boolean postingAllowed;
    attribute boolean pushAuth;
    attribute unsigned long lastUpdatedTime;

    /* look up the newsgroup list for the given name */
    nsINNTPNewsgroupList GetNewsgroupList(in string name);

    /* given a newsgroup name, find or create the given name */
    nsINNTPNewsgroup FindNewsgroup(in string name, in boolean create);
    
    /* libnet callbacks for Dredd NNTP extensions
     * please document if you know how these work
     */
    void AddPropertyForGet(in string name, in string value);
    string QueryPropertyForGet(in string name);
    
    void AddSearchableGroup(in string name);
    boolean QuerySearchableGroup(in string name);
    
    void AddVirtualGroup(in string responseText);
    void SetIsVirtualGroup(in string name, in boolean isVirtual);
    boolean GetIsVirtualGroup(in string name
                           /*, nsIMsgGroupRecord inGroupRecord */);

    
    void AddSearchableHeader(in string headerName);
    boolean QuerySearchableHeader(in string headerName);

    /* this used to just call pane->GetMaster()->AddNewsGroup(url) */
    /* void AddSubscribedNewsgroup(in string url); */
    
    /* In response to an NNTP GROUP command, the server said
     * the group doesn't exist
     */
    void GroupNotFound(in string group, in boolean opening);
    
    /* Tell the subscribe pane about a new newsgroup we noticed. */
    /* XXX should xactive flags be a long? */
    void AddNewNewsgroup(in string name,
                         in long first, in long last,
                         in string flags, in boolean xactiveFlags);
    
    /* formerly GetNewsRCCount() */
    /* After displaying a list of newsgroups, we need the NNTP module to go and
       run "GROUP" commands for the ones for which we don't know the unread
       article count.  This function returns a count of how many groups we think
       we're going to need this for (so we can display progress in a reasonable
       way).
    */
    long GetNumGroupsNeedingCounts();
  
    /* formerly GetNewsRCGroup() */
    /* Gets the name of the next group that we want to get article counts for.
       MSG_DisplaySubscribedGroup() should get called with this group before
       this call happens again. */
    string GetFirstGroupNeedingCounts();
 
    /* In response to a "news://host/" URL; this is called once for each group
     that was returned by MSG_GetNewsRCGroup(), after the NNTP GROUP
     command has been run.  It's also called whenever we actually visit the
     group (the user clicks on the newsgroup line), in case the data has
     changed since the initial passthrough.  The "nowvisiting" parameter
     is TRUE in the latter case, FALSE otherwise. */
    void DisplaySubscribedGroup(in nsINNTPNewsgroup newsgroup,
                                in long first_message, in long last_message,
                                in long total_messages,
                                in boolean visit_now);

    string GetFirstGroupNeedingExtraInfo();
    void SetGroupNeedsExtraInfo(in string name, in boolean needsExtraInfo);

  
    /* News servers work better if you ask for message numbers instead of IDs.
     So, the NNTP module asks us what the group and number of an ID is with
     this.  If we don't know, we return 0 for both.   If the pane is not a
     thead or message pane, this routine will fail.
    */
    void GetNewsgroupAndNumberOfID(in string message_id,
                                   out nsINNTPNewsgroup group,
                                   out unsigned long message_number);


    void SetPrettyName(in string name, in string prettyName);

	/* Write out the newsrc for this host right now.  In general, either
       MarkDirty() or WriteIfDirty() should be called instead. */
    void WriteNewsrc();

	/* Write out the newsrc for this host right now, if anything has changed
       in it. */
    void WriteIfDirty();
    
	/* Note that something has changed, and we need to rewrite the newsrc file
       for this host at some point. */
    void MarkDirty();
    
    attribute string newsRCFilename;

    nsINNTPNewsgroup FindGroup(in string name);
    nsINNTPNewsgroup AddGroup(in string name
                              /* , msg_GroupRecord *inGroupRecord */ );
    void RemoveGroupByName(in string name);
    void RemoveGroup(in nsINNTPNewsgroup group); 

    /* Name of directory to store newsgroup
       databases in.  This needs to have
       "/name" appended to it, and the
       whole thing can be passed to the XP_File
       stuff with a type of xpXoverCache.
    */
    readonly attribute string dbDirName;

    /* this should actually return a list of strings..how to do in XPIDL? */
    string GetGroupList();

};