1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2/* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6#include "nsISupports.idl" 7#include "nsIMsgFolder.idl" 8 9%{C++ 10#include "nsTArray.h" 11%} 12 13interface nsIMsgWindow; 14interface nsINntpIncomingServer; 15 16[ref] native nsMsgKeyArrayRef(nsTArray<nsMsgKey>); 17 18[scriptable, uuid(9a12c3a5-9de5-4c57-ace3-d51802b525a9)] 19interface nsIMsgNewsFolder : nsISupports { 20 readonly attribute AString unicodeName; 21 /**|rawName| is an 8-bit string to represent the name of a newsgroup used by 22 * a news server. It's offered for the convenience of callers so that they 23 * don't have to convert |unicodeName| to the server-side name when 24 * communicating with a news server. It's US-ASCII except for some 25 * 'stand-alone' Chinese news servers that use GB2312 for newsgroup names 26 * violating RFC 1036. For those servers, it's GB2312. However, it can be any 27 * other single and multibyte encoding in principle. The encoding of this 28 * string is stored in |nsINntpIncomingServer| because that's a server-wide 29 * property. 30 **/ 31 [noscript] readonly attribute ACString rawName; 32 readonly attribute nsINntpIncomingServer nntpServer; 33 attribute boolean saveArticleOffline; 34 35 /** 36 * @name Authentication methods 37 * NNTP authentication is slightly wonky, due to edge cases that are not seen 38 * in other protocols. Authentication is not necessary; if authentication is 39 * used, it could be configured on a per-group basis or even require only a 40 * username and not a password. 41 * 42 * Since passwords could be per-group, it is necessary to refer to passwords 43 * using the methods on this interface and not nsIMsgIncomingServer. Passwords 44 * for the server as a whole are found via the root folder. If the server is 45 * configured to use single sign-on (the default), asking any group for its 46 * password will result in the server's password, otherwise, each group stores 47 * its password individually. 48 * 49 * Due to this setup, most of the password management functions on 50 * nsIMsgIncomingServer do not correctly work. The only one that would affect 51 * the passwords stored on folders correctly is forgetPassword; using any 52 * other on a news server would result in inconsistent state. 53 * 54 * Before requesting either the username or password for authentication, it is 55 * first necessary to call getAuthenticationCredentials. If the method returns 56 * true, then groupUsername and groupPassword are appropriately set up for 57 * necessary authentication; if not, then authentication must be stopped. 58 */ 59 /// @{ 60 61 /** 62 * Gets the authentication credentials, returning if the results are valid. 63 * 64 * If mustPrompt is true, then the user will always be asked for the 65 * credentials. Otherwise, if mayPrompt is true, then the user will be asked 66 * for credentials if there are no saved credentials. If mayPrompt is false, 67 * then no prompt will be shown, even if there are no saved credentials. 68 * 69 * If this method returns true, then groupUsername and groupPassword will 70 * contain non-empty results that could be used for authentication. If this 71 * method returns false, then the values of groupUsername and groupPassword 72 * will be cleared if they had previously been set. This could happen if 73 * mustPrompt were true and the user decided to cancel the authentication 74 * prompt. 75 * 76 * Note that this method will be executed synchronously; if an async prompt 77 * is wanted, it is the responsibility of the caller to manage it explicitly 78 * with nsIMsgAsyncPrompter. 79 */ 80 bool getAuthenticationCredentials(in nsIMsgWindow aMsgWindow, 81 in bool mayPrompt, in bool mustPrompt); 82 83 /// The username that should be used for this group 84 attribute ACString groupUsername; 85 86 /// The password that should be used for this group 87 attribute ACString groupPassword; 88 89 /// Forgets saved authentication credentials permanently. 90 void forgetAuthenticationCredentials(); 91 /// @} 92 93 void moveFolder(in nsIMsgFolder aNewsgroupToMove, in nsIMsgFolder aRefNewsgroup, in int32_t aOrientation); 94 95 nsIMsgFolder addNewsgroup(in AUTF8String newsgroupName, in ACString setStr); 96 97 void setReadSetFromStr(in ACString setStr); 98 99 /// returns the server's default charset. 100 readonly attribute ACString charset; 101 102 readonly attribute ACString newsrcLine; 103 readonly attribute ACString optionLines; 104 readonly attribute ACString unsubscribedNewsgroupLines; 105 void SetNewsrcHasChanged(in boolean newsrcHasChanged); 106 void updateSummaryFromNNTPInfo(in long oldest, in long youngest, in long total); 107 void removeMessage(in nsMsgKey key); 108 [noscript] void removeMessages(in nsMsgKeyArrayRef aMsgKeys); 109 void cancelComplete(); 110 void cancelFailed(); 111 112 ACString getMessageIdForKey(in nsMsgKey key); 113 114 void getNextNMessages(in nsIMsgWindow aMsgWindow); 115 void notifyDownloadedLine(in string line, in nsMsgKey key); 116 void notifyFinishedDownloadinghdrs(); 117 118 /** 119 * Retrieves the database, but does not cache it in mDatabase. 120 * 121 * This is useful for operations that shouldn't hold open the database. 122 */ 123 nsIMsgDatabase getDatabaseWithoutCache(); 124 125 /** 126 * Requests that a message be canceled. 127 * 128 * Note that, before sending the news cancel, this method will check to make 129 * sure that the user has proper permission to cancel the message. 130 * 131 * @param aMsgHdr The header of the message to be canceled. 132 * @param aMsgWindow The standard message window object, for error dialogs. 133 */ 134 void cancelMessage(in nsIMsgDBHdr aMsgHdr, in nsIMsgWindow aMsgWindow); 135}; 136