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