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