gecko-dev/mailnews/base/public/nsIMsgFolder.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Netscape 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/NPL/
 *
 * 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 Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */
 
#include "nsISupports.idl"
#include "nsIFolder.idl"
#include "nsIMsgThread.idl"
#include "nsIMsgIncomingServer.idl"
#include "nsIFileSpec.idl"
#include "nsISupportsArray.idl"
#include "nsIMsgCopyServiceListener.idl"

%{ C++
#include "nsIMsgDatabase.h"
#include "nsMsgKeyArray.h"
%}

interface nsIMessage;
interface nsIMsgWindow;
interface nsIMsgDatabase;
interface nsMsgKeyArray;

interface nsIMsgFolderCacheElement;
interface nsAutoString;

[scriptable, uuid(85e39ff0-b248-11d2-b7ef-00805f05ffa5)]
interface nsIMsgFolder : nsIFolder {

  /* already exists in nsIFolder */
  /*	readonly attribute string name;   */
  /*	void SetName(in string name); */


  /* XXX should these 2 go on nsIFolder or nsICollection? */
  void AddUnique(in nsISupports element);
  void ReplaceElement(in nsISupports element, in nsISupports newElement);
  
  nsISimpleEnumerator getMessages();
	nsISimpleEnumerator getThreads();
  
	void startFolderLoading();
	void endFolderLoading();
  
	/* get new headers for db */
	void updateFolder(in nsIMsgWindow aWindow);
  
	nsIMsgThread getThreadForMessage(in nsIMessage message);
	boolean hasMessage(in nsIMessage message);
  
  nsIEnumerator getVisibleSubFolders();
	readonly attribute wstring prettiestName;

  /**
   * URL for this folder
   */
  readonly attribute string folderURL;

  /**
   * should probably move to the server
   */
	readonly attribute boolean deleteIsMoveToTrash;
  
  /**
   * should probably move to the server
   */
	readonly attribute boolean showDeletedMessages;

  /**
   * this folder's parent server
   */
  readonly attribute nsIMsgIncomingServer server;

  /**
   * is this folder the "phantom" server folder?
   */
  readonly attribute boolean isServer;
  readonly attribute boolean canSubscribe;
  readonly attribute boolean canFileMessages;

  /**
   * does this folder allow subfolders?
   * for example, newsgroups cannot have subfolders, and the INBOX
   * on some IMAP servers cannot have subfolders
   */
  readonly attribute boolean canCreateSubfolders;

  /**
   * can you change the name of this folder?
   * for example, newsgroups
   * and some special folders can't be renamed
   */
  readonly attribute boolean canRename;

  /**
   * the phantom server folder
   */
	readonly attribute nsIMsgFolder rootFolder;
  
	void OnCloseFolder ();
	void Delete ();

	void deleteSubFolders(in nsISupportsArray folders);
	void propagateDelete(in nsIMsgFolder folder, in boolean deleteStorage);
	void recursiveDelete(in boolean deleteStorage);

	void createSubfolder(in string folderName);
  nsIMsgFolder addSubfolder(in nsAutoString folderName);
  
  void compact();
  void emptyTrash();

  /**
   * change the name of the folder
   *
   * @param name the new name of the folder
   */
	void rename(in string name);
	void adopt(in nsIMsgFolder srcFolder, out unsigned long outPos);

  /**
   * looks in immediate children of this folder for the given name
   *
   * @param name the name of the target subfolder
   */
	boolean containsChildNamed(in string name);
	boolean isAncestorOf(in nsIMsgFolder folder);

	string generateUniqueSubfolderName(in string prefix,
                                     in nsIMsgFolder otherFolder);

	void updateSummaryTotals(in boolean force);
	void summaryChanged();
  /**
   * get the total number of unread messages in this folder,
   * or in all subfolders
   *
   * @param deep if true, descends into all subfolders and gets a grand total
   */  
	long getNumUnread(in boolean deep);

  /**
   * get the total number of messages in this folder,
   * or in all subfolders
   *
   * @param deep if true, descends into all subfolders and gets a grand total
   */  
	long getTotalMessages(in boolean deep);

	readonly attribute unsigned long expungedBytesCount;

  /**
   * can this folder be deleted?
   * for example, special folders cannot be deleted
   */
	readonly attribute boolean deletable;

  /**
   * should we be displaying recipients instead of the sender?
   * for example, in the Sent folder, recipients are more relevant
   * than the sender
   */
	readonly attribute boolean displayRecipients;

  /**
   * used to determine if it will take a long time to download all
   * the headers in this folder - so that we can do folder notifications
   * synchronously instead of asynchronously
   */
	boolean manyHeadersToDownload();

	readonly attribute boolean requiresCleanup;
	void clearRequiresCleanup();

  /**
   * this should go into a news-specific interface
   */
	readonly attribute boolean knowsSearchNntpExtension;
  
  /**
   * this should go into a news-specific interface
   */
	readonly attribute boolean allowsPosting;

	readonly attribute string relativePathName;

  /**
   * size of this folder (including headers??) on disk
   */
	readonly attribute unsigned long sizeOnDisk;

  /**
   * set the password for this folder (what is this used for?)
   */
	void rememberPassword(in string password);
	readonly attribute string rememberedPassword;
	boolean userNeedsToAuthenticateForFolder(in boolean displayOnly);
  	readonly attribute string username;
  	readonly attribute string hostname;

	void setFlag(in unsigned long flag);
	void clearFlag(in unsigned long flag);
	boolean getFlag(in unsigned long flag);

	void toggleFlag (in unsigned long flag);
	void onFlagChange (in unsigned long flag);
  
	readonly attribute unsigned long flags;

	nsIMsgFolder getFoldersWithFlag(in unsigned long flags,
                         in unsigned long resultsize, out unsigned long numFolders);

	void getExpansionArray(in nsISupportsArray expansionArray);

	void deleteMessages(in nsISupportsArray message,
                      in nsIMsgWindow msgWindow,
                      in boolean deleteStorage);

  void copyMessages(in nsIMsgFolder srcFolder, in nsISupportsArray messages,
                    in boolean isMove, in nsIMsgWindow msgWindow,
                    in nsIMsgCopyServiceListener listener);

  void copyFileMessage(in nsIFileSpec fileSpec, in nsIMessage msgToReplace,
                       in boolean isDraft, in nsIMsgWindow msgWindow,
                       in nsIMsgCopyServiceListener listener);

  void acquireSemaphore (in nsISupports semHolder);
  void releaseSemaphore (in nsISupports semHolder);
  boolean testSemaphore (in nsISupports semHolder);
  readonly attribute boolean locked;

	nsIMessage createMessageFromMsgDBHdr(in nsIMsgDBHdr msgDBHdr);
	void getNewMessages(in nsIMsgWindow aWindow);

  /**
   * write out summary data for this folder
   * to the given folder cache (i.e. panacea.dat)
   */
	void writeToFolderCache(in nsIMsgFolderCache folderCache);

  /**
   * the charset of this folder
   */
	attribute wstring charset;
	attribute unsigned long biffState;

  /**
   * the number of new messages since this folder was last visited
   */
	attribute long numNewMessages;

  /**
   * verbose description of the new messages in this folder
   */
	readonly attribute wstring newMessagesNotificationDescription;
  readonly attribute nsIMsgDatabase msgDatabase;

  /**
   * local path of this folder
   */
	attribute nsIFileSpec path;

	void markMessagesRead(in nsISupportsArray messages, in boolean markRead);
	void markAllMessagesRead();
	void markMessagesFlagged(in nsISupportsArray messages, in boolean markFlagged);

	nsIMsgFolder getChildWithURI(in string uri, in boolean deep);
};